Skip to content

Commit b952af6

Browse files
authored
📦 Seal one workflow run's evidence into a portable .xmd file (#610)
* Specify portable XMD workflow artifacts * 📝 Plan portable XMD artifact implementation * 📦 Seal one workflow run's evidence into a portable .xmd file Version 1 of the XMD artifact container, and the verifier every later artifact operation reads one through. A writer takes one complete detached snapshot — the artifact frontier, the run record, its executions and prior fork lineage, every journal row with its exact filtered record and provenance, every retained Workspace root, DOFS manifest and blob, the Repository and Worktree records, the suspension answers, the Agent session mappings, and the authenticated definition source closure — and writes it into one new SQLite file in one transaction, under the `XMDA` marker that tells it apart from a live run store on sight. Identity is a statement about the evidence rather than about the file. The canonical manifest enumerates every record and retained byte with its kind, its complete logical natural key as canonical JSON, its encoding, its length and its hash; page size, insertion order, free space and host path are outside it. Two containers holding the same snapshot derive the same identity and report different final-file digests, which is what makes one a semantic identity and the other a transport digest. The reader is total. Path admission, a read-only open, integrity, the family marker, the container version, the artifact version, the exact declared schema, every entry's declared length and hash, every parsed record and every reference between them, and only then the stored manifest and identity compared against the ones the accepted content produces. Nothing partial is ever returned, and the stored manifest is comparison evidence rather than the source of the inventory — a reader that trusted it would be asking a tampered file to describe its own tampering. Opening never writes: no journal mode, no migration, no pragma that writes, no sidecar, no lock. A refusal leaves the file byte- and mode-identical, including from a directory nobody may write to. `.xmd` and the versioned semantic contract are the public boundary. The marker, the two tables and the SQL stay behind a provider-internal barrel, and the suite asserts that neither published entrypoint names any of them. Two live Workspace parsers gained a rejection parameter and one pure DOFS manifest decoder was factored out of the row that holds it, so a detached copy is validated by the same code a live run uses without borrowing a sentence that tells an operator to restore a run from a backup. This story exposes no CLI, takes no executor lock, reads no live run store and creates no fork. Export, artifact inspection and the artifact-source fork remain unbuilt. Refs #602 * 🔒 Read the artifact's version before its shape, and hand back bytes nobody can edit Two corrections to the version-1 verifier, and the assertions that prove each. The artifact format version is now read between recognizing the container and comparing its declared schema, which is the order the specification already stated. A build that changed the format may have changed the tables carrying it, so a file declaring a format this one does not implement is an unsupported version whatever its tables look like — reporting it as a schema disagreeing with itself would be this build guessing about a version it cannot read. A container that is version 1 and is not shaped like one is still damage. Gate 10 now holds for every leaf, bytes included. `Object.freeze` refuses a typed array holding elements, this runtime offers no immutable `ArrayBuffer` to build one over, and a write-refusing `Proxy` fails `ArrayBuffer.isView`, `Buffer.from` and `TextDecoder.decode` — it would hand a caller bytes nothing can hash or read. So a byte leaf is a sealed original behind a frozen accessor that answers with a copy: replacing the member is refused, and writing into what a read returned lands on a copy nobody else holds. The consequence, which belongs to whoever owns the value contract, is that a byte member is a fresh array per read rather than a stable reference. C5 gains the undeclared trigger its frozen row named and had no evidence for, and the ordering evidence for its existing future-artifact row. C7 attempts both edits against every byte leaf and re-reads through the member rather than through the array it was handed. The matrix is still nine criteria. Both corrections were checked by breaking them: a plain freeze on a blob fails C7, and the old gate order fails C5 with the schema refusal where the version refusal is expected. Production parsing and return paths carry no type assertions. The inventory hands back identities as values rather than as text a decoder re-parsed and asserted about, the stored encoding narrows through a predicate, a stored identity parses through the shared JSON parser, the retained answer state narrows through a helper, and the content-entry builders let their annotated return type infer their literal encoding. The suites reach readonly values through Reflect and parse stored records through the shared object parser. Refs #602 * 🔑 Authenticate a retained answer against the wait it says it answers A retained answer named a journal event and nothing checked what that event was. The fixture proved how little that asks for: it pointed a consumed answer at a Git effect and a pending one at a coroutine Close, carried no suspension event at all, and the writer, its own read-back and both semantic tests took it. An answer is now held to the history it claims. The event it names has to be a retained suspension request; that request has to be for this wait, by the identity it carries twice over; the request is parsed rather than read, because it reached the journal through a public durable operation; its fingerprint is recomputed and compared, so a value judged against some other schema is not an answer to this one; the value is judged again by the schema that wait retained; and the row's state has to agree with the journal — consumed means the answer was published, pending means it was not, and a publication may not precede its request. Every one of those questions is asked with the live contracts. The request fingerprint had been written out twice already, once in delivery and once in the resume that consumes an answer; it is now one function beside the request parser, and all three callers share it. Judging the value is the same schema compilation a delivery and an `<Elicit>` use. Compiling that schema is an operation, so the semantic pass became one, and the reader now closes its connection after reading content into memory rather than holding it open through verification. That is what gate 6 always said, and the gates after it never needed the file again. The fixture carries two waits a run could really have reached — identifiers derived from the run and the durable position, a request and its publication for the answered one, a request alone for the wait the run is suspended at. C8 gains the refusals that hold each rule: an event that is not a request, a request for the other wait, a fingerprint from elsewhere, a value the schema rejects, a consumed row with nothing published, and a pending row whose answer already was. Six of those seven pass against the check this replaces. That is what the gap was. Refs #602 * 📍 Hold a published answer to the position a publication occupies A consumed row asked only whether *some* answer for its wait appeared later in the journal. Later is not a position: `suspendFor()` publishes the request and then the answer as two durable operations in one coroutine, back to back, so an answer sits at the request's index plus one in that coroutine and nowhere else. Anything looser accepts a publication belonging to another wait, in another coroutine, as evidence that this one ended. So a publication is now read at its durable position — recovered by counting each coroutine's settled yields, which is what an index is; a Close settles nothing and occupies none. Every publication has to name one wait in both the fields that carry it and stand directly behind that wait's request, whether or not a row claims it. A consumed row then has to find its publication exactly there, carrying a successful result, and carrying the value the row retains. The rich fixture had two faults behind that gap. Its suspension positions were guesses rather than the coroutine's own count, and it marked the run's own answered wait as inherited — which cannot happen, because fork creation copies journal rows and Workspace state and never the retained answer rows behind them. It now reads as the fork it claims to be: the source run's answered wait inherited whole with no row of its own, and this run's own answered and pending waits written by it. That first case is also why a publication no row claims is accepted when it stands behind its request, and refused when it does not. C8 gains the publication side: a mismatched identity, a publication moved to another coroutine, an unsuccessful result, a value that is not the one retained, a second publication for one wait, and one for a wait no request opened. The seven answer-row regressions stay. Removing the four new checks makes five of those six fall through to the manifest comparison instead of the semantic gate, which is the difference between recognizing tampered history and noticing the bytes moved. Refs #602 * 🧷 Ask a publication which wait it stands behind, and whether it carried a value Two ways a snapshot still reached a canonical identity it had not earned. A request describes its wait twice, in `name` and in `suspensionId`, and the structural pairing only compared the first. A pair agreeing about the name and disagreeing about the identity names two waits, and neither of them is one the other could have ended. Both fields are now compared, and asked of every publication rather than only of one some retained row points at — inherited history legitimately arrives as a request and its publication with no row behind them, which is exactly where nothing else was looking. A successful publication was read through `result.value ?? null`, so a result carrying no value at all read as a publication of `null`. A wait that ended with nothing and a wait whose retained answer is null are different histories, and one was standing in for the other. The member is now asked for by name, and only once it is there is the value compared. Both regressions are writer-path, because neither can be made by damaging a sealed file — a sealed file is one this build already accepted. They are snapshots offered to `writeXmdArtifact()`, which has to refuse them before a container exists, and the test asserts nothing is left at the destination. At the previous commit each of them is written and given an identity. Removing either check alone puts that back. Refs #602 * 🪪 Hold every wait this run opened to the position that names it A suspension identity is derived from the run and the exact durable position, and a caller supplies neither — that is what keeps two waits in one procedure from receiving each other's answer. The artifact never asked. A forged identity used consistently across a request, the answer published behind it and the row pointing at both agreed with itself, so every check that compared those three to each other passed, and the container was written and given a canonical identity. So every request the retained run authored is now re-derived from its own run id, its coroutine, and the index recovered by counting that coroutine's settled yields, and refused when the position names some other wait. It is asked of the request itself rather than of requests something else reaches: a wait nobody answered, standing at a position that cannot produce its name, is the same forgery with one fewer record in it. Only its own. An inherited request was derived in the run it came from, at that run's position, and re-deriving it against the child would refuse every fork for having a history — the fixture's inherited request and its publication stay accepted, and removing that exemption refuses the whole snapshot. Request shape is now checked where the request is read rather than only where a publication pairs with one, so a retained request that names its wait one way in `name` and another in `suspensionId` is refused whether or not anything stands behind it. Refs #602 * 🧪 Keep the artifact suite out of the one runtime that cannot load it Bun 1.3.14 has no `node:sqlite`, so the artifact suite does not fail there — it never loads. The subject is the Deno provider's container, which imports that module directly, so there is nothing to run under Bun and nothing a different test would recover. Recorded in a list of its own rather than in the shared Deno-only manifest, because the two state different facts. That one says a subject belongs to Deno. This one says a runtime is missing a built-in the subject imports — and Node has since gained `node:sqlite` unflagged and runs this file today, so folding the entry into the shared list would drop coverage Node is currently giving. Refs #602 --------- Co-authored-by: Taras Mankovski <[email protected]>
1 parent 37aa8a6 commit b952af6

