Skip to content

Edition (EditionSnapshot)

Definition

An Edition — canonically an EditionSnapshot — is a sealed, attestable, point-in-time release of an Insight, like a signed git tag. It freezes an evidence manifest (the Blocks as they stood), snapshots the narrative and decision metadata, records the review and attestation, and content-hashes the whole thing for integrity. An Edition is the unit of accountability: it is what a reviewer signs, what resolves the triggering Signal, and what dispatches downstream decision effects. Where the Insight is the working repository, the Edition is the immutable record of a decision made from it.

Canonical schema: cortex/docs/spec/des-objects.yml:401. Runtime model: cortex/cortex/models/intelligence.py:652. All command logic lives in cortex/cortex/edition.py. Persistence: a UDS DAO over the shared Elasticsearch intelligence index under the edition_snapshot alias, id edn_ + 12 hex.

Lifecycle

status: pending_review → approved → attested, with archived.

  • create_edition (edition.py:319) — freezes every pinned Block of the Insight into the evidence_manifest (block id + digest + frozen mode), assigns a sequential edition_number, and sets status pending_review.
  • freeze_edition_for_attestation (edition.py:694) — verifies all manifest blocks are frozen, computes content_hash (_compute_edition_hash:195 over insight id + edition number + manifest + narrative + decision metadata), stamps frozen_at / frozen_by, and moves status to approved. Idempotent once a content hash exists.
  • attest_edition (edition.py:876) — requires a content hash and (unless the accountability pack allows self-close) approved status; builds an attestation record whose signature is the content hash, and once minimum_attesters is met moves status to attested. Attestation writes a Memory record, an attested event, auto-resolves the source Signal, and dispatches post-attestation decision effects.
  • request_edition_review (edition.py:1321) — requires a frozen Edition, creates a reviewer Task, and auto-advances the Insight draft → in_review.

Journey through the code

Entry wires are MCP create_edition, freeze_edition_for_attestation, attest_edition, the *_decision_tag tools, and request_edition_review; reads via REST GET /edition_snapshot/{uid} and GET /edition/diff. Each mutation reads the Edition, enforces the accountability-pack gates (_load_accountability_pack, fail-closed: minimum evidence, allowed decision templates, decision type, rationale, separation of duties), writes through _build_edition_update against the _EDITION_WRITABLE_FIELDS allowlist, then appends an InsightEvent (edition_created, revision_committed, attested, review_requested, decision_tagged) and advances the Insight head.

Data shape

Required (des-objects.yml:406): schema_version, insight_id, edition_number (≥ 1), head_event_id, evidence_manifest (≥ 1 entry, each block id + digest + mode = frozen), created_by.

Key computed / optional (intelligence.py:652): edition_id, content_hash + content_hash_attested, frozen_at / frozen_by, attested_at / attested_by, narrative_snapshot (executive summary, methodology, conclusion, decision statement, key risks, mitigations, next step, no-action rationale, system-of-record statement), decision_metadata (decision_type ∈ action | no_action | deferred, decision_template_id), decision_tags[], review + review_requests[], attestation (latest) + attestations[] (all), block_order[], previous_edition_id (revision chain). Storage: intelligence index, edition_snapshot alias; key queryable fields edition_id, insight_id, status, content_hash.

Invariants

  • Every manifest block is frozen with a valid digest before the Edition can be frozen (edition.py:769).
  • content_hash must exist before attestation (edition.py:920); content_hash_attested must equal it.
  • Separation of duties — the attester is not the author (edition.py:939) and the freezer is not the author, unless the pack permits self-close; only an actor.type = user may attest (agents must not). No double-attestation by the same attester.
  • No-action decisions require a no_action_rationale and ≥ 1 evidence block (edition.py:441).
  • edition_number is sequential per Insight; downstream decision effects require an attested Edition.
  • product.insight — an Edition belongs to an Insight (insight_id, captured at head_event_id) and is listed in the Insight's edition_ids[].
  • product.block — the evidence_manifest[] is the set of frozen Blocks; freezing an Edition freezes its Blocks.
  • product.signal — attestation auto-resolves the triggering Signal.
  • product.task — review/attest Tasks are created against an Edition and bidirectionally synced with its review.

Open questions

  • REST convergence. DES marks content_hash, content_hash_attested, frozen_at, frozen_by as critical additions still missing from canonical REST objects.yml; cortex implements them, but the wire schema lags.
  • attestation_type ([Q4]). DES says freeform; the runtime AttestationType enum constrains it to approval | review | acknowledgment — a divergence from the north star.
  • Status set. DES lists pending_review/approved/rejected/attested; the model has pending_review/approved/attested/archived (no rejected).

Realized by: component.cortex.decision-evidence, component.cortex.intelligence, component.cortex.investigation-lifecycle