Skip to content
bucker

Insight governance

A saved insight is a node (docs/insight-query.md) with a life. Agents author freely and in private; a person decides what everyone else sees. This page is the contract between the two: which act an edit is, what an approver reads, what freezes, what a public link serves and what no agent can do.

Everything here is product analytics, so every door runs behind the project's PA-01 gate (docs/product-analytics-gate.md): a project that has not enabled it answers the gate's refusal and stores nothing.

The life of an insight

            insights_create (draft)              insights_create (shared) / insights_update visibility: shared
  (nothing) ─────────────────────────▶ DRAFT ────────────────────────────────────────────────────▶ SHARED
              insight.draft, ALLOW       │  private, 90 days                insight.create, ASK        │
                                         │                                                              │ new node: insight.draft, ALLOW
                                         ▼                                                              │ (a draft revision beside the served one)
                                     ARCHIVED ◀── insight.archive ──────────────────────────────────────┤
                                                  (ALLOW for a draft, ASK when shared)                  │ promote N: insight.update, ASK
                                                                                                        ▼
                                                                                              a NEW revision, served
Act Class and decision What it is Inverse
insight.draft ELEVATED, ALLOW a new private draft; an edit of a draft; a draft revision of a shared insight the previous values
insight.create SENSITIVE, ASK sharing: a new insight proposed shared, or a draft made shared insight.archive
insight.update SENSITIVE, ASK promotion of a revision, a rename of a shared insight, a restore of an archived shared one promote the previous revision, as a new one
insight.archive ELEVATED, ALLOW for a draft; the shared fact floors a shared insight to ASK (derived SENSITIVE) removes it from lists; restorable for 90 days restore (archive: false)
insight.revoke ELEVATED, ALLOW ends a public link or embed; any holder of analytics:write, an agent included a person publishes again
insight.publish human-only, org:admin a public link or embed, at most 90 days insight.revoke
insight.delete human-only, org:admin removes a shared insight, its revisions and links none (archive is the reversible path)

The act is read from the difference between the desired state and the insight as it stands. There is no verb, so no argument can turn a draft into a share or an edit into a publish. A call that changes nothing is refused before anyone is asked (no_change).

Drafts are private

A draft belongs to its accountable principal: the person an act is for (the sponsor an agent acts on behalf of, else the caller). It is visible to that principal and to an agent acting for them (the delegation claim act.pid), and to nobody else: a third member, an admin and another organization's owner read "not found", the same as a missing id, on every door (insights_list, insight_get, the revisions route, an edit). There is no sponsor column; the rule is the delegation chain.

A draft lapses 90 days after its last edit unless it is shared. An expired draft is invisible at once (read on every read); archiveExpiredDrafts retires the rows in a scheduler pass.

What an approver reads