20 files changed

Lines changed: 6401 additions & 55 deletions

‎architecture.md‎

Lines changed: 43 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -57,6 +57,11 @@ Existing documents and code get aligned to this section retroactively.
5757
| stale execution | an unfinished retained document execution found after acquiring the executor lock proves its previous workflow executor is gone |
5858
| inspection recovery coordination | provider-private cross-process exclusion between copying a crashed run's database-and-journal pair for inspection and opening the retained database write-capably for SQLite recovery; it grants no executor or lifecycle authority |
5959
| recovered inspection snapshot | an immutable lifecycle snapshot read from a private scratch copy after SQLite rolls that copy's hot journal back to the retained store's last committed state; the retained database and journal are not changed |
60+
| XMD artifact | one immutable portable evidence file with the `.xmd` extension, containing one workflow run's committed retained state at one artifact frontier together with its workflow definition source closure; it is neither a live run store nor authority to continue the source run |
61+
| artifact frontier | the exact committed lifecycle snapshot, journal boundary and current Workspace root an XMD artifact records |
62+
| workflow definition source closure | the exact root Markdown source and every source in its declared workflow component bundle, each authenticated against the immutable object identity in the workflow definition; retrieval metadata and a repository checkout are not part of the closure |
63+
| artifact manifest | the canonical versioned inventory of every semantic record and retained byte in one XMD artifact, excluding its own derived identity and physical container layout |
64+
| XMD artifact identity | the lowercase SHA-256 of an XMD artifact's artifact manifest; it identifies the evidence independently of its host path and physical encoding and is retained as the source identity of a history fork made from that artifact |
6065
| Workspace | the provider-neutral, run-owned environment that supplies retained filesystem, repository, process and working-directory capabilities to a workflow |
6166
| document filesystem | the files a document names in its own text, reached only through `API.Files`; distinct from the host paths the engine's own control plane reads |
6267
| Files provider | the installed implementation of `API.Files` for a document execution: the host provider under `xmd run`, a transaction-bound provider under a workflow run. There is no default, and no provider falls back to another |
@@ -747,6 +752,43 @@ visible. A suspended, interrupted or cancelled run with no root Close instead
747752
states that no canonical document outcome was recorded. Presentation never
748753
removes an event from the JSON contract or synthesizes a journal event.
749754

