Skip to content

Commit cf48c97

Browse files
committed
💥 Replace invocation() with getExpansion() and derive expansion identity
## Motivation Durable workflow effects (#291) and workflow-owned worktrees (#293) need a deterministic identity for one logical evaluation of an authored element. Nothing in the engine could supply one: the only run-scoped identifier was the `BlockCounter`, which advances with however much has already run and so moves under retry and under a branch that did or did not execute. `invocation()` already answered the other half of the question — the authored name and where it was written — but only for function components, and only as a Component Api operation any middleware could intercept, while four families of durable record name are derived from it. ## Approach `getExpansion()` replaces `invocation()` with no alias, and covers Markdown component expansions as well. It answers with `{ id, name, position? }`. `id` is derived from the root document and the structural path that reached the element. Each step contributes a frame — root document, authored element, loop iteration, each item, projection — and the path is threaded explicitly as the digest so far, so extending it costs one hash. An element is placed by its own source path and offset rather than by an index into the list being expanded, which is what makes the derivation independent of how much ran before it. `Expansion` is delivered as a plain context value. An Effection context is identified by its name, and two descriptors built with the same name address the same context — the portability mechanism that lets a second instance of core read what the engine published, which is what a repository `.ts` component importing core from disk is while the compiled binary carries its own copy. A first attempt branded the value with a private class field; every Deno check stayed green while the compiled binary failed 2 of 10 documents. Every produced location string is unchanged, so `elicit:`, `prompt:`, `test:`, `testing:` and the web-form record names are byte-identical and existing journals still replay. ## Verification Tier XP (17 tests) discriminates each claim by the derivation it would kill, including two concurrent projections of one slot keeping their identifiers when completion order reverses, a projection operation constructed but never interpreted consuming no ordinal, and a context descriptor built elsewhere reading the engine's expansion — which moves the compiled-binary-only break into the fast suite. `deno task lint`, `check`, `test` (352), `check:jsr`, `tsc --project tsconfig.node.json`, `bun run test:bun` (2342), `deno task build` with the compiled-binary smoke over `packages/core/src`, and `git diff --check` are all green.
1 parent 7f03a08 commit cf48c97

19 files changed

Lines changed: 885 additions & 166 deletions

‎architecture.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -359,7 +359,7 @@ Status is measured against main.
359359
| --- | --- | --- |
360360
| `<PrintErrors>` / `printErrors(fn)` | prints failures | built on main |
361361
| `<Output>` region `output` mode | an undecided error fails the document execution | built on main |
362-
| `Expansion` / `getExpansion()` | describes the current logical element expansion | defined, unbuilt |
362+
| `Expansion` / `getExpansion()` | describes the current logical element expansion | built on main |
363363
| `useWorkflow()` / `getWorkflowRun()` | associates one document execution with a workflow run | defined, unbuilt |
364364
| `Git.revParse()` | verifies and resolves one Git revision expression contextually | defined, unbuilt |
365365
| `xmd workflow run` / `xmd workflow continue` | starts or continues a workflow run from the CLI | defined, unbuilt; ships with durable lookup |

