Skip to content

Commit 68e5f80

Browse files
authored
🔎 Inspect a sealed artifact with the commands that inspect a run (#619)
* 🔎 Inspect a sealed artifact with the commands that inspect a run `xmd workflow status --artifact=<path.xmd>` and `xmd workflow history --artifact=<path.xmd>`. The same questions a retained run answers, asked of a file that left the machine which produced it. They are sibling lifecycle operations rather than one operation over a union. `inspect(runId)` addresses live lifecycle authority — something a caller may still advance, cancel or delete — and `inspectArtifact(path)` addresses immutable evidence somebody is holding. Widening one to accept either would make that difference a detail of a parameter. The Deno provider owns the container: it verifies the whole file through the existing reader before answering with any of it, and reaches no run store, lock, Workspace, definition reader or external provider. The CLI never imports the reader, so a host without the Deno provider gives the standard refusal and the grammar stays portable. History is one projection now. Authored source, cumulative forkability, inherited provenance and freezing moved to `projectHistory()` beside the provider-neutral contract, and both sources call it — a live journal table on one side, verified journal records on the other. Two mappings are how history quietly starts meaning different things depending on where it was read. The path is presentation. It heads the human output and appears nowhere in JSON, so two copies of one artifact are one answer. Artifact history JSON is an envelope because the identity and the frontier have nowhere else to go; retained history stays the bare array. `retrieval` is absent from an artifact snapshot as a fact rather than an omission — where a definition can be fetched from now is authority belonging to the machine that exported. Status and history take exactly one source. Neither named is a refusal showing both forms, both named is a refusal naming both, and a second `--artifact` is refused rather than letting the parser keep the last of two different files. `list` stays a registry of runs and refuses `--artifact` like any other action. I1 compares the artifact's answers field-for-field against the retained answers captured from the same run before it was exported through the real `workflow export`. I1b is the discriminating case for the frontier: the last event's root and the current pointer coincide in every ordinary run, so the run is edited from outside XMD to make them differ — reading one as the other fails it. I2 proves two paths give byte-identical JSON, I3 that both commands answer from a directory with no repository and an empty run store while the file and its directory stay untouched, I4 that a refused file presents nothing at all, and I5 the source grammar. DLC13 and C9 already hold the locality and entrypoint boundaries over the new modules. Refs #601 * 🔍 Read an artifact where nothing may be written beside it I2 was arranged but not complete. It copied the artifact to a second path and compared the answers, which proves the path is not part of identity — and proves nothing at all about the claim underneath it, that inspecting an artifact writes nothing. A directory that merely happened to stay clean is not a directory that could not have been written to. So the copy is inspected while its containing directory refuses new entries. A reader that opened the container for writing, or left a journal, a WAL or a lock next to it, cannot finish there at all. The refusal is proven before the assertions rather than assumed, because a host that quietly ignored the mode change would make every line after it a coincidence. Permissions are restored through this scope's teardown, registered inside the fixture's own removal so it runs first: a failing assertion still leaves the temporary tree removable. Status and history both still answer, the two paths give byte-identical JSON, the human heading names the path each caller supplied, and the file and its directory are unchanged afterwards. The `architecture.md` lifecycle excerpt now says what the surface is. It had drifted before this story — no fork lineage on the snapshot and no `export` — and it gains the artifact result types and the two sibling operations. The retained pair stays distinct, and the paragraph under it says why: a run ID names live lifecycle authority, a path names evidence somebody is holding, and `WorkflowArtifactSnapshot` extends the retained snapshot rather than restating it. Refs #601 * 🧱 Give an artifact snapshot no retrieval to leave unset The contract says an artifact carries no record of where its definition could be fetched from now. The type said otherwise. `WorkflowArtifactSnapshot` extended `WorkflowLifecycleSnapshot`, so `retrieval` was a valid key of it, and the whole exclusion rested on the Deno projection happening not to write one. A member a type admits is a member some caller will eventually set. So the shared shape is what both forms are. `WorkflowInspectionSnapshot` holds the record, the executions, the journal frontier, the current Workspace root and the fork lineage — everything true of the run itself. The retained-run snapshot alone adds `retrieval`, because where a definition can be fetched from now is a fact about the machine holding the run rather than about the run. The artifact snapshot alone adds which artifact answered and the boundary it was sealed at. Neither extends the other. The renderer had to say this too. `renderStatus` takes the shared shape and receives retrieval as its own argument, supplied by the retained caller and by nobody else — reading it off the value would have made the renderer expect a member half its callers cannot have. Structural assignability hid this: an optional member kept every call site compiling either way, which is exactly why the boundary needed stating rather than inferring. The regression is compile-time, because that is where the defect was. Three `Assert<false>` guards in the lifecycle inspection suite fail if `retrieval` becomes a key of the artifact snapshot or of the shared base, or stops being one of the retained snapshot. Putting the artifact snapshot back to extending the retained one fails the first of them, which is the exact mistake being fixed. Runtime behavior, the sibling operations, both JSON shapes and the retrieval-free projection are unchanged; the architecture excerpt and artifact spec now describe the relationship the types actually have. Refs #601 --------- Co-authored-by: Taras Mankovski <[email protected]>
1 parent 6717e86 commit 68e5f80

14 files changed

Lines changed: 1065 additions & 88 deletions

‎architecture.md‎

Lines changed: 66 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -527,31 +527,78 @@ type ExecutorAcquisition =
527527
| { readonly kind: "acquired"; readonly lock: ExecutorLock }
528528
| { readonly kind: "already-running" };
529529

530-
interface WorkflowLifecycleSnapshot {
530+
interface WorkflowForkLineage {
531+
readonly sourceRunId: string;
532+
readonly checkpointEventId: string;
533+
readonly checkpointWorkspaceRootId: string;
534+
}
535+
536+
interface WorkflowInspectionSnapshot {
531537
readonly record: WorkflowRunRecord;
532-
readonly retrieval?: DefinitionRetrieval;
533538
readonly executions: readonly DocumentExecutionRecord[];
534539
readonly journalFrontier?: {
535540
readonly eventId: string;
536541
readonly workspaceRootId: string;
537542
};
538543
readonly currentWorkspaceRootId: string;
544+
readonly lineage?: WorkflowForkLineage;
545+
}
546+
547+
interface WorkflowLifecycleSnapshot extends WorkflowInspectionSnapshot {
548+
readonly retrieval?: DefinitionRetrieval;
539549
}
540550

541551
interface WorkflowDeletion {
542552
readonly removed: readonly ("run-storage" | "provider-sessions")[];
543553
}
544554

555+
interface XmdArtifactFrontier {
556+
readonly sourceRunId: string;
557+
readonly finalEventId?: string;
558+
readonly currentWorkspaceRootId: string;
559+
}
560+
561+
interface WorkflowArtifactIdentity {
562+
readonly identity: string;
563+
readonly frontier: XmdArtifactFrontier;
564+
}
565+
566+
interface WorkflowArtifactSnapshot extends WorkflowInspectionSnapshot {
567+
readonly artifact: WorkflowArtifactIdentity;
568+
}
569+
570+
interface WorkflowArtifactHistory {
571+
readonly artifact: WorkflowArtifactIdentity;
572+
readonly entries: readonly WorkflowHistoryEntry[];
573+
}
574+
545575
interface WorkflowLifecycleApi {
546576
acquireExecutor(runId: string): Operation<Result<ExecutorAcquisition>>;
547577
inspect(runId: string): Operation<Result<WorkflowLifecycleSnapshot>>;
548578
list(): Operation<Result<readonly WorkflowLifecycleSnapshot[]>>;
549579
history(runId: string): Operation<Result<readonly WorkflowHistoryEntry[]>>;
580+
inspectArtifact(path: string): Operation<Result<WorkflowArtifactSnapshot>>;
581+
historyArtifact(path: string): Operation<Result<WorkflowArtifactHistory>>;
550582
cancel(runId: string): Operation<Result<WorkflowRunRecord>>;
551583
delete(runId: string): Operation<Result<WorkflowDeletion>>;
584+
export(request: WorkflowExportRequest): Operation<Result<WorkflowExportResult>>;
552585
}
553586
```
554587

588+
The two artifact operations are siblings of the retained-run pair rather than a
589+
widening of it. A run ID names live lifecycle authority in this host's storage;
590+
a path names immutable evidence somebody is holding, and no run has to exist for
591+
it to answer.
592+
593+
`WorkflowInspectionSnapshot` is what a run says about itself, and both forms are
594+
it. The retained snapshot alone adds `retrieval`, because where a definition
595+
could be fetched from now is a fact about the machine holding the run rather
596+
than about the run; the artifact snapshot alone adds which artifact answered and
597+
the boundary it was sealed at. Neither extends the other. That is what makes an
598+
artifact's exclusion of retrieval a property of the type rather than a habit of
599+
one projection: there is no such member to set. The path is never part of a
600+
result either, so two copies of one artifact answer identically.
601+
555602
The executor lock's public fields describe it and never validate it. Lifecycle
556603
transitions accept the exact object separately from their data
557604
through an adapter-private provider operation, just as Workspace transaction
@@ -659,6 +706,22 @@ only that surface. They never invoke canonical execution, read through replay,
659706
attach a Workspace, materialize a root, import a document, contact an Agent,
660707
process or external provider, or append.
661708

709+
Two sources answer the same questions. `inspect(runId)` and `history(runId)`
710+
address this host's retained storage; `inspectArtifact(path)` and
711+
`historyArtifact(path)` address one sealed `.xmd` file. They are siblings rather
712+
than one operation over a union: a run id names live lifecycle authority —
713+
something a caller may still advance, cancel or delete — while a path names
714+
immutable evidence that left the machine which produced it, and collapsing the
715+
two would make that difference a detail of a parameter. The artifact operations
716+
verify the whole container before answering with any of it, reach no run store,
717+
lock, Workspace, definition reader or external provider, and project the same
718+
snapshot and history values plus the artifact's identity and committed frontier.
719+
The path never enters the answer, so two copies of one artifact answer
720+
identically. History is shared: both sources run the same projection over
721+
ordered rows — authored source, cumulative forkability, inherited provenance —
722+
because two mappings are how history quietly starts meaning different things
723+
depending on where it was read.
724+
662725
The Deno provider first reads each retained database through its ordinary
663726
read-only connection. A host crash may leave a hot rollback journal: that is a
664727
healthy database one SQLite rollback away from the last committed state, but
@@ -3209,7 +3272,7 @@ Status is measured against main.
32093272
| `<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 |
32103273
| `<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 |
32113274
| 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, its total read-only verifier and `xmd workflow export` are built, Deno provider only — the inspection commands and the artifact-source fork remain unbuilt |
3275+
| 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, its total read-only verifier, `xmd workflow export` and artifact `status`/`history` are built, Deno provider only — the artifact-source fork remains unbuilt. Inspection is two sibling lifecycle operations, `inspectArtifact()` and `historyArtifact()`, taking a path rather than a run id: a run id names live lifecycle authority and a path names immutable evidence, so neither is a mode of the other. They reach no run store, lock, Workspace, definition reader or external provider, and the artifact path never enters the structural answer |
32133276
| 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 |
32143277
| 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 |
32153278
| 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 |

‎packages/cli/src/cli.ts‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,6 +7,7 @@
77
* xmd workflow start <document.md> [options]
88
* xmd workflow resume <run-id>
99
* xmd workflow status|history <run-id> [--json]
10+
* xmd workflow status|history --artifact=<path.xmd> [--json]
1011
* xmd workflow list [--status=<status>] [--json]
1112
*
1213
* A document reference is a path, optionally followed by `#` and one target

0 commit comments

Comments
 (0)