@aftertext/runtime 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (71) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +31 -2
  3. package/dist/create-runtime-state.d.ts +14 -0
  4. package/dist/create-runtime-state.d.ts.map +1 -0
  5. package/dist/create-runtime-state.js +18 -0
  6. package/dist/create-runtime-state.js.map +1 -0
  7. package/dist/execution/advance.d.ts +37 -0
  8. package/dist/execution/advance.d.ts.map +1 -0
  9. package/dist/execution/advance.js +196 -0
  10. package/dist/execution/advance.js.map +1 -0
  11. package/dist/execution/choice.d.ts +30 -0
  12. package/dist/execution/choice.d.ts.map +1 -0
  13. package/dist/execution/choice.js +58 -0
  14. package/dist/execution/choice.js.map +1 -0
  15. package/dist/execution/cursor.d.ts +78 -0
  16. package/dist/execution/cursor.d.ts.map +1 -0
  17. package/dist/execution/cursor.js +59 -0
  18. package/dist/execution/cursor.js.map +1 -0
  19. package/dist/execution/errors.d.ts +27 -0
  20. package/dist/execution/errors.d.ts.map +1 -0
  21. package/dist/execution/errors.js +36 -0
  22. package/dist/execution/errors.js.map +1 -0
  23. package/dist/execution/expression.d.ts +50 -0
  24. package/dist/execution/expression.d.ts.map +1 -0
  25. package/dist/execution/expression.js +159 -0
  26. package/dist/execution/expression.js.map +1 -0
  27. package/dist/execution/memory-queries.d.ts +20 -0
  28. package/dist/execution/memory-queries.d.ts.map +1 -0
  29. package/dist/execution/memory-queries.js +83 -0
  30. package/dist/execution/memory-queries.js.map +1 -0
  31. package/dist/execution/navigate.d.ts +23 -0
  32. package/dist/execution/navigate.d.ts.map +1 -0
  33. package/dist/execution/navigate.js +32 -0
  34. package/dist/execution/navigate.js.map +1 -0
  35. package/dist/execution/result.d.ts +50 -0
  36. package/dist/execution/result.d.ts.map +1 -0
  37. package/dist/execution/result.js +2 -0
  38. package/dist/execution/result.js.map +1 -0
  39. package/dist/execution/variant.d.ts +33 -0
  40. package/dist/execution/variant.d.ts.map +1 -0
  41. package/dist/execution/variant.js +34 -0
  42. package/dist/execution/variant.js.map +1 -0
  43. package/dist/index.d.ts +21 -0
  44. package/dist/index.d.ts.map +1 -0
  45. package/dist/index.js +14 -0
  46. package/dist/index.js.map +1 -0
  47. package/dist/reader/scene-memory.d.ts +15 -0
  48. package/dist/reader/scene-memory.d.ts.map +1 -0
  49. package/dist/reader/scene-memory.js +23 -0
  50. package/dist/reader/scene-memory.js.map +1 -0
  51. package/dist/reader/variant-memory.d.ts +42 -0
  52. package/dist/reader/variant-memory.d.ts.map +1 -0
  53. package/dist/reader/variant-memory.js +48 -0
  54. package/dist/reader/variant-memory.js.map +1 -0
  55. package/dist/state/navigation-state.d.ts +9 -0
  56. package/dist/state/navigation-state.d.ts.map +1 -0
  57. package/dist/state/navigation-state.js +2 -0
  58. package/dist/state/navigation-state.js.map +1 -0
  59. package/dist/state/reader-state.d.ts +15 -0
  60. package/dist/state/reader-state.d.ts.map +1 -0
  61. package/dist/state/reader-state.js +2 -0
  62. package/dist/state/reader-state.js.map +1 -0
  63. package/dist/state/runtime-state.d.ts +16 -0
  64. package/dist/state/runtime-state.d.ts.map +1 -0
  65. package/dist/state/runtime-state.js +2 -0
  66. package/dist/state/runtime-state.js.map +1 -0
  67. package/dist/state/story-state.d.ts +14 -0
  68. package/dist/state/story-state.d.ts.map +1 -0
  69. package/dist/state/story-state.js +2 -0
  70. package/dist/state/story-state.js.map +1 -0
  71. package/package.json +38 -4
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 z0rimo
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,32 @@
1
- # Temporary Holding Version
1
+ # `@aftertext/runtime`
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ Pure narrative execution for compiled AfterText `StoryDocument` values,
4
+ including story state, reader memory, choices, variants, and navigation.
5
+
6
+ > v0.1 foundation: the public API is early and may change.
7
+
8
+ ## Install
9
+
10
+ ```sh
11
+ npm install @aftertext/runtime @aftertext/compiler
12
+ ```
13
+
14
+ ## Usage
15
+
16
+ ```ts
17
+ import { compile } from "@aftertext/compiler";
18
+ import { advance, createRuntimeState, INITIAL_CURSOR } from "@aftertext/runtime";
19
+
20
+ const { document } = compile("@scene start\n\nHello.\n");
21
+ const state = createRuntimeState(document);
22
+ const step = advance(document, state, INITIAL_CURSOR);
23
+
24
+ console.log(step.result);
25
+ ```
26
+
27
+ Runtime transitions are synchronous and non-mutating. The runtime consumes the
28
+ compiler-owned AST and does not parse AfterText source.
29
+
30
+ ## License
31
+
32
+ MIT
@@ -0,0 +1,14 @@
1
+ import type { StoryDocument } from "@aftertext/compiler";
2
+ import type { RuntimeState } from "./state/runtime-state.js";
3
+ /**
4
+ * Builds the initial `RuntimeState` for a compiled `StoryDocument`.
5
+ *
6
+ * `navigation.sceneId` is taken directly from the compiler's normalized
7
+ * `document.entryScene` — the runtime never guesses or re-derives an entry
8
+ * scene. `story` is a fresh shallow copy of `document.initialState`, so
9
+ * later mutating the returned runtime state can never alter the compiler's
10
+ * output (every allowed state value is itself an immutable primitive, so a
11
+ * shallow copy is already a full copy).
12
+ */
13
+ export declare function createRuntimeState(document: StoryDocument): RuntimeState;
14
+ //# sourceMappingURL=create-runtime-state.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"create-runtime-state.d.ts","sourceRoot":"","sources":["../src/create-runtime-state.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAE7D;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,aAAa,GAAG,YAAY,CAMxE"}
@@ -0,0 +1,18 @@
1
+ /**
2
+ * Builds the initial `RuntimeState` for a compiled `StoryDocument`.
3
+ *
4
+ * `navigation.sceneId` is taken directly from the compiler's normalized
5
+ * `document.entryScene` — the runtime never guesses or re-derives an entry
6
+ * scene. `story` is a fresh shallow copy of `document.initialState`, so
7
+ * later mutating the returned runtime state can never alter the compiler's
8
+ * output (every allowed state value is itself an immutable primitive, so a
9
+ * shallow copy is already a full copy).
10
+ */
11
+ export function createRuntimeState(document) {
12
+ return {
13
+ story: { ...document.initialState },
14
+ reader: { visitedScenes: {}, seenVariants: {} },
15
+ navigation: { sceneId: document.entryScene }
16
+ };
17
+ }
18
+ //# sourceMappingURL=create-runtime-state.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"create-runtime-state.js","sourceRoot":"","sources":["../src/create-runtime-state.ts"],"names":[],"mappings":"AAGA;;;;;;;;;GASG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAuB;IACxD,OAAO;QACL,KAAK,EAAE,EAAE,GAAG,QAAQ,CAAC,YAAY,EAAE;QACnC,MAAM,EAAE,EAAE,aAAa,EAAE,EAAE,EAAE,YAAY,EAAE,EAAE,EAAE;QAC/C,UAAU,EAAE,EAAE,OAAO,EAAE,QAAQ,CAAC,UAAU,EAAE;KAC7C,CAAC;AACJ,CAAC"}
@@ -0,0 +1,37 @@
1
+ import type { StoryDocument } from "@aftertext/compiler";
2
+ import type { RuntimeState } from "../state/runtime-state.js";
3
+ import { type ExecutionCursor } from "./cursor.js";
4
+ import type { ExecutionStep } from "./result.js";
5
+ export interface AdvanceOptions {
6
+ /**
7
+ * Overrides the internal step-budget default — intended for tests that
8
+ * need to deterministically exercise step-limit exhaustion without
9
+ * constructing a pathologically large scene. Not a specification-level
10
+ * constant (docs/PROJECT_SPEC.md Section 17.12 deliberately commits to
11
+ * no numeric default).
12
+ */
13
+ readonly stepBudget?: number;
14
+ }
15
+ /**
16
+ * Walks a compiled `StoryDocument`'s blocks, automatically executing
17
+ * non-suspending work (`@set`, Conditional/Variant branch selection) until
18
+ * it reaches content, presentation, a choice, a navigation, `completed`,
19
+ * or a runtime error (docs/PROJECT_SPEC.md Sections 17.5–17.7).
20
+ *
21
+ * Pure: never mutates `runtimeState`/`cursor`. Progressive, not
22
+ * transactional (17.11): automatic operations completed earlier in this
23
+ * call remain reflected in the returned state even if a later operation
24
+ * in the same call fails; only the failing operation itself has no effect.
25
+ *
26
+ * Also integrates Reader Memory recording (17.9): `recordSceneVisit` and
27
+ * `recordVariantSeen` are called here, at the exact points a qualifying
28
+ * `content`/`presentation`/`choice`/`completed` result is committed —
29
+ * never for `navigation`, a runtime error, or automatic work alone. See
30
+ * `cursor.ts`'s `CursorFrameOrigin`/`collectPendingExposure` for how this
31
+ * survives across separate `advance()` calls (errors, step-budget
32
+ * exhaustion) without a purely function-local computation.
33
+ *
34
+ * `cursor` defaults to the start of `runtimeState.navigation.sceneId`.
35
+ */
36
+ export declare function advance(document: StoryDocument, runtimeState: RuntimeState, cursor?: ExecutionCursor, options?: AdvanceOptions): ExecutionStep;
37
+ //# sourceMappingURL=advance.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"advance.d.ts","sourceRoot":"","sources":["../../src/execution/advance.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAkD,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACzG,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAK9D,OAAO,EAOL,KAAK,eAAe,EACrB,MAAM,aAAa,CAAC;AAOrB,OAAO,KAAK,EAAmB,aAAa,EAAE,MAAM,aAAa,CAAC;AAElE,MAAM,WAAW,cAAc;IAC7B;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAuBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,OAAO,CACrB,QAAQ,EAAE,aAAa,EACvB,YAAY,EAAE,YAAY,EAC1B,MAAM,GAAE,eAAgC,EACxC,OAAO,CAAC,EAAE,cAAc,GACvB,aAAa,CA4Jf"}
@@ -0,0 +1,196 @@
1
+ import { recordSceneVisit } from "../reader/scene-memory.js";
2
+ import { recordVariantSeen } from "../reader/variant-memory.js";
3
+ import { INITIAL_CURSOR, collectPendingExposure, markExposureRecorded, popFrame, pushFrame, withNextIndex } from "./cursor.js";
4
+ import { filterChoiceItems } from "./choice.js";
5
+ import { evaluateCondition, evaluateExpression } from "./expression.js";
6
+ import { RuntimeErrors } from "./errors.js";
7
+ import { navigateTo } from "./navigate.js";
8
+ import { resolveVariant } from "./variant.js";
9
+ const DEFAULT_STEP_BUDGET = 10_000;
10
+ /** Not exported — Conditional has no named public resolution operation, unlike Variant's `resolveVariant`. */
11
+ function selectConditionalBranch(node, context) {
12
+ for (const branch of node.branches) {
13
+ if (branch.kind === "else") {
14
+ return { ok: true, branch };
15
+ }
16
+ if (!branch.condition)
17
+ continue; // defensive: if/elseif always carry a condition per the compiler grammar
18
+ const condition = evaluateCondition(branch.condition, context);
19
+ if (!condition.ok)
20
+ return { ok: false, error: condition.error };
21
+ if (condition.value)
22
+ return { ok: true, branch };
23
+ }
24
+ return undefined; // no branch matched — not an error
25
+ }
26
+ /**
27
+ * Walks a compiled `StoryDocument`'s blocks, automatically executing
28
+ * non-suspending work (`@set`, Conditional/Variant branch selection) until
29
+ * it reaches content, presentation, a choice, a navigation, `completed`,
30
+ * or a runtime error (docs/PROJECT_SPEC.md Sections 17.5–17.7).
31
+ *
32
+ * Pure: never mutates `runtimeState`/`cursor`. Progressive, not
33
+ * transactional (17.11): automatic operations completed earlier in this
34
+ * call remain reflected in the returned state even if a later operation
35
+ * in the same call fails; only the failing operation itself has no effect.
36
+ *
37
+ * Also integrates Reader Memory recording (17.9): `recordSceneVisit` and
38
+ * `recordVariantSeen` are called here, at the exact points a qualifying
39
+ * `content`/`presentation`/`choice`/`completed` result is committed —
40
+ * never for `navigation`, a runtime error, or automatic work alone. See
41
+ * `cursor.ts`'s `CursorFrameOrigin`/`collectPendingExposure` for how this
42
+ * survives across separate `advance()` calls (errors, step-budget
43
+ * exhaustion) without a purely function-local computation.
44
+ *
45
+ * `cursor` defaults to the start of `runtimeState.navigation.sceneId`.
46
+ */
47
+ export function advance(document, runtimeState, cursor = INITIAL_CURSOR, options) {
48
+ let frames = cursor;
49
+ let story = runtimeState.story;
50
+ let reader = runtimeState.reader;
51
+ let budget = options?.stepBudget ?? DEFAULT_STEP_BUDGET;
52
+ if (frames.length === 0) {
53
+ const scene = document.scenes.find((s) => s.id === runtimeState.navigation.sceneId);
54
+ if (!scene) {
55
+ return {
56
+ runtimeState,
57
+ cursor: INITIAL_CURSOR,
58
+ result: { type: "error", error: RuntimeErrors.invalidSceneTarget(runtimeState.navigation.sceneId) }
59
+ };
60
+ }
61
+ frames = pushFrame(INITIAL_CURSOR, scene.blocks, { kind: "scene", visitRecorded: false });
62
+ }
63
+ const commit = (cursorOut, result) => ({
64
+ runtimeState: { ...runtimeState, story, reader },
65
+ cursor: cursorOut,
66
+ result
67
+ });
68
+ // Rebuilt at each use (never cached) since `story`/`reader` change as the
69
+ // walk progresses — every expression-evaluating construct must see the
70
+ // current values, per the single shared EvaluationContext (17.17).
71
+ const context = () => ({ document, story, reader });
72
+ /**
73
+ * Folds any due scene-visit/Variant-seen recording into `reader` and
74
+ * returns the cursor with those occurrences marked recorded. Call only
75
+ * for a genuinely qualifying result (`content`/`presentation`/`choice`)
76
+ * — never for `navigation`/`completed`/an error.
77
+ */
78
+ const recordObservableExposure = (cursorIn) => {
79
+ const pending = collectPendingExposure(cursorIn);
80
+ if (!pending.recordScene && pending.variants.length === 0)
81
+ return cursorIn;
82
+ if (pending.recordScene) {
83
+ reader = recordSceneVisit(reader, runtimeState.navigation.sceneId);
84
+ }
85
+ for (const variant of pending.variants) {
86
+ reader = recordVariantSeen(reader, variant.variantId, variant.branchId);
87
+ }
88
+ return markExposureRecorded(cursorIn, pending);
89
+ };
90
+ for (;;) {
91
+ const top = frames[frames.length - 1];
92
+ if (!top) {
93
+ return commit(INITIAL_CURSOR, { type: "completed" });
94
+ }
95
+ if (top.index >= top.blocks.length) {
96
+ const sceneOrigin = frames[0]?.origin;
97
+ frames = popFrame(frames);
98
+ if (frames.length === 0) {
99
+ // Qualifying "empty" completed (17.9): the episode's only
100
+ // observable outcome is reaching the end with nothing shown.
101
+ // Variant-seen is deliberately NOT extended here by symmetry —
102
+ // only the scene-visit rule treats completed as qualifying.
103
+ if (sceneOrigin?.kind === "scene" && !sceneOrigin.visitRecorded) {
104
+ reader = recordSceneVisit(reader, runtimeState.navigation.sceneId);
105
+ }
106
+ return commit(INITIAL_CURSOR, { type: "completed" });
107
+ }
108
+ frames = withNextIndex(frames); // no budget charge — bookkeeping, not automatic work
109
+ continue;
110
+ }
111
+ const block = top.blocks[top.index];
112
+ switch (block.type) {
113
+ case "Paragraph":
114
+ case "Heading": {
115
+ frames = withNextIndex(frames);
116
+ frames = recordObservableExposure(frames);
117
+ return commit(frames, { type: "content", block });
118
+ }
119
+ case "Presentation": {
120
+ frames = withNextIndex(frames);
121
+ frames = recordObservableExposure(frames);
122
+ return commit(frames, { type: "presentation", command: block.command });
123
+ }
124
+ case "Set": {
125
+ if (budget <= 0)
126
+ return commit(frames, { type: "error", error: RuntimeErrors.stepLimitExceeded() });
127
+ budget -= 1; // charge: "a @set evaluation"
128
+ const evaluated = evaluateExpression(block.expression, context());
129
+ if (!evaluated.ok)
130
+ return commit(frames, { type: "error", error: evaluated.error });
131
+ story = { ...story, [block.name]: evaluated.value };
132
+ frames = withNextIndex(frames);
133
+ continue;
134
+ }
135
+ case "Conditional": {
136
+ if (budget <= 0)
137
+ return commit(frames, { type: "error", error: RuntimeErrors.stepLimitExceeded() });
138
+ budget -= 1; // charge: "a conditional branch selection"
139
+ const selection = selectConditionalBranch(block, context());
140
+ if (selection === undefined) {
141
+ frames = withNextIndex(frames); // no match — no descent, no 2nd charge
142
+ }
143
+ else if (!selection.ok) {
144
+ return commit(frames, { type: "error", error: selection.error });
145
+ }
146
+ else {
147
+ if (budget <= 0)
148
+ return commit(frames, { type: "error", error: RuntimeErrors.stepLimitExceeded() });
149
+ budget -= 1; // charge: "descending into a selected branch's blocks"
150
+ frames = pushFrame(frames, selection.branch.blocks); // no origin — Conditional has no reader-memory concept
151
+ }
152
+ continue;
153
+ }
154
+ case "Variant": {
155
+ if (budget <= 0)
156
+ return commit(frames, { type: "error", error: RuntimeErrors.stepLimitExceeded() });
157
+ budget -= 1; // charge: "a Variant branch resolution"
158
+ const resolution = resolveVariant(block, context());
159
+ if (!resolution.ok)
160
+ return commit(frames, { type: "error", error: resolution.error });
161
+ if (resolution.resolved) {
162
+ if (budget <= 0)
163
+ return commit(frames, { type: "error", error: RuntimeErrors.stepLimitExceeded() });
164
+ budget -= 1; // charge: "descending into a selected branch's blocks"
165
+ frames = pushFrame(frames, resolution.resolved.blocks, {
166
+ kind: "variant",
167
+ variantId: resolution.resolved.variantId,
168
+ branchId: resolution.resolved.branchId,
169
+ seenRecorded: false
170
+ });
171
+ }
172
+ else {
173
+ frames = withNextIndex(frames); // no match — no descent, no 2nd charge
174
+ }
175
+ continue;
176
+ }
177
+ case "Choice": {
178
+ const filtered = filterChoiceItems(block, context());
179
+ if (!filtered.ok)
180
+ return commit(frames, { type: "error", error: filtered.error });
181
+ if (filtered.items.length === 0) {
182
+ return commit(frames, { type: "error", error: RuntimeErrors.emptyChoice() });
183
+ }
184
+ // Cursor is intentionally left pointing at this ChoiceNode — resuming
185
+ // past it only ever happens via selectChoice's shared navigateTo,
186
+ // never via a further advance() call.
187
+ frames = recordObservableExposure(frames);
188
+ return commit(frames, { type: "choice", items: filtered.items });
189
+ }
190
+ case "Goto": {
191
+ return navigateTo(document, { ...runtimeState, story, reader }, frames, block.target);
192
+ }
193
+ }
194
+ }
195
+ }
196
+ //# sourceMappingURL=advance.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"advance.js","sourceRoot":"","sources":["../../src/execution/advance.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,30 @@
1
+ import type { ChoiceNode, StoryDocument } from "@aftertext/compiler";
2
+ import { type EvaluationContext } from "./expression.js";
3
+ import type { RuntimeExecutionError } from "./errors.js";
4
+ import type { AvailableChoiceItem, ExecutionStep } from "./result.js";
5
+ export type ChoiceFilterOutcome = {
6
+ readonly ok: true;
7
+ readonly items: readonly AvailableChoiceItem[];
8
+ } | {
9
+ readonly ok: false;
10
+ readonly error: RuntimeExecutionError;
11
+ };
12
+ /**
13
+ * Evaluates a `ChoiceNode`'s item conditions exactly once, producing the
14
+ * precise item set `advance()` will expose as the Choice suspension.
15
+ * Internal to `execution/` — used by `advance.ts`. Takes the full
16
+ * `EvaluationContext` (Section 17.17) since an item's condition may now
17
+ * contain a Reader Memory query; this is an internal-only signature
18
+ * widening, not a public API change (unlike `resolveVariant`).
19
+ */
20
+ export declare function filterChoiceItems(node: ChoiceNode, context: EvaluationContext): ChoiceFilterOutcome;
21
+ /**
22
+ * Resolves an explicit Choice selection against the *exact* suspension
23
+ * `advance()` returned — never by re-locating the source `ChoiceNode` or
24
+ * re-evaluating its conditions (docs/PROJECT_SPEC.md Section 17.7). The
25
+ * runtime core has no global "current suspension"; an older but internally
26
+ * valid suspension may be replayed/forked from — that is not itself an
27
+ * error here (17.7's replay clarification).
28
+ */
29
+ export declare function selectChoice(document: StoryDocument, suspension: ExecutionStep, index: number): ExecutionStep;
30
+ //# sourceMappingURL=choice.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"choice.d.ts","sourceRoot":"","sources":["../../src/execution/choice.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACrE,OAAO,EAAqB,KAAK,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAE5E,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAEzD,OAAO,KAAK,EAAE,mBAAmB,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAEtE,MAAM,MAAM,mBAAmB,GAC3B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,SAAS,mBAAmB,EAAE,CAAA;CAAE,GACrE;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAA;CAAE,CAAC;AAElE;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,iBAAiB,GAAG,mBAAmB,CAWnG;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,aAAa,EAAE,UAAU,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,CA2B7G"}
@@ -0,0 +1,58 @@
1
+ import { evaluateCondition } from "./expression.js";
2
+ import { RuntimeErrors } from "./errors.js";
3
+ import { navigateTo } from "./navigate.js";
4
+ /**
5
+ * Evaluates a `ChoiceNode`'s item conditions exactly once, producing the
6
+ * precise item set `advance()` will expose as the Choice suspension.
7
+ * Internal to `execution/` — used by `advance.ts`. Takes the full
8
+ * `EvaluationContext` (Section 17.17) since an item's condition may now
9
+ * contain a Reader Memory query; this is an internal-only signature
10
+ * widening, not a public API change (unlike `resolveVariant`).
11
+ */
12
+ export function filterChoiceItems(node, context) {
13
+ const items = [];
14
+ for (const item of node.items) {
15
+ if (item.condition) {
16
+ const condition = evaluateCondition(item.condition, context);
17
+ if (!condition.ok)
18
+ return { ok: false, error: condition.error };
19
+ if (!condition.value)
20
+ continue;
21
+ }
22
+ items.push({ index: items.length, text: item.text, target: item.target });
23
+ }
24
+ return { ok: true, items };
25
+ }
26
+ /**
27
+ * Resolves an explicit Choice selection against the *exact* suspension
28
+ * `advance()` returned — never by re-locating the source `ChoiceNode` or
29
+ * re-evaluating its conditions (docs/PROJECT_SPEC.md Section 17.7). The
30
+ * runtime core has no global "current suspension"; an older but internally
31
+ * valid suspension may be replayed/forked from — that is not itself an
32
+ * error here (17.7's replay clarification).
33
+ */
34
+ export function selectChoice(document, suspension, index) {
35
+ if (suspension.result.type !== "choice") {
36
+ return {
37
+ runtimeState: suspension.runtimeState,
38
+ cursor: suspension.cursor,
39
+ result: {
40
+ type: "error",
41
+ error: RuntimeErrors.invalidChoiceSelection("Not currently suspended on a choice.")
42
+ }
43
+ };
44
+ }
45
+ const item = suspension.result.items[index];
46
+ if (!item) {
47
+ return {
48
+ runtimeState: suspension.runtimeState,
49
+ cursor: suspension.cursor,
50
+ result: {
51
+ type: "error",
52
+ error: RuntimeErrors.invalidChoiceSelection(`Selection index ${index} is not part of the offered choice.`)
53
+ }
54
+ };
55
+ }
56
+ return navigateTo(document, suspension.runtimeState, suspension.cursor, item.target);
57
+ }
58
+ //# sourceMappingURL=choice.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"choice.js","sourceRoot":"","sources":["../../src/execution/choice.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAA0B,MAAM,iBAAiB,CAAC;AAC5E,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAO3C;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAgB,EAAE,OAA0B;IAC5E,MAAM,KAAK,GAA0B,EAAE,CAAC;IACxC,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;QAC9B,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YACnB,MAAM,SAAS,GAAG,iBAAiB,CAAC,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;YAC7D,IAAI,CAAC,SAAS,CAAC,EAAE;gBAAE,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,SAAS,CAAC,KAAK,EAAE,CAAC;YAChE,IAAI,CAAC,SAAS,CAAC,KAAK;gBAAE,SAAS;QACjC,CAAC;QACD,KAAK,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,KAAK,CAAC,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,CAAC,CAAC;IAC5E,CAAC;IACD,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAC7B,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,YAAY,CAAC,QAAuB,EAAE,UAAyB,EAAE,KAAa;IAC5F,IAAI,UAAU,CAAC,MAAM,CAAC,IAAI,KAAK,QAAQ,EAAE,CAAC;QACxC,OAAO;YACL,YAAY,EAAE,UAAU,CAAC,YAAY;YACrC,MAAM,EAAE,UAAU,CAAC,MAAM;YACzB,MAAM,EAAE;gBACN,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE,aAAa,CAAC,sBAAsB,CAAC,sCAAsC,CAAC;aACpF;SACF,CAAC;IACJ,CAAC;IAED,MAAM,IAAI,GAAG,UAAU,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;IAC5C,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,OAAO;YACL,YAAY,EAAE,UAAU,CAAC,YAAY;YACrC,MAAM,EAAE,UAAU,CAAC,MAAM;YACzB,MAAM,EAAE;gBACN,IAAI,EAAE,OAAO;gBACb,KAAK,EAAE,aAAa,CAAC,sBAAsB,CACzC,mBAAmB,KAAK,qCAAqC,CAC9D;aACF;SACF,CAAC;IACJ,CAAC;IAED,OAAO,UAAU,CAAC,QAAQ,EAAE,UAAU,CAAC,YAAY,EAAE,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;AACvF,CAAC"}
@@ -0,0 +1,78 @@
1
+ import type { StoryBlock } from "@aftertext/compiler";
2
+ /**
3
+ * Reader-Memory-integration provenance for one frame (docs/PROJECT_SPEC.md
4
+ * Section 17.9). Purely runtime-internal bookkeeping — never a `ReaderState`
5
+ * value itself, only whether/what to record:
6
+ *
7
+ * - `scene`: tags the outermost frame of one scene-entry episode. Set once,
8
+ * when the episode begins; `visitRecorded` flips to `true` the first time
9
+ * that episode produces a qualifying result.
10
+ * - `variant`: tags a frame pushed by resolving a Variant to a branch. One
11
+ * tag per resolution occurrence; `seenRecorded` flips to `true` the first
12
+ * time that occurrence produces a qualifying result from inside it.
13
+ *
14
+ * A frame pushed for any other reason (a matched `ConditionalNode` branch)
15
+ * carries no `origin` — Conditional has no reader-memory concept.
16
+ */
17
+ export type CursorFrameOrigin = {
18
+ readonly kind: "scene";
19
+ readonly visitRecorded: boolean;
20
+ } | {
21
+ readonly kind: "variant";
22
+ readonly variantId: string;
23
+ readonly branchId: string;
24
+ readonly seenRecorded: boolean;
25
+ };
26
+ /**
27
+ * One level of nested block-tree position: which block list is being
28
+ * walked, and the index of the next block to process within it. Not
29
+ * exported from the package's public barrel — internal to `execution/`.
30
+ */
31
+ export interface CursorFrame {
32
+ readonly blocks: readonly StoryBlock[];
33
+ readonly index: number;
34
+ readonly origin?: CursorFrameOrigin;
35
+ }
36
+ /**
37
+ * Ephemeral structural execution position within a scene's block tree
38
+ * (docs/PROJECT_SPEC.md Section 17.10). A stack of frames — the top is the
39
+ * deepest active nested branch. Exists separately from `RuntimeState`, is
40
+ * never persisted, and must never be written into `ReaderState`: it is
41
+ * *structural* position (plus, per 17.9, ephemeral recording provenance),
42
+ * not reader-memory identity itself. Treated as opaque by consumers —
43
+ * obtained from and passed back into `advance`/`selectChoice`, never
44
+ * constructed or inspected directly.
45
+ */
46
+ export type ExecutionCursor = readonly CursorFrame[];
47
+ /** The cursor meaning "start of the current scene, from its first block." */
48
+ export declare const INITIAL_CURSOR: ExecutionCursor;
49
+ /** Pushes a new frame — "descending into a selected branch's blocks." */
50
+ export declare function pushFrame(cursor: ExecutionCursor, blocks: readonly StoryBlock[], origin?: CursorFrameOrigin): ExecutionCursor;
51
+ /** Pops the deepest frame — resuming the parent after its nested content is exhausted. */
52
+ export declare function popFrame(cursor: ExecutionCursor): ExecutionCursor;
53
+ /** Returns a cursor with the top frame's index advanced by one, preserving its origin. */
54
+ export declare function withNextIndex(cursor: ExecutionCursor): ExecutionCursor;
55
+ /**
56
+ * Reader-Memory exposure recording due at the current cursor position: the
57
+ * active scene-entry episode (frame 0), if not yet recorded, plus every
58
+ * active Variant-branch frame not yet recorded, at any depth — including
59
+ * beneath an untagged (Conditional) frame, so a nested construct inside a
60
+ * selected Variant branch still attributes correctly (docs/PROJECT_SPEC.md
61
+ * Section 17.9, "Nested Variants"). A pure query — records nothing itself.
62
+ */
63
+ export interface PendingExposure {
64
+ readonly recordScene: boolean;
65
+ readonly variants: readonly {
66
+ readonly depth: number;
67
+ readonly variantId: string;
68
+ readonly branchId: string;
69
+ }[];
70
+ }
71
+ export declare function collectPendingExposure(cursor: ExecutionCursor): PendingExposure;
72
+ /**
73
+ * Marks the given `PendingExposure` as recorded on the cursor, immutably.
74
+ * Called only after the corresponding `recordSceneVisit`/`recordVariantSeen`
75
+ * calls have actually been folded into `ReaderState` — see `advance.ts`.
76
+ */
77
+ export declare function markExposureRecorded(cursor: ExecutionCursor, pending: PendingExposure): ExecutionCursor;
78
+ //# sourceMappingURL=cursor.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cursor.d.ts","sourceRoot":"","sources":["../../src/execution/cursor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,iBAAiB,GACzB;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAA;CAAE,GAC3D;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAA;CAAE,CAAC;AAExH;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,MAAM,EAAE,SAAS,UAAU,EAAE,CAAC;IACvC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,iBAAiB,CAAC;CACrC;AAED;;;;;;;;;GASG;AACH,MAAM,MAAM,eAAe,GAAG,SAAS,WAAW,EAAE,CAAC;AAErD,6EAA6E;AAC7E,eAAO,MAAM,cAAc,EAAE,eAAoB,CAAC;AAElD,yEAAyE;AACzE,wBAAgB,SAAS,CACvB,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,SAAS,UAAU,EAAE,EAC7B,MAAM,CAAC,EAAE,iBAAiB,GACzB,eAAe,CAEjB;AAED,0FAA0F;AAC1F,wBAAgB,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CAEjE;AAED,0FAA0F;AAC1F,wBAAgB,aAAa,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CAItE;AAWD;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,SAAS;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACjH;AAED,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,eAAe,GAAG,eAAe,CAY/E;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,eAAe,EAAE,OAAO,EAAE,eAAe,GAAG,eAAe,CAcvG"}
@@ -0,0 +1,59 @@
1
+ /** The cursor meaning "start of the current scene, from its first block." */
2
+ export const INITIAL_CURSOR = [];
3
+ /** Pushes a new frame — "descending into a selected branch's blocks." */
4
+ export function pushFrame(cursor, blocks, origin) {
5
+ return [...cursor, { blocks, index: 0, origin }];
6
+ }
7
+ /** Pops the deepest frame — resuming the parent after its nested content is exhausted. */
8
+ export function popFrame(cursor) {
9
+ return cursor.slice(0, -1);
10
+ }
11
+ /** Returns a cursor with the top frame's index advanced by one, preserving its origin. */
12
+ export function withNextIndex(cursor) {
13
+ const top = cursor[cursor.length - 1];
14
+ if (!top)
15
+ return cursor;
16
+ return [...cursor.slice(0, -1), { blocks: top.blocks, index: top.index + 1, origin: top.origin }];
17
+ }
18
+ /** Immutably replaces the origin metadata of the frame at `depth`. */
19
+ function withFrameOrigin(cursor, depth, origin) {
20
+ const frame = cursor[depth];
21
+ if (!frame)
22
+ return cursor;
23
+ const next = cursor.slice();
24
+ next[depth] = { blocks: frame.blocks, index: frame.index, origin };
25
+ return next;
26
+ }
27
+ export function collectPendingExposure(cursor) {
28
+ const sceneOrigin = cursor[0]?.origin;
29
+ const recordScene = sceneOrigin?.kind === "scene" && !sceneOrigin.visitRecorded;
30
+ const variants = [];
31
+ for (let depth = 0; depth < cursor.length; depth++) {
32
+ const origin = cursor[depth]?.origin;
33
+ if (origin?.kind === "variant" && !origin.seenRecorded) {
34
+ variants.push({ depth, variantId: origin.variantId, branchId: origin.branchId });
35
+ }
36
+ }
37
+ return { recordScene, variants };
38
+ }
39
+ /**
40
+ * Marks the given `PendingExposure` as recorded on the cursor, immutably.
41
+ * Called only after the corresponding `recordSceneVisit`/`recordVariantSeen`
42
+ * calls have actually been folded into `ReaderState` — see `advance.ts`.
43
+ */
44
+ export function markExposureRecorded(cursor, pending) {
45
+ let next = cursor;
46
+ if (pending.recordScene) {
47
+ next = withFrameOrigin(next, 0, { kind: "scene", visitRecorded: true });
48
+ }
49
+ for (const variant of pending.variants) {
50
+ next = withFrameOrigin(next, variant.depth, {
51
+ kind: "variant",
52
+ variantId: variant.variantId,
53
+ branchId: variant.branchId,
54
+ seenRecorded: true
55
+ });
56
+ }
57
+ return next;
58
+ }
59
+ //# sourceMappingURL=cursor.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cursor.js","sourceRoot":"","sources":["../../src/execution/cursor.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,27 @@
1
+ import type { SourceSpan } from "@aftertext/compiler";
2
+ /**
3
+ * Narrow runtime execution error categories — deliberately not a code
4
+ * registry mirroring the compiler's `Diagnostic`. Runtime execution errors
5
+ * are a distinct concern from compiler diagnostics: different producer,
6
+ * different audience, different lifecycle (docs/PROJECT_SPEC.md Section
7
+ * 17.11).
8
+ */
9
+ export type RuntimeExecutionErrorKind = "unknown-identifier" | "type-mismatch" | "division-by-zero" | "invalid-arithmetic-result" | "empty-choice" | "invalid-choice-selection" | "invalid-scene-target" | "step-limit-exceeded" | "unknown-builtin" | "invalid-variant-reference";
10
+ export interface RuntimeExecutionError {
11
+ readonly kind: RuntimeExecutionErrorKind;
12
+ readonly message: string;
13
+ readonly span?: SourceSpan;
14
+ }
15
+ export declare const RuntimeErrors: {
16
+ readonly unknownIdentifier: (name: string, span?: SourceSpan) => RuntimeExecutionError;
17
+ readonly typeMismatch: (message: string, span?: SourceSpan) => RuntimeExecutionError;
18
+ readonly divisionByZero: (span?: SourceSpan) => RuntimeExecutionError;
19
+ readonly invalidArithmeticResult: (span?: SourceSpan) => RuntimeExecutionError;
20
+ readonly emptyChoice: (span?: SourceSpan) => RuntimeExecutionError;
21
+ readonly invalidChoiceSelection: (message: string) => RuntimeExecutionError;
22
+ readonly invalidSceneTarget: (target: string, span?: SourceSpan) => RuntimeExecutionError;
23
+ readonly stepLimitExceeded: () => RuntimeExecutionError;
24
+ readonly unknownBuiltin: (name: string, span?: SourceSpan) => RuntimeExecutionError;
25
+ readonly invalidVariantReference: (variantId: string, span?: SourceSpan) => RuntimeExecutionError;
26
+ };
27
+ //# sourceMappingURL=errors.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/execution/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEtD;;;;;;GAMG;AACH,MAAM,MAAM,yBAAyB,GACjC,oBAAoB,GACpB,eAAe,GACf,kBAAkB,GAClB,2BAA2B,GAC3B,cAAc,GACd,0BAA0B,GAC1B,sBAAsB,GACtB,qBAAqB,GACrB,iBAAiB,GACjB,2BAA2B,CAAC;AAEhC,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;IACzC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EAAE,UAAU,CAAC;CAC5B;AAMD,eAAO,MAAM,aAAa;uCACA,MAAM,SAAS,UAAU,KAAG,qBAAqB;qCAGnD,MAAM,SAAS,UAAU,KAAG,qBAAqB;qCAGjD,UAAU,KAAG,qBAAqB;8CAGzB,UAAU,KAAG,qBAAqB;kCAO9C,UAAU,KAAG,qBAAqB;+CAGrB,MAAM,KAAG,qBAAqB;0CAGnC,MAAM,SAAS,UAAU,KAAG,qBAAqB;sCAGvD,qBAAqB;oCAGrB,MAAM,SAAS,UAAU,KAAG,qBAAqB;kDAGnC,MAAM,SAAS,UAAU,KAAG,qBAAqB;CAG5E,CAAC"}