‎packages/core/mod.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,6 @@ export type {
2525
ReturnsSchema,
2626
ComponentDefinition,
2727
ComponentFailure,
28-
ComponentInvocationMetadata,
2928
ComponentOrigin,
3029
PartialContent,
3130
ComponentRegistry,
@@ -61,7 +60,6 @@ export {
6160
persistent,
6261
content,
6362
retain,
64-
invocation,
6563
tryContent,
6664
hasCapture,
6765
capture,
@@ -97,6 +95,8 @@ export type { NameKind, SchemaVisitor } from "./src/schema-walk.ts";
9795

9896
export { hasContent, useContent } from "./src/content-context.ts";
9997
export { ContentError } from "./src/errors.ts";
98+
export { getExpansion } from "./src/expansion.ts";
99+
export type { Expansion } from "./src/expansion.ts";
100100
export { InvocationTeardownError, withInvocation } from "./src/invocation.ts";
101101
export type { Invocation } from "./src/invocation.ts";
102102
export { Sample } from "./src/sample-api.ts";

‎packages/core/src/agent/function-components.ts‎

Lines changed: 7 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -17,9 +17,11 @@
1717
import { Config } from "@executablemd/runtime";
1818
import { scoped } from "effection";
1919
import type { Operation } from "effection";
20-
import { content, hasContent, invocation } from "../component-api.ts";
20+
import { content, hasContent } from "../component-api.ts";
21+
import { getExpansion } from "../expansion.ts";
2122
import { parseDuration } from "../modifiers/timeout.ts";
22-
import type { ComponentInvocationMetadata, Json, PropsSchema } from "../types.ts";
23+
import type { Json, PropsSchema } from "../types.ts";
24+
import type { Expansion } from "../expansion.ts";
2325
import { Agent } from "./agent-api.ts";
2426
import type { PromptOptions, Session } from "./agent-api.ts";
2527
import { AgentProviders } from "./provider-api.ts";
@@ -76,7 +78,7 @@ function asString(value: Json | undefined): string | undefined {
7678
}
7779

7880
/** `path:line:column`, `line:column`, or `unknown` — the durable prompt key. */
79-
function formatLocation(metadata: ComponentInvocationMetadata): string {
81+
function formatLocation(metadata: Expansion): string {
8082
const position = metadata.position;
8183
if (!position) {
8284
return "unknown";
@@ -86,7 +88,7 @@ function formatLocation(metadata: ComponentInvocationMetadata): string {
8688
}
8789

8890
/**
89-
* Everything this component installs belongs to its own invocation, so the
91+
* Everything this component installs belongs to its own getExpansion, so the
9092
* engine dismantles content before the provider's resources. A failure from the
9193
* factory and a failure from the cleanup it installed are the same kind of
9294
* problem, and both stop the document — which is what an ordinary failure does.
@@ -200,7 +202,7 @@ export function* Prompt(props: Record<string, Json>): Operation<Json> {
200202
const throwOnError =
201203
props.throwOnError === true || (yield* AgentInternal.operations.promptFailurePolicy());
202204

203-
const location = formatLocation(yield* invocation());
205+
const location = formatLocation(yield* getExpansion());
204206
const ordinal = yield* AgentInternal.operations.promptOrdinal(location);
205207
const sequence = yield* AgentInternal.operations.nextPromptSequence();
206208

‎packages/core/src/component-api.ts‎

Lines changed: 0 additions & 16 deletions
Original file line numberDiff line numberDiff line change
@@ -24,7 +24,6 @@ import type {
2424
ComponentDefinition,
2525
ComponentElement,
2626
ComponentFailure,
27-
ComponentInvocationMetadata,
2827
ComponentRegistry,
2928
PartialContent,
3029
ErrorSegment,
@@ -105,14 +104,6 @@ export interface ComponentApi {
105104
* provider that rejects the call rather than letting it succeed.
106105
*/
107106
retain<T>(resource: () => Operation<T>): Operation<T>;
108-
/**
109-
* Where this function component was invoked (spec §5.5).
110-
*
111-
* Available only while the component runs. A nested invocation shadows it and
112-
* the enclosing one is restored on the way out, so what a component reads is
113-
* always its own call site.
114-
*/
115-
invocation(): Operation<ComponentInvocationMetadata>;
116107
/**
117108
* Render the invoking component's content, reporting a failure instead of
118109
* replacing the invocation with it.
@@ -210,12 +201,6 @@ export const Component: Api<ComponentApi> = createApi<ComponentApi>("Component",
210201
throw new Error("Component.retain() has no provider: not inside a component invocation.");
211202
},
212203
// deno-lint-ignore require-yield
213-
*invocation(): Operation<ComponentInvocationMetadata> {
214-
throw new Error(
215-
"Component.invocation() has no provider: not inside a function component invocation.",
216-
);
217-
},
218-
// deno-lint-ignore require-yield
219204
*tryContent(_slot?: string): Operation<PartialContent> {
220205
throw new Error(
221206
"Component.tryContent() has no provider: not inside a function component invocation.",
@@ -241,7 +226,6 @@ export const content: Operations<ComponentApi>["content"] = Component.operations
241226
export const hasContent: Operations<ComponentApi>["hasContent"] = Component.operations.hasContent;
242227
export const retain: Operations<ComponentApi>["retain"] = Component.operations.retain;
243228
export const registry: Operations<ComponentApi>["registry"] = Component.operations.registry;
244-
export const invocation: Operations<ComponentApi>["invocation"] = Component.operations.invocation;
245229
export const tryContent: Operations<ComponentApi>["tryContent"] = Component.operations.tryContent;
246230
export const hasCapture: Operations<ComponentApi>["hasCapture"] = Component.operations.hasCapture;
247231
export const capture: Operations<ComponentApi>["capture"] = Component.operations.capture;

‎packages/core/src/components/Elicit.ts‎

Lines changed: 6 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -39,14 +39,16 @@
3939

4040
import type { Operation } from "effection";
4141

42-
import { content, invocation } from "../component-api.ts";
42+
import { content } from "../component-api.ts";
43+
import { getExpansion } from "../expansion.ts";
4344
import {
4445
persistElicitation,
4546
questionFingerprint,
4647
refuseChangedQuestion,
4748
} from "../elicit-journal.ts";
4849
import { prepareElicitation, runPreparedElicitation } from "../elicit.ts";
49-
import type { ComponentInvocationMetadata, Json } from "../types.ts";
50+
import type { Json } from "../types.ts";
51+
import type { Expansion } from "../expansion.ts";
5052

5153
export const props = {
5254
type: "object",
@@ -76,7 +78,7 @@ export default function* Elicit(props: Record<string, Json>): Operation<Json> {
7678
const message = yield* content();
7779

7880
const identity = {
79-
location: formatLocation(yield* invocation()),
81+
location: formatLocation(yield* getExpansion()),
8082
fingerprint: questionFingerprint({ schema: prepared.schema, message }),
8183
};
8284

@@ -88,7 +90,7 @@ export default function* Elicit(props: Record<string, Json>): Operation<Json> {
8890
}
8991

9092
/** `path:line:column`, `line:column`, or `unknown` — the durable identity. */
91-
function formatLocation(metadata: ComponentInvocationMetadata): string {
93+
function formatLocation(metadata: Expansion): string {
9294
const position = metadata.position;
9395
if (!position) {
9496
return "unknown";

‎packages/core/src/execute.ts‎

Lines changed: 19 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -55,6 +55,7 @@ import {
5555
createBlockCounter,
5656
} from "./expand.ts";
5757
import type { BlockCounter } from "./expand.ts";
58+
import { extendPath } from "./expansion.ts";
5859
import {
5960
DocumentationError,
6061
documentationError,
@@ -506,6 +507,7 @@ function* runValueRoot(
506507
counter: BlockCounter,
507508
/** What this root emitted, held by the caller so a failure still finds it. */
508509
chunks: string[],
510+
path: string,
509511
): Operation<DocumentResult> {
510512
let produced: { value: Json } | undefined;
511513

@@ -530,6 +532,8 @@ function* runValueRoot(
530532
validatedProps,
531533
new Set(),
532534
counter,
535+
undefined,
536+
path,
533537
);
534538
for (const resolved of expanded) {
535539
const text = renderSegment(resolved);
@@ -579,6 +583,10 @@ function* documentWorkflow(props: Record<string, Json>): Workflow<DocumentResult
579583
// around the entire loop so all segments share it. Resources spawned by
580584
// `persist` blocks are retained in the eval scope until expansion
581585
// completes, then torn down.
586+
// The root document seeds the structural path, so the same authored element
587+
// in two different root documents is two different expansions (§5.6).
588+
const rootPath = extendPath("", { f: "doc", path: root.path });
589+
582590
const scopedExpansion: Operation<DocumentResult> = scoped(function* () {
583591
yield* Component.around({ env: () => rootEnv }, { at: "min" });
584592
// Structural preflight (spec §6.9, §6.10): a structurally invalid root
@@ -597,7 +605,7 @@ function* documentWorkflow(props: Record<string, Json>): Workflow<DocumentResult
597605
}
598606

599607
if (root.returns !== undefined) {
600-
return yield* runValueRoot(root, root.returns, validatedProps, counter, streamed);
608+
return yield* runValueRoot(root, root.returns, validatedProps, counter, streamed, rootPath);
601609
}
602610

603611
// A root declaring top-level <Output> buffers completely (spec §5.4):
@@ -615,6 +623,7 @@ function* documentWorkflow(props: Record<string, Json>): Workflow<DocumentResult
615623
undefined,
616624
undefined,
617625
selected,
626+
rootPath,
618627
);
619628
const text = selected.map(renderSegment).join("");
620629
// An empty buffered root emits no output event.
@@ -629,7 +638,15 @@ function* documentWorkflow(props: Record<string, Json>): Workflow<DocumentResult
629638
// has still handed over what it rendered — the root emits that before the
630639
// failure is reported, exactly as a buffered root does.
631640
for (const segment of root.bodySegments) {
632-
yield* expandSegments([segment], root.meta, validatedProps, new Set(), counter, produced);
641+
yield* expandSegments(
642+
[segment],
643+
root.meta,
644+
validatedProps,
645+
new Set(),
646+
counter,
647+
produced,
648+
rootPath,
649+
);
633650

634651
while (emittedThrough < produced.length) {
635652
const resolved = produced[emittedThrough];

0 commit comments

Comments
 (0)