Story 2731: Indigo functions rails - packet producer, broker invoke, envelope persistence

This walkthrough covers the functions half of Indigo (Epic-2624): the deterministic addressable_document_packet.v1 producer, the broker invoke onto the Indigo runtime, and persistence of the returned document_understanding.v1 envelope. Out of scope and unchanged here: the Indigo brain (pramaan-agents #2730), the Terraform runtime deploy (pramaan-infra), and app rendering.

Why this shape

1. Where things live

2. The producer validates what the consumer will reject

The consumer (agents/indigo/models.py) is sealed - extra="forbid", frozen, and it byte-matches every anchor against its page text on ingest. This repo mirrors those exact rules and runs them before the invoke, so a defective packet fails here, named, instead of costing a model call and surfacing as an opaque agent-side rejection:

PacketBuildError: packet for document <id> at extraction_version <id> failed the
ingest invariants: anchor sp1:doc-1:1:1:27-82 text does not byte-match page slice

Offsets come from documents.document_pages_v2, whose page text and block offsets are minted together by projection._with_offsets (page-relative, char_end exclusive) - which is why text[char_start:char_end] == block.text holds exactly. The legacy document_pages path is deliberately not a fallback: legacy OCR blocks carry no offsets, so a packet built from them could not satisfy the byte-match invariant. Such a document is skipped (skipped_not_addressable) rather than shipped with anchors we cannot stand behind.

3. AnchorKind: one enum home, and an honest gap

indigo-rfd §9 R1 leaves the AnchorKind set as "residue for the producer child ticket ... frozen in the same functions-side map spec, ONE enum home both repos cite". That home is src/shared/agent_contracts/indigo.py. The Document Map is Textract-layout derived, so the total map is:

The map is total: an unknown upstream kind raises rather than defaulting to block, because a new layout kind is a contract event both repos must see, not something to absorb and rediscover months later as degraded reading quality.

4. The matter frame carries relevance, never exposure

prune_frame_subset narrows our FrameOutput to the five relevance keys (frame_summary, core_dispute, parties, issues, theory_of_case), recursively dropping nulls, blank strings and empty lists. An entirely empty frame returns None - the block is omitted, never rendered empty (the consumer hard-rejects an empty frame).

5. Invoke rides the existing broker rails

agent_invoke.v1
  agent_key: indigo
  mode:      understand
  meta:      { run_id, firm_id, matter_id, batch_id }   ← tracing only
  input:     { packet }                                  ← the whole input

The runtime ARN is resolved per run from the SSM registry (/pramaan/{env}/agents/indigo/runtime-arn, roster constant AGENT_INDIGO) via the one canonical helper. No AGENT_RUNTIME_ARN_* env var: that N x M env matrix is the #2154/#2177 incident class, and a pinned ARN goes stale the moment the runtime redeploys. Tenant ids stay in meta and out of input - the packet carries no firm_id/matter_id, so nothing outside the sealed object can reach a prompt. Consent, cost-cap and RLS machinery are untouched. Observability reuses the approved AGENT_INVOKE_BUILD/AGENT_INVOKE_CALL spans; no new span name is minted, so no ADR-124 registry amendment is needed.

6. Failure discipline: two classes, two answers

Per §3.7 a failed panel or gate emits run.failed and no product effect at all, so status has no error arm. That makes "no effect seen" a failure, and a stream that ends with no terminal event a failure too - silence is never success. partial (rejects > 0 or pages omitted) is a real artifact, not a failure.

7. Storage: idempotent on the triple

Migration 0194 adds context.document_understandings. The idempotency key is deliberately wider than the insight brief's (firm_id, document_id):

UNIQUE (firm_id, document_id, extraction_version_id, prompt_version)

An envelope is only meaningful against the extraction it was read at (every anchor_id addresses that extraction's page text) and under the prompt that produced it. So a re-run of the same triple replaces its row in place, while a re-extraction or a prompt bump writes a new row - the two reads stay comparable instead of one silently destroying the other, which is how the gate reject-rate is measured per-PR.

RLS is firm isolation + staff-with-grant read, SELECT/INSERT/UPDATE only, DELETE revoked (derived, re-enrichable rows are never deleted).

8. Trigger and flag

The seat runs on the context-enrichment chain beside the Insight seat (context_embed, on the same card/carve-completion eligibility), so a minutes-scale read never rides the registration consumer's budget alongside Blake's passes.

INDIGO_UNDERSTANDING_ENABLED     default false   ← kill switch
INDIGO_UNDERSTANDING_MATTER_IDS  default ""      ← comma-separated allowlist; empty = all matters

Default OFF is required, not cautious: the seat invokes an AgentCore runtime that pramaan-agents #2730 is still building, so an enabled flag against an unregistered runtime would be an AgentRuntimeNotRegistered per document. Off, the seat is fully inert - it never resolves SSM, never invokes, never writes. The allowlist exists because staging should prove a paid per-document model pass on one real matter first. The kill switch wins over the allowlist, so an allowlist is never an accidental enable.

The document.understanding row in pramaan-agents' AgentEventType enum is in flight on #2730. This side is coded against the event-type string and the §3.7 payload shape, and the flag defaults off, so merge order does not matter.

9. Verification