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_getreportsrevision(served) andlatestRevision(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.
Public links and embeds are a person's
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.