A share (insight.create) and a promotion (insight.update) carry, in the plan the approver is shown and the digest the yes is bound to:

  • the node, as one line of JSON, and the compiled statement (the F-05 specs over the rollup:pa_* datasets, one line each; a node the rollups cannot answer says why and cannot be shared);
  • a 30-day result preview, floored: it runs as a fixed in-process principal without pii:read, so the cohort floor answers for the floored class whoever asks, and the numbers are counts, never people, with cells under k withheld;
  • the trust check (PA-09): the lines that need reading and how many pass. A failing check is refused at the ask, before anyone is asked, until a person with project admin overrides it with a reason; the gate is read again at the apply from the stored rows without running anything;
  • the materialisation cost: for a funnel, the rows a day it adds to pa_funnel_daily (one per step), the trailing days it recomputes nightly and the history it backfills the first time; for anything else, nothing;
  • the boards that will show it (counts and names) and the alert rules that read it;
  • the author principal (the request's requester and the person it acts for) and the model the agent names (self-reported, shown as such).

The MCP Apps card (insight-card.ts) draws exactly these. The agent's reason, the insight's name and a board's name are the authors' words and are drawn as quoted, untrusted data.

What freezes, and what does not

The engine re-plans on the retry and requires the same digest as the approved plan. A relative range slides at midnight, a late event changes a count and a board is edited at any time, so none of those can be read twice and stay equal. The facts above are read once, frozen as a row of insight_results under a key of their own, and served from there for 48 hours: the ask and the retry see one plan, and an approver sees exactly what the plan says. An approval that outlives the freeze is re-planned and asks again; that is the rule ("any re-plan needs a new approval"), not a defect.

In practice an approval is good for 24 hours, the trust check's freshness, not 48: a retry later than that re-runs the check (its 7-day counts have moved), the digest changes and the call asks again. Whatever the approver reads is what the retry applies, or it applies nothing.

The trust check is not frozen: a person's override is the remedy for a failing check, so the gate is read live at the plan and again at the apply. The door runs the check only when none stands within the gate's 24 hours, so a retry reuses it. A re-run by someone else in between that changes the counts changes the digest.

The decision card shows only the first 900 characters of the plan and the approver's page the whole of it, so the fragment is ordered for reading: the act, the kind, the gate, the cost and the head of the preview come before the node, the statement and the ids (the digest is canonical, so order binds nothing).

A plan is shown pretty-printed and capped at 4,000 characters, so the node and the preview's numbers travel as one-line strings and the preview is the head of each list (compactEssence). A plan that still does not fit is refused PLAN_TOO_LARGE.

The revision a yes is bound to moves when the served revision, the newest revision, the visibility, the name, the description, the archived state or the number of ended links moves: an edit between the yes and the retry closes the request TARGET_CHANGED, unspent. A link published, a result cached or a trust check re-run does not move it.

Copy on write

AnalyticsInsight.node is the served node: every reader (insight_get, the funnel, retention and paths reads, the insight board widget, the analytics alert evaluator) reads it. It changes only when the served revision changes.

  • A new node on a draft replaces the draft's node and writes a revision.
  • A new node on a shared insight writes a draft revision (insight.draft) beside the served one. It is on its revision row alone; nothing a reader sees changes, however many are written.
  • Promoting revision N (insight.update) copies it to a new revision that carries the principal, the plan digest and the approval, and serves it. A restore is the same act. No revision is rewritten, and none is deleted except the oldest unserved ones past 100.
  • Every shared revision therefore names its principal and its plan digest. insight_get reports revision (served) and latestRevision (newest); they differ while a draft revision waits.

Saved funnels are kept warm

Applying insight.create or promoting a funnel registers it in materialised_funnels, keyed by the funnel's own hash (the node without its range), so one stream answers every range and two shared insights over one funnel share a row. The workers' pass fills pa_funnel_daily; from then the compiler reads it (source: materialised). Archiving the last shared insight that uses a row pauses it; sharing or restoring resumes it. Nothing already computed is deleted. A funnel the rollups cannot answer, one with an action step and one narrowed by a cohort are not registered, and the card says so.

insight.publish is human-only: a person on their own session with org:admin and a step-up. An agent, an OAuth-client person, a service, a delegation and a credential derived from a session are each refused, before anything is read. The link is 32 random bytes shown once; only its SHA-256 is stored. It lives at most 90 days (expiry is evaluated on read) and an insight holds at most five live links. A draft, an archived insight and another project's insight are not found.

A link serves the floored numbers of one shared, unarchived insight through the same fixed principal as the preview, so a cell under k is withheld whoever published it. It is read-only and returns the numbers, the range and the floor's statement, never the node, an id, a project, an organization or a person. An unknown, revoked, expired, archived, gate-shut or mismatched link is the same 404, and the door is rate-limited per address before the lookup. The dashboard page for a link is /share/insight/<token>; it reads GET /public/insights/:token.

insight.revoke only narrows, so any holder of analytics:write, an agent included, may end a link; it applies at once. Re-publishing is a person's act.

insight.delete removes a shared insight, its revisions and its links, is refused while an alert rule reads it, and writes an audit row listing the boards that showed it. A draft is archived, not deleted.

Doors

REST (routes-insights-write.ts, routes-insights-public.ts), each declaring its operation row in the route:

Route Act
POST …/analytics/insights insight.draft or insight.create
PATCH …/analytics/insights/:insight draft, share, promote, rename, archive or restore
POST …/insights/preview, POST …/insights/:insight/preview what the call would do and what an approver would read; a refusal is data. Give the write's own reason: the plan includes it
POST …/insights/revert-preview records the preview operation_revert needs for a stored inverse of insight.update
GET …/insights/:insight/revisions the ledger
GET …/insights/:insight/links, POST …/links/challenge, POST …/links, POST …/links/:link/revoke the links; publish is human-only
POST …/insights/:insight/delete insight.delete, human-only
GET /public/insights/:token the public read

MCP: insights_create and insights_update (held: configure_analytics, outside the live ceiling until the SG-059 review) and the reads of docs/insight-query.md; insight_get takes include: revisions and subscriptions. The share dialog's grants are the generic resource-grant routes (resource kind insight).

A write that needs a person answers 202 input_required (REST) or an input request (MCP) with the request to decide; the retry names it. The preview is its own route; there is no dry-run flag.

insight.update requires a preview. The registry row names insights_query_preview as the required preview, which estimates a node's cost and records nothing, so every door of this family records the engine's preview of the exact plan itself just before the write (ensureRequiredPreview). operation_revert does not: reverting a promotion, a rename or a restore of a shared insight is two calls, POST …/insights/revert-preview with the operation id and then operation_revert, by the same person. There is no MCP door for the first call yet, so such a revert is a dashboard (REST) act until the registry row drops requirePreview or the revert door previews its own inverse. Reverting a share, a draft edit or an archive needs no preview.

The public door is live, not frozen

A link runs the insight's node when it is read, through the result cache (6 hours for a daily node), with no QUERY_SCAN governor and a per-address limit before the lookup, and it counts a view. That keeps the page current; the cost is an unmetered read an address can repeat up to the limit. The dashboard snapshot link (MET-24) serves a frozen document instead. Which is right is an open question (see the work-package note).

Tenancy

The project comes from the path or the token and is authorized first; every statement names it. Another organization's owner and agent, another project's insight and another member's draft each find nothing, and a body never names an org or a project. The frozen facts are read and written by project. The registered funnel row carries the project.