755+
### Portable XMD artifacts
756+
757+
An XMD artifact is a semantic export, not a renamed workflow-run database. The
758+
exporter reads one committed retained snapshot and writes a separate sealed
759+
container containing that snapshot, every retained Workspace root and byte it
760+
references, and the workflow definition source closure. Host paths, lock
761+
sidecars, rollback journals, open connections, retrieval metadata, credentials
762+
and provider-owned session directories do not cross the boundary. The initial
763+
container encoding is SQLite, but its tables and SQLite schema are private; the
764+
public compatibility boundary is the versioned XMD artifact contract.
765+
766+
The source run stays authoritative for itself and is never moved into the
767+
artifact. Export takes the executor lock before choosing the artifact frontier,
768+
so a live workflow executor makes export refuse and no later committed event can
769+
race the chosen frontier. Crash recovery, when required, operates on a private
770+
copy under inspection recovery coordination. Export performs no lifecycle
771+
transition and never changes the retained source.
772+
773+
Every command that consumes an XMD artifact opens it read-only and verifies its
774+
complete artifact manifest before returning any partial answer. That manifest
775+
determines the XMD artifact identity. A bytewise digest of the finished file is
776+
reported separately for transport verification; neither digest is a signature,
777+
so authenticity still comes from the channel that published the artifact.
778+
779+
An artifact grants inspection and history-fork input only. It is never resumed,
780+
answered, cancelled, deleted as a run, or admitted as the writable storage for
781+
an existing run ID. A history fork from it creates a new run ID, copies retained
782+
state rather than sharing pages, records the artifact identity with the source
783+
run and checkpoint, and passes through the same compatibility replay and
784+
forkability checks as a fork from local retained storage. The artifact remains
785+
byte-identical before, during and after the fork.
786+
787+
This split is the concurrency boundary between environments. Arbitrarily many
788+
hosts may inspect the same bytes or fork independently because none of them can
789+
advance the source identity. No SQLite lock can coordinate downloaded copies,
790+
and the design never asks one to.
791+
750792
### Cancellation control
751793

