<?xml version="1.0" encoding="utf-8"?>
<entry xmlns="http://www.w3.org/2005/Atom" xml:base="https://docs.spec-kitty.ai/adr/3.x/2026-08-16-1-pack-metadata-manifest-unification/">
  <id>https://docs.spec-kitty.ai/adr/3.x/2026-08-16-1-pack-metadata-manifest-unification/</id>
  <title>ADR: Unify Pack Metadata on a Single Manifest — Enumerated Constituents + Delegated Lineage</title>
  <updated>2026-08-16T00:00:00.000Z</updated>
  <author><name>Spec Kitty</name></author>
  <link rel="alternate" type="text/html" href="https://docs.spec-kitty.ai/adr/3.x/2026-08-16-1-pack-metadata-manifest-unification/"/>
  <summary>Unifies the two divergent pack manifests (counts vs enumerated) onto one canonical pack-manifest schema for every pack type, splitting authored lineage from generated constituents.</summary>
  <content type="html">&lt;h2 id=&quot;unify-pack-metadata-on-a-single-manifest--enumerated-constituents--delegated-lineage&quot;&gt;Unify Pack Metadata on a Single Manifest — Enumerated Constituents + Delegated Lineage&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Filename:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;2026-08-16-1-pack-metadata-manifest-unification.md&lt;/code&gt;&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Status:&lt;/strong&gt; Accepted&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Date:&lt;/strong&gt; 2026-08-16&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Deciders:&lt;/strong&gt; Maintainer&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Technical Story:&lt;/strong&gt; [#2467 (KEYSTONE — split built-in doctrine into packs + compound packs)], corroboration in [&lt;code dir=&quot;auto&quot;&gt;docs/plans/investigations/2026-08-pack-level-metadata-manifest.md&lt;/code&gt;]&lt;/p&gt;
&lt;hr&gt;
&lt;h2 id=&quot;context-and-problem-statement&quot;&gt;Context and Problem Statement&lt;/h2&gt;
&lt;p&gt;A pack — built-in, org, fetched, or a charter bundle — has no single, first-class
record of &lt;strong&gt;what it contains&lt;/strong&gt; and &lt;strong&gt;where it sits in a lineage&lt;/strong&gt; (its parent pack,
and, for a charter pack, which doctrine pack it accompanies). The information exists,
but scattered across &lt;strong&gt;two divergent manifest formats that disagree&lt;/strong&gt;:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;pack-manifest.yaml&lt;/code&gt; for org doctrine packs (&lt;code dir=&quot;auto&quot;&gt;src/specify_cli/doctrine/snapshot.py:157-180&lt;/code&gt;)
records per-kind &lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;artifact_counts&lt;/code&gt;&lt;/strong&gt; (&lt;code dir=&quot;auto&quot;&gt;:195-212&lt;/code&gt;) — counts, not an enumerated list —
carries &lt;strong&gt;no lineage&lt;/strong&gt;, and is &lt;strong&gt;not written&lt;/strong&gt; for the built-in or git-managed packs
(&lt;code dir=&quot;auto&quot;&gt;…/contracts/pack-layout.md:104-107&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;synthesis-manifest.yaml&lt;/code&gt; for charter/project bundles
(&lt;code dir=&quot;auto&quot;&gt;src/charter/synthesizer/manifest.py:46-112&lt;/code&gt;) records &lt;strong&gt;enumerated&lt;/strong&gt;
&lt;code dir=&quot;auto&quot;&gt;artifacts:[{kind, slug, path, content_hash}]&lt;/code&gt; plus a self-integrity &lt;code dir=&quot;auto&quot;&gt;manifest_hash&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;:107&lt;/code&gt;) — the “constituent parts” model — but exists only for charter bundles.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;The &lt;strong&gt;built-in reference pack that every org pack extends has no pack-level manifest at
all&lt;/strong&gt; — &lt;code dir=&quot;auto&quot;&gt;packs/built-in/*.graph.yaml&lt;/code&gt; carry only &lt;code dir=&quot;auto&quot;&gt;schema_version&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;generated_by&lt;/code&gt; headers.
Packs also have &lt;strong&gt;no stable identity&lt;/strong&gt; — they are keyed only by config &lt;code dir=&quot;auto&quot;&gt;name&lt;/code&gt;
(&lt;code dir=&quot;auto&quot;&gt;org_pack_config.py:166&lt;/code&gt;) — and a charter pack’s binding to its doctrine pack exists
only &lt;strong&gt;per-activation&lt;/strong&gt; as &lt;code dir=&quot;auto&quot;&gt;doctrine_pack_id&lt;/code&gt; (&lt;code dir=&quot;auto&quot;&gt;src/charter/activations.py:241&lt;/code&gt;), never
as one pack-level pointer.&lt;/p&gt;
&lt;p&gt;Left unaddressed, adding pack metadata would ship a &lt;strong&gt;third&lt;/strong&gt; format and deepen the
fragmentation. The decision is whether to &lt;strong&gt;unify&lt;/strong&gt; onto one schema or &lt;strong&gt;bridge&lt;/strong&gt; the two.&lt;/p&gt;
&lt;h2 id=&quot;decision-drivers&quot;&gt;Decision Drivers&lt;/h2&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;Single canonical authority&lt;/strong&gt; (charter governing principle): one description of a
pack, not two that drift.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Trust/verifiability:&lt;/strong&gt; a &lt;code dir=&quot;auto&quot;&gt;constituents[] + content_hash + manifest_hash&lt;/code&gt; inventory is
the substrate for the pack-trust / verified-distribution epic (#2539/#2543); two formats
means two things to sign and verify.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Cost asymmetry:&lt;/strong&gt; three of the required gaps (built-in manifest, stable &lt;code dir=&quot;auto&quot;&gt;pack_id&lt;/code&gt;, the
charter→doctrine binding) are net-new &lt;em&gt;regardless&lt;/em&gt; of unify-vs-bridge; bridge avoids only
the (mechanical, M-sized) migration of &lt;code dir=&quot;auto&quot;&gt;artifact_counts&lt;/code&gt; readers, at the permanent cost of
a two-format “add every field twice” tax.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Lossless dominance:&lt;/strong&gt; &lt;code dir=&quot;auto&quot;&gt;constituents[]&lt;/code&gt; strictly dominates &lt;code dir=&quot;auto&quot;&gt;artifact_counts&lt;/code&gt; — counts are
a derivable projection of the enumerated list, never the reverse.&lt;/li&gt;
&lt;/ul&gt;
&lt;h2 id=&quot;considered-options&quot;&gt;Considered Options&lt;/h2&gt;
&lt;ol&gt;
&lt;li&gt;&lt;strong&gt;Unify&lt;/strong&gt; — one &lt;code dir=&quot;auto&quot;&gt;pack-manifest&lt;/code&gt; schema for all pack types; enumerated constituents
canonical; counts become a derived view; &lt;code dir=&quot;auto&quot;&gt;synthesis-manifest.yaml&lt;/code&gt; becomes the charter
pack’s instance (via a charter profile block).&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;Bridge&lt;/strong&gt; — keep both formats, reconcile behind a read adapter, fill gaps per format.&lt;/li&gt;
&lt;/ol&gt;
&lt;h2 id=&quot;decision-outcome&quot;&gt;Decision Outcome&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Chosen: Unify.&lt;/strong&gt; Pack metadata is canonicalized on a single manifest schema for every
pack type, with two structural rules:&lt;/p&gt;
&lt;h3 id=&quot;1-one-schema-enumerated-constituents-charter-profile&quot;&gt;1. One schema, enumerated constituents, charter profile&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;constituents: [{kind, id, path, content_hash}]&lt;/code&gt; is the canonical inventory across all
packs. &lt;code dir=&quot;auto&quot;&gt;artifact_counts&lt;/code&gt; is &lt;strong&gt;retired&lt;/strong&gt; as stored state and, where still needed, computed
from &lt;code dir=&quot;auto&quot;&gt;constituents[]&lt;/code&gt;. The charter bundle’s extra fields (&lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;bundle_content_hash&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;synthesizer_version&lt;/code&gt;) live in an optional &lt;code dir=&quot;auto&quot;&gt;charter:&lt;/code&gt; &lt;strong&gt;profile
block&lt;/strong&gt; on the same schema — not a forked format. &lt;code dir=&quot;auto&quot;&gt;synthesis-manifest.yaml&lt;/code&gt; becomes the
charter pack’s generated manifest instance.&lt;/p&gt;
&lt;h3 id=&quot;2-two-files-authored-identitylineage-vs-generated-constituents&quot;&gt;2. Two files: authored identity/lineage vs generated constituents&lt;/h3&gt;
&lt;p&gt;The pack-layout contract forbids authors editing the generated manifest
(&lt;code dir=&quot;auto&quot;&gt;pack-layout.md:104&lt;/code&gt;). Rather than fence an authored block inside a generated file, the
manifest is split:&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;pack.yaml&lt;/code&gt;&lt;/strong&gt; (authored, hand-edited): &lt;code dir=&quot;auto&quot;&gt;pack_id&lt;/code&gt; (stable identity, minted once —
mirrors the &lt;code dir=&quot;auto&quot;&gt;mission_id&lt;/code&gt; ULID identity model), &lt;code dir=&quot;auto&quot;&gt;pack_version&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;parent_pack&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;accompanies_doctrine_pack&lt;/code&gt;, human metadata.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;pack.md&lt;/code&gt;&lt;/strong&gt; (authored): human-readable pack description.&lt;/li&gt;
&lt;li&gt;&lt;strong&gt;&lt;code dir=&quot;auto&quot;&gt;pack-manifest.yaml&lt;/code&gt;&lt;/strong&gt; (generated, never hand-edited): &lt;code dir=&quot;auto&quot;&gt;schema_version&lt;/code&gt;,
&lt;code dir=&quot;auto&quot;&gt;generated_by&lt;/code&gt;/&lt;code dir=&quot;auto&quot;&gt;generated_at&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;manifest_hash&lt;/code&gt;, &lt;code dir=&quot;auto&quot;&gt;constituents[]&lt;/code&gt;, and the optional
&lt;code dir=&quot;auto&quot;&gt;charter:&lt;/code&gt; profile block.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;This matches the operator’s original instinct (“a yaml + markdown pair accompanying a
pack”): the yaml+md are the &lt;em&gt;authored&lt;/em&gt; meta + human doc; the generated constituent record
is their verifiable sibling.&lt;/p&gt;
&lt;h3 id=&quot;3-lineage-delegates-never-re-walks&quot;&gt;3. Lineage delegates, never re-walks&lt;/h3&gt;
&lt;p&gt;&lt;code dir=&quot;auto&quot;&gt;parent_pack&lt;/code&gt; and &lt;code dir=&quot;auto&quot;&gt;accompanies_doctrine_pack&lt;/code&gt; &lt;strong&gt;store&lt;/strong&gt; edges only. Resolution order is
delegated to the existing &lt;code dir=&quot;auto&quot;&gt;src/charter/org_extends.py::resolve_extends_order&lt;/code&gt; (the
canonical &lt;code dir=&quot;auto&quot;&gt;extends:&lt;/code&gt; resolver with cycle detection). A second walker is prohibited — it
trips the C-005 no-parallel-resolver ratchet (&lt;code dir=&quot;auto&quot;&gt;org_extends.py:14-21&lt;/code&gt;).&lt;/p&gt;
&lt;h3 id=&quot;bridge-is-a-migration-tactic-not-a-destination&quot;&gt;Bridge is a migration tactic, not a destination&lt;/h3&gt;
&lt;p&gt;If the &lt;code dir=&quot;auto&quot;&gt;artifact_counts&lt;/code&gt;-reader migration proves deeper than expected, a bridge-then-unify
sequence is permitted &lt;strong&gt;only&lt;/strong&gt; with a stated unify-by release; two permanent formats are
not an acceptable end state.&lt;/p&gt;
&lt;h2 id=&quot;consequences&quot;&gt;Consequences&lt;/h2&gt;
&lt;p&gt;&lt;strong&gt;Positive.&lt;/strong&gt; One canonical pack description; a single signing/verification target for
#2539; stable &lt;code dir=&quot;auto&quot;&gt;pack_id&lt;/code&gt; for trust and lineage keys; the charter→doctrine binding gains a
pack-level home; every future field is added once.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Negative / cost.&lt;/strong&gt; Requires migrating &lt;code dir=&quot;auto&quot;&gt;artifact_counts&lt;/code&gt; readers to the derived view
(mechanical, M). Requires a new generator emitting &lt;code dir=&quot;auto&quot;&gt;pack-manifest.yaml&lt;/code&gt; for the built-in
pack from its per-kind &lt;code dir=&quot;auto&quot;&gt;*.graph.yaml&lt;/code&gt; &lt;code dir=&quot;auto&quot;&gt;nodes:&lt;/code&gt;. Introduces a &lt;code dir=&quot;auto&quot;&gt;pack_id&lt;/code&gt; minting/backfill
step for existing packs.&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Scope note.&lt;/strong&gt; This ADR fixes the &lt;em&gt;schema and split&lt;/em&gt;; it is the first deliverable of
#2467’s pack-manifest bullet and is sequenced with the pack-trust epic &lt;strong&gt;#2539&lt;/strong&gt; (the
manifest is the verifiability carrier). The broad “compound packs” work in #2467 remains a
separate slice. Implementation decomposes into: WP-core (unify schema + built-in writer),
WP-identity (&lt;code dir=&quot;auto&quot;&gt;pack_id&lt;/code&gt;), WP-lineage (&lt;code dir=&quot;auto&quot;&gt;parent_pack&lt;/code&gt; delegation + &lt;code dir=&quot;auto&quot;&gt;accompanies_doctrine_pack&lt;/code&gt;),
WP-split (authored vs generated files).&lt;/p&gt;
&lt;h2 id=&quot;delivery-status-this-slice&quot;&gt;Delivery status (this slice)&lt;/h2&gt;
&lt;p&gt;Mission &lt;code dir=&quot;auto&quot;&gt;pack-metadata-manifest-unification-01M052PT&lt;/code&gt; shipped this ADR’s schema and the
built-in-pack writer as a &lt;strong&gt;library-first slice&lt;/strong&gt;; it does not yet mean all 4 pack types
emit the unified manifest on disk. Read the ADR’s present tense above as “the decision,” not
“the rollout” — the rollout is partial by design, tracked here:&lt;/p&gt;
&lt;p&gt;&lt;strong&gt;Shipped:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;The unified &lt;code dir=&quot;auto&quot;&gt;pack-manifest&lt;/code&gt; schema and its models.&lt;/li&gt;
&lt;li&gt;The single hasher used for &lt;code dir=&quot;auto&quot;&gt;manifest_hash&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;content_hash&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;The built-in pack’s generated &lt;code dir=&quot;auto&quot;&gt;pack-manifest.yaml&lt;/code&gt; (via &lt;code dir=&quot;auto&quot;&gt;spec-kitty doctrine regenerate-graph&lt;/code&gt;) plus its authored &lt;code dir=&quot;auto&quot;&gt;pack.yaml&lt;/code&gt; / &lt;code dir=&quot;auto&quot;&gt;pack.md&lt;/code&gt;.&lt;/li&gt;
&lt;li&gt;The lineage adapter — delegates to &lt;code dir=&quot;auto&quot;&gt;org_extends.resolve_extends_order&lt;/code&gt;, fail-closed — and
its non-vacuous architectural ratchet guarding against a second walker.&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;counts_by_kind&lt;/code&gt; derive seam (a computed view over &lt;code dir=&quot;auto&quot;&gt;constituents[]&lt;/code&gt;).&lt;/li&gt;
&lt;li&gt;&lt;code dir=&quot;auto&quot;&gt;pack_version&lt;/code&gt; derive-else-fallback (authored value wins; generated value covers packs
without one).&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;&lt;strong&gt;Deferred to a future integration WP:&lt;/strong&gt;&lt;/p&gt;
&lt;ul&gt;
&lt;li&gt;Org and fetched pack manifest &lt;strong&gt;writers&lt;/strong&gt;, and the charter pack’s on-disk unified
emission — absorption ships as an &lt;strong&gt;in-memory bridge only&lt;/strong&gt;, to keep NFR-005 readers
green without forcing an on-disk format change yet.&lt;/li&gt;
&lt;li&gt;On-disk retirement of stored &lt;code dir=&quot;auto&quot;&gt;artifact_counts&lt;/code&gt; for org/fetched packs — still stored today
because &lt;code dir=&quot;auto&quot;&gt;_has_recognisable_pack_manifest&lt;/code&gt; requires the key.&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;pack_id&lt;/code&gt;-keyed resolver cutover and the retirement of name-based lookup — &lt;code dir=&quot;auto&quot;&gt;pack_id&lt;/code&gt;
ships now as an optional field plus a validator and an idempotent backfill, not yet the
resolution key.&lt;/li&gt;
&lt;li&gt;Wiring the lineage / &lt;code dir=&quot;auto&quot;&gt;accompanies_doctrine_pack&lt;/code&gt; resolvers and &lt;code dir=&quot;auto&quot;&gt;absorb_synthesis_manifest&lt;/code&gt;
into production callers.&lt;/li&gt;
&lt;li&gt;The &lt;code dir=&quot;auto&quot;&gt;accompanies_doctrine_pack&lt;/code&gt; cutover away from per-activation &lt;code dir=&quot;auto&quot;&gt;doctrine_pack_id&lt;/code&gt;.&lt;/li&gt;
&lt;/ul&gt;
&lt;p&gt;A downstream reader should not assume all 4 pack types already emit the unified manifest —
only the built-in pack does, as of this slice.&lt;/p&gt;</content>
</entry>