752794
Cancellation never reaches into a live document execution. The initial local
@@ -3167,6 +3209,7 @@ Status is measured against main.
31673209
| `<PullRequest>` | upserts one pull request of the selected checkout's current named branch, reconciled through the shared Git-host state machine: a required `title`, an optional positive-integer `number`, an optional `base` defaulting to the Repository's retained initial branch, an optional `draft`, and the rendered content as the body; it renders nothing and returns stable evidence through `as` — the filtered Repository identity, the provider's own stable pull-request identity, number, URL, open state, and the head and base SHAs of the snapshot it finished at. Without a number it creates one pull request for the head/base pair or adopts the compatible one an interrupted attempt left; with a number it brings that exact pull request's title, body, draft state and base to what the request says, records a no-op when they already match, and refuses a number belonging to another repository, opened from another head, or no longer open. It never pushes, never rewrites a head, and never reopens, merges or comments. The run must already hold its own successful `Git.Push` result for that exact Repository identity, head branch, destination ref and commit — proven by a scan of the whole successful history that requires each relevant record's natural key, inputs and result to describe one publication; a branch is published repeatedly, so the whole history is read in order and the run's last publication of that branch decides — an earlier one behind it is history rather than disagreement, while a last one naming another commit is the branch having moved on; that is conflicting, no relevant record at all is missing, and a relevant record that cannot be read whole is unreadable, each failing locally before the Git host is observed; the first adapter works over `github.com` on REST plus the two GraphQL draft transitions, selected from the private retained locator, credentialed from `GH_TOKEN`, then `GITHUB_TOKEN`, then the machine's own `gh` login, issuing each required mutation at most once per attempt and deciding the outcome by one observation, with the locator, endpoint, credential and payload confined to the per-invocation provider closure | built on the #295 stack, Deno provider only |
31683210
| `<Issue>` | asks one of two questions, decided by its own shape, through a boundary of its own rather than the Git host's. Self-closing with `url` reads that issue and binds `{ url, title, description, tags, assignee }`; paired with `title` upserts and binds exactly `{ url }`, its rendered content being the description. There is no `description` prop. Props are exactly `url`, `title`, optional `tags`, optional `assignee` and — on a read only — optional `provider`; no repository/token/label/milestone/project/comment/close or approval prop. Both forms render nothing. The form is decided before the tracker is read, before any provider is asked and before an `issue_effect` record exists, and that is where a mixed `url`+`title`, a read carrying content or `tags`/`assignee`, an upsert with no content, an upsert naming a `provider`, and an element that is neither are all refused. A read needs no tracker — its URL is the identity; an upsert requires the nearest lexical `<IssueTracker>` and takes its discriminator only from there. The tracker carries a credential-free `url` and an optional `provider`; the URL is canonicalized — a credential, a query and a fragment are refused rather than stripped — and a nested tracker replaces the whole value for its descendants, never merging members, with the enclosing one restored on leaving. It is composition data, not authority: the provider holds an adapter-private ceiling beside its credentials, admitted before it connects, so a target outside it sends nothing. One stable contextual operation, `executablemd.workflow.issue`, with `read(url, options)` and `upsert(issue, options)`; a provider is ordinary middleware around it, matching its own URLs without a discriminator and only its own name with one, independently per member, with no host-side resolution. Once middleware matches it owns the answer — it never delegates afterwards, and nothing catches its refusal to try somebody else — and a request everyone delegated reaches `NoIssueProvider` unchanged. `issue_effect` records an operation discriminator with the normalized request and result; both forms replay without reaching `IssueApi` and therefore without network access; only an upsert derives an idempotency key, from the operation, the canonical target and the run's own effect identity. Retention excludes credentials, endpoints, payloads, provider identities, origin markers and host paths. Observing, adopting, creating once and recovering an interrupted creation are the provider's, because they are knowledge about what a service can prove; title is never identity, and tags are a code-point-sorted set. The Deno workflow host installs configured GitHub middleware and installs none otherwise, so absence of configuration is fail-closed | built on the #296 stack; GitHub middleware, Deno host |
31693211
| workflow lifecycle inspection and control | reads status/list/history without advancing a run, recovering a private copy when a crashed source needs rollback; enforces the executor lock, refuses live cancellation, cancels non-live runs under that lock and deletes retained state | direct read-only inspection and control built on the #367 stack; coordinated recovered inspection built on the #513 stack, Deno provider only |
3212+
| XMD artifact export, inspection and fork source | seals one run's committed retained state, Workspace roots and workflow definition source closure into one immutable `.xmd` evidence file; opens that file read-only for status/history and admits continuation only by creating a new history fork whose lineage names the artifact identity | specified by `specs/xmd-artifact-spec.md`; the version-1 sealed container and its total read-only verifier are built, Deno provider only and provider-internal — export, the inspection commands and the artifact-source fork remain unbuilt |
31703213
| historical authored source | retains an authored durable operation's normalized `SourcePosition` beside its identity, and history parses it or refuses the entry | built on the #367 stack |
31713214
| history fork | creates a new run from one compatible checkpoint and retained Workspace root, under a new immutable definition and normalized props | built on the #368 stack, Deno provider only |
31723215
| workflow Agent session | a workflow document's `<Agent>` runs under a profile the host attaches only for a live or partial run: an empty host-owned working directory instead of any Workspace, checkout or caller path, no MCP servers, an empty requested native tool set, and `deny-all` with a permission path that denies every native request and fails the turn that asked without reaching the public permission chain. Within a run a session is identified by the Agent/Session expansion identity the engine derived — the authored name is descriptive, so two sibling `<Session name="review">` elements are two sessions — routed inside a placement bound to its element and good for one use, so a kept placement cannot be substituted for the next. The conversation is retained as a row in the run's own database with the provider, resolved agent command and policy fingerprint beside it as compatibility attributes. The order is provider creation, the provider's canonical tagged assertion, the mapping commit, then the first Prompt; occupancy of a provider key is not an assertion, the pre-commit window reconciles only from exactly one, and a missing, conflicting, replaced or ambiguous assertion is one explicit refusal that starts no replacement. Deleting a run removes the row with the run and the provider-session directory beside it, and reports the categories. The profile selects ACP-only capability explicitly — no native-launch advertisement and no client-native attachment advertisement — rather than inheriting the provider package's ordinary-run sets by omission, and it supplies no machine session coordinator, construction-route store or executable observer: a workflow session belongs to a run, and the machine-wide account describes a different thing entirely | built on the #302 stack, with the explicit ACP-only selection from #561; the portable proof that an adapter honours an empty tool set is tracked by #496 and does not widen the ceiling |
Lines changed: 180 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,180 @@
1+
/**
2+
* The canonical inventory an XMD artifact is identified by.
3+
*
4+
* The manifest names every semantic record and retained byte the artifact
5+
* holds, and nothing about the file those bytes ended up in. Page size, free
6+
* space, insertion order, index layout and the path the file was written to are
7+
* all outside it — which is what makes the identity a statement about the
8+
* evidence rather than about one encoding of it.
9+
*
10+
* ## Ordering is part of the version
11+
*
12+
* Entries are sorted by kind, then by the UTF-8 byte order of the canonical
13+
* JSON encoding of the entry's logical identity. An identity is that kind's
14+
* complete natural key as a JSON scalar or array, never a delimiter-joined
15+
* string: joining `("a/b", "c")` and `("a", "b/c")` produces the same text, and
16+
* two distinct records that collided into one manifest row would be an artifact
17+
* whose inventory is smaller than its content.
18+
*
19+
* ## Key order is core's, not a second comparator
20+
*
21+
* Canonical JSON here is `canonicalize()` followed by `JSON.stringify`, exactly
22+
* as every other identity in this repository spells it. Restating the ordering
23+
* rule with a comparator of this module's own would be a second definition of
24+
* canonical JSON that could drift from the first.
25+
*/
26+
27+
import { createHash } from "node:crypto";
28+
import { Buffer } from "node:buffer";
29+
import { canonicalize } from "@executablemd/core";
30+
import type { Json } from "@executablemd/durable-streams";
31+
import type {
32+
XmdArtifactContentEntry,
33+
XmdArtifactManifestEntryV1,
34+
XmdArtifactManifestV1,
35+
} from "./types.ts";
36+
37+
/** The artifact manifest version this build produces and reads. */
38+
export const XMD_ARTIFACT_MANIFEST_VERSION = 1;
39+
40+
/**
41+
* What the artifact identity is a hash *of*, beyond the manifest bytes.
42+
*
43+
* Domain separation, so the same bytes appearing as some other structure's
44+
* canonical encoding cannot be presented as an artifact identity.
45+
*/
46+
export const XMD_ARTIFACT_IDENTITY_DOMAIN = "xmd-artifact\0v1\0";
47+
48+
const encoder = new TextEncoder();
49+
50+
/** The compact canonical JSON encoding of a value, as UTF-8 bytes. */
51+
export function canonicalJsonBytes(value: Json): Uint8Array {
52+
return encoder.encode(canonicalJsonText(value));
53+
}
54+
55+
/** The compact canonical JSON encoding of a value, as text. */
56+
export function canonicalJsonText(value: Json): string {
57+
const text = JSON.stringify(canonicalize(value));
58+
if (typeof text !== "string") {
59+
throw new TypeError("an artifact manifest admits only JSON values");
60+
}
61+
return text;
62+
}
63+
64+
/** The lowercase SHA-256 of some bytes. */
65+
export function sha256Hex(content: Uint8Array): string {
66+
return createHash("sha256").update(content).digest("hex");
67+
}
68+
69+
/** The manifest row one accepted entry produces. */
70+
export function manifestEntry(entry: XmdArtifactContentEntry): XmdArtifactManifestEntryV1 {
71+
return Object.freeze({
72+
kind: entry.kind,
73+
identity: entry.identity,
74+
encoding: entry.encoding,
75+
length: entry.content.byteLength,
76+
sha256: sha256Hex(entry.content),
77+
});
78+
}
79+
80+
/** Two byte strings in UTF-8 order, which is `Buffer.compare` on their bytes. */
81+
function compareBytes(left: Uint8Array, right: Uint8Array): number {
82+
return Buffer.compare(Buffer.from(left), Buffer.from(right));
83+
}
84+
85+
/**
86+
* The canonical sort key of one entry: its kind, then its identity.
87+
*
88+
* Both compared as UTF-8 bytes rather than as JavaScript strings, because `<`
89+
* on strings compares UTF-16 code units and orders a supplementary character
90+
* before some of the ones that precede it in UTF-8.
91+
*/
92+
function compareEntries(
93+
left: XmdArtifactManifestEntryV1,
94+
right: XmdArtifactManifestEntryV1,
95+
): number {
96+
const kinds = compareBytes(encoder.encode(left.kind), encoder.encode(right.kind));
97+
if (kinds !== 0) {
98+
return kinds;
99+
}
100+
return compareBytes(canonicalJsonBytes(left.identity), canonicalJsonBytes(right.identity));
101+
}
102+
103+
/** The key a `(kind, identity)` pair is unique under. */
104+
export function entryKey(kind: string, identity: Json): string {
105+
return `${JSON.stringify(kind)} ${canonicalJsonText(identity)}`;
106+
}
107+
108+
/** One artifact's canonical manifest, its bytes, and the identity they derive. */
109+
export interface XmdArtifactManifestBuild {
110+
readonly manifest: XmdArtifactManifestV1;
111+
/** Compact canonical JSON as UTF-8, with no byte-order mark and no newline. */
112+
readonly bytes: Uint8Array;
113+
readonly identity: string;
114+
/** The entries in canonical manifest order, with their content. */
115+
readonly ordered: readonly XmdArtifactContentEntry[];
116+
}
117+
118+
/**
119+
* Build the manifest one set of accepted entries produces.
120+
*
121+
* `duplicate` is raised by whoever called: the writer is refusing its own
122+
* caller's snapshot and the reader is refusing a file, and those are different
123+
* conditions with different diagnostics even though the arithmetic is the same.
124+
*/
125+
export function buildXmdArtifactManifest(
126+
entries: readonly XmdArtifactContentEntry[],
127+
duplicate: (kind: string) => never,
128+
): XmdArtifactManifestBuild {
129+
const seen = new Set<string>();
130+
const rows: Array<{ row: XmdArtifactManifestEntryV1; entry: XmdArtifactContentEntry }> = [];
131+
for (const entry of entries) {
132+
const key = entryKey(entry.kind, entry.identity);
133+
if (seen.has(key)) {
134+
duplicate(entry.kind);
135+
}
136+
seen.add(key);
137+
rows.push({ row: manifestEntry(entry), entry });
138+
}
139+
rows.sort((left, right) => compareEntries(left.row, right.row));
140+
141+
const manifest: XmdArtifactManifestV1 = Object.freeze({
142+
version: XMD_ARTIFACT_MANIFEST_VERSION,
143+
entries: Object.freeze(rows.map((each) => each.row)),
144+
});
145+
const bytes = canonicalJsonBytes(manifestToJson(manifest));
146+
return Object.freeze({
147+
manifest,
148+
bytes,
149+
identity: deriveXmdArtifactIdentity(bytes),
150+
ordered: Object.freeze(rows.map((each) => each.entry)),
151+
});
152+
}
153+
154+
/**
155+
* The manifest as a plain JSON value.
156+
*
157+
* An interface has no index signature, so the manifest is written out member by
158+
* member rather than asserted into `Json`. Doing it here is also what keeps the
159+
* encoded shape and the declared shape one decision.
160+
*/
161+
export function manifestToJson(manifest: XmdArtifactManifestV1): Json {
162+
return {
163+
version: manifest.version,
164+
entries: manifest.entries.map((entry) => ({
165+
kind: entry.kind,
166+
identity: entry.identity,
167+
encoding: entry.encoding,
168+
length: entry.length,
169+
sha256: entry.sha256,
170+
})),
171+
};
172+
}
173+
174+
/** The lowercase SHA-256 of the domain prefix followed by the manifest bytes. */
175+
export function deriveXmdArtifactIdentity(manifestBytes: Uint8Array): string {
176+
return createHash("sha256")
177+
.update(XMD_ARTIFACT_IDENTITY_DOMAIN, "utf8")
178+
.update(manifestBytes)
179+
.digest("hex");
180+
}

0 commit comments

Comments
 (0)