@aftertext/runtime 0.1.0 → 0.1.1
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.
- package/dist/execution/advance.d.ts +2 -2
- package/dist/execution/advance.js +1 -1
- package/dist/execution/choice.d.ts +1 -1
- package/dist/execution/choice.js +1 -1
- package/dist/execution/cursor.d.ts +3 -3
- package/dist/execution/errors.d.ts +1 -1
- package/dist/execution/expression.d.ts +2 -2
- package/dist/execution/memory-queries.d.ts +1 -1
- package/dist/execution/memory-queries.js +2 -2
- package/dist/execution/navigate.d.ts +1 -1
- package/dist/execution/navigate.js +1 -1
- package/dist/execution/result.d.ts +1 -1
- package/dist/execution/variant.d.ts +1 -1
- package/dist/execution/variant.js +1 -1
- package/dist/reader/variant-memory.d.ts +3 -3
- package/dist/reader/variant-memory.js +2 -2
- package/dist/state/reader-state.d.ts +1 -1
- package/package.json +2 -2
|
@@ -7,7 +7,7 @@ export interface AdvanceOptions {
|
|
|
7
7
|
* Overrides the internal step-budget default — intended for tests that
|
|
8
8
|
* need to deterministically exercise step-limit exhaustion without
|
|
9
9
|
* constructing a pathologically large scene. Not a specification-level
|
|
10
|
-
* constant (docs/
|
|
10
|
+
* constant (docs/CORE_SPEC.md Section 17.12 deliberately commits to
|
|
11
11
|
* no numeric default).
|
|
12
12
|
*/
|
|
13
13
|
readonly stepBudget?: number;
|
|
@@ -16,7 +16,7 @@ export interface AdvanceOptions {
|
|
|
16
16
|
* Walks a compiled `StoryDocument`'s blocks, automatically executing
|
|
17
17
|
* non-suspending work (`@set`, Conditional/Variant branch selection) until
|
|
18
18
|
* it reaches content, presentation, a choice, a navigation, `completed`,
|
|
19
|
-
* or a runtime error (docs/
|
|
19
|
+
* or a runtime error (docs/CORE_SPEC.md Sections 17.5–17.7).
|
|
20
20
|
*
|
|
21
21
|
* Pure: never mutates `runtimeState`/`cursor`. Progressive, not
|
|
22
22
|
* transactional (17.11): automatic operations completed earlier in this
|
|
@@ -27,7 +27,7 @@ function selectConditionalBranch(node, context) {
|
|
|
27
27
|
* Walks a compiled `StoryDocument`'s blocks, automatically executing
|
|
28
28
|
* non-suspending work (`@set`, Conditional/Variant branch selection) until
|
|
29
29
|
* it reaches content, presentation, a choice, a navigation, `completed`,
|
|
30
|
-
* or a runtime error (docs/
|
|
30
|
+
* or a runtime error (docs/CORE_SPEC.md Sections 17.5–17.7).
|
|
31
31
|
*
|
|
32
32
|
* Pure: never mutates `runtimeState`/`cursor`. Progressive, not
|
|
33
33
|
* transactional (17.11): automatic operations completed earlier in this
|
|
@@ -21,7 +21,7 @@ export declare function filterChoiceItems(node: ChoiceNode, context: EvaluationC
|
|
|
21
21
|
/**
|
|
22
22
|
* Resolves an explicit Choice selection against the *exact* suspension
|
|
23
23
|
* `advance()` returned — never by re-locating the source `ChoiceNode` or
|
|
24
|
-
* re-evaluating its conditions (docs/
|
|
24
|
+
* re-evaluating its conditions (docs/CORE_SPEC.md Section 17.7). The
|
|
25
25
|
* runtime core has no global "current suspension"; an older but internally
|
|
26
26
|
* valid suspension may be replayed/forked from — that is not itself an
|
|
27
27
|
* error here (17.7's replay clarification).
|
package/dist/execution/choice.js
CHANGED
|
@@ -26,7 +26,7 @@ export function filterChoiceItems(node, context) {
|
|
|
26
26
|
/**
|
|
27
27
|
* Resolves an explicit Choice selection against the *exact* suspension
|
|
28
28
|
* `advance()` returned — never by re-locating the source `ChoiceNode` or
|
|
29
|
-
* re-evaluating its conditions (docs/
|
|
29
|
+
* re-evaluating its conditions (docs/CORE_SPEC.md Section 17.7). The
|
|
30
30
|
* runtime core has no global "current suspension"; an older but internally
|
|
31
31
|
* valid suspension may be replayed/forked from — that is not itself an
|
|
32
32
|
* error here (17.7's replay clarification).
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import type { StoryBlock } from "@aftertext/compiler";
|
|
2
2
|
/**
|
|
3
|
-
* Reader-Memory-integration provenance for one frame (docs/
|
|
3
|
+
* Reader-Memory-integration provenance for one frame (docs/CORE_SPEC.md
|
|
4
4
|
* Section 17.9). Purely runtime-internal bookkeeping — never a `ReaderState`
|
|
5
5
|
* value itself, only whether/what to record:
|
|
6
6
|
*
|
|
@@ -35,7 +35,7 @@ export interface CursorFrame {
|
|
|
35
35
|
}
|
|
36
36
|
/**
|
|
37
37
|
* Ephemeral structural execution position within a scene's block tree
|
|
38
|
-
* (docs/
|
|
38
|
+
* (docs/CORE_SPEC.md Section 17.10). A stack of frames — the top is the
|
|
39
39
|
* deepest active nested branch. Exists separately from `RuntimeState`, is
|
|
40
40
|
* never persisted, and must never be written into `ReaderState`: it is
|
|
41
41
|
* *structural* position (plus, per 17.9, ephemeral recording provenance),
|
|
@@ -57,7 +57,7 @@ export declare function withNextIndex(cursor: ExecutionCursor): ExecutionCursor;
|
|
|
57
57
|
* active scene-entry episode (frame 0), if not yet recorded, plus every
|
|
58
58
|
* active Variant-branch frame not yet recorded, at any depth — including
|
|
59
59
|
* beneath an untagged (Conditional) frame, so a nested construct inside a
|
|
60
|
-
* selected Variant branch still attributes correctly (docs/
|
|
60
|
+
* selected Variant branch still attributes correctly (docs/CORE_SPEC.md
|
|
61
61
|
* Section 17.9, "Nested Variants"). A pure query — records nothing itself.
|
|
62
62
|
*/
|
|
63
63
|
export interface PendingExposure {
|
|
@@ -3,7 +3,7 @@ import type { SourceSpan } from "@aftertext/compiler";
|
|
|
3
3
|
* Narrow runtime execution error categories — deliberately not a code
|
|
4
4
|
* registry mirroring the compiler's `Diagnostic`. Runtime execution errors
|
|
5
5
|
* are a distinct concern from compiler diagnostics: different producer,
|
|
6
|
-
* different audience, different lifecycle (docs/
|
|
6
|
+
* different audience, different lifecycle (docs/CORE_SPEC.md Section
|
|
7
7
|
* 17.11).
|
|
8
8
|
*/
|
|
9
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";
|
|
@@ -3,7 +3,7 @@ import type { ReaderState } from "../state/reader-state.js";
|
|
|
3
3
|
import type { StoryState, StoryValue } from "../state/story-state.js";
|
|
4
4
|
import type { RuntimeExecutionError } from "./errors.js";
|
|
5
5
|
/**
|
|
6
|
-
* Everything expression evaluation may read (docs/
|
|
6
|
+
* Everything expression evaluation may read (docs/CORE_SPEC.md Section
|
|
7
7
|
* 17.17). Responsibilities are strictly partitioned: `story` backs
|
|
8
8
|
* `Identifier` resolution (unchanged since before Reader Memory queries
|
|
9
9
|
* existed); `reader` backs Reader Memory builtin values, reachable only
|
|
@@ -20,7 +20,7 @@ export interface EvaluationContext {
|
|
|
20
20
|
}
|
|
21
21
|
/**
|
|
22
22
|
* Pure evaluator for the compiler's existing `ExpressionNode` against an
|
|
23
|
-
* `EvaluationContext`. Implements docs/
|
|
23
|
+
* `EvaluationContext`. Implements docs/CORE_SPEC.md Section 17.8 exactly:
|
|
24
24
|
* explicit, deterministic rules, never implicit JavaScript truthiness or
|
|
25
25
|
* coercion. Result-typed rather than throwing, matching this package's
|
|
26
26
|
* existing no-throw, pure-function style. `Call` (Reader Memory queries)
|
|
@@ -10,7 +10,7 @@ export type MemoryQueryOutcome = {
|
|
|
10
10
|
readonly error: RuntimeExecutionError;
|
|
11
11
|
};
|
|
12
12
|
/**
|
|
13
|
-
* Evaluates a Reader Memory builtin call (docs/
|
|
13
|
+
* Evaluates a Reader Memory builtin call (docs/CORE_SPEC.md Sections
|
|
14
14
|
* 17.14–17.16). Defensive: the compiler is expected to have already
|
|
15
15
|
* rejected an unknown callee, wrong arity, a non-literal argument, or an
|
|
16
16
|
* unknown Scene/Variant reference — this still re-checks each, exactly as
|
|
@@ -2,7 +2,7 @@ import { hasVisitedScene, getSceneVisitCount } from "../reader/scene-memory.js";
|
|
|
2
2
|
import { hasSeenVariant, getLastSeenVariantBranch } from "../reader/variant-memory.js";
|
|
3
3
|
import { RuntimeErrors } from "./errors.js";
|
|
4
4
|
/**
|
|
5
|
-
* The fixed Reader Memory query builtin registry (docs/
|
|
5
|
+
* The fixed Reader Memory query builtin registry (docs/CORE_SPEC.md
|
|
6
6
|
* Section 17.15) — exactly four entries, not author-extensible. This is
|
|
7
7
|
* implementation code, not a dynamic function-lookup mechanism: adding a
|
|
8
8
|
* builtin means adding an entry here, never resolving a JS function by an
|
|
@@ -49,7 +49,7 @@ function variantExists(document, variantId) {
|
|
|
49
49
|
return document.scenes.some((scene) => containsVariant(scene.blocks, variantId));
|
|
50
50
|
}
|
|
51
51
|
/**
|
|
52
|
-
* Evaluates a Reader Memory builtin call (docs/
|
|
52
|
+
* Evaluates a Reader Memory builtin call (docs/CORE_SPEC.md Sections
|
|
53
53
|
* 17.14–17.16). Defensive: the compiler is expected to have already
|
|
54
54
|
* rejected an unknown callee, wrong arity, a non-literal argument, or an
|
|
55
55
|
* unknown Scene/Variant reference — this still re-checks each, exactly as
|
|
@@ -4,7 +4,7 @@ import { type ExecutionCursor } from "./cursor.js";
|
|
|
4
4
|
import type { ExecutionStep } from "./result.js";
|
|
5
5
|
/**
|
|
6
6
|
* Shared internal navigation operation used identically by `GotoNode`
|
|
7
|
-
* handling and by a resolved Choice selection (docs/
|
|
7
|
+
* handling and by a resolved Choice selection (docs/CORE_SPEC.md
|
|
8
8
|
* Section 17.7: "share one navigation rule"). Not part of the public
|
|
9
9
|
* barrel.
|
|
10
10
|
*
|
|
@@ -2,7 +2,7 @@ import { INITIAL_CURSOR } from "./cursor.js";
|
|
|
2
2
|
import { RuntimeErrors } from "./errors.js";
|
|
3
3
|
/**
|
|
4
4
|
* Shared internal navigation operation used identically by `GotoNode`
|
|
5
|
-
* handling and by a resolved Choice selection (docs/
|
|
5
|
+
* handling and by a resolved Choice selection (docs/CORE_SPEC.md
|
|
6
6
|
* Section 17.7: "share one navigation rule"). Not part of the public
|
|
7
7
|
* barrel.
|
|
8
8
|
*
|
|
@@ -5,7 +5,7 @@ import type { RuntimeExecutionError } from "./errors.js";
|
|
|
5
5
|
/**
|
|
6
6
|
* One item offered by a Choice suspension. `index` is a transient
|
|
7
7
|
* request/response correlator scoped to that one suspension — never a
|
|
8
|
-
* stable identity, never persisted (docs/
|
|
8
|
+
* stable identity, never persisted (docs/CORE_SPEC.md Section 17.7).
|
|
9
9
|
*/
|
|
10
10
|
export interface AvailableChoiceItem {
|
|
11
11
|
readonly index: number;
|
|
@@ -14,7 +14,7 @@ export type VariantResolution = {
|
|
|
14
14
|
readonly error: RuntimeExecutionError;
|
|
15
15
|
};
|
|
16
16
|
/**
|
|
17
|
-
* Pure Variant resolution (docs/
|
|
17
|
+
* Pure Variant resolution (docs/CORE_SPEC.md Section 17.7): `@when`
|
|
18
18
|
* conditions evaluated in source order, first match wins, `@otherwise` is
|
|
19
19
|
* the fallback. If nothing matches and there is no `@otherwise`,
|
|
20
20
|
* `resolved` is `undefined` — a graceful "no match," not an error. Never
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { evaluateCondition } from "./expression.js";
|
|
2
2
|
/**
|
|
3
|
-
* Pure Variant resolution (docs/
|
|
3
|
+
* Pure Variant resolution (docs/CORE_SPEC.md Section 17.7): `@when`
|
|
4
4
|
* conditions evaluated in source order, first match wins, `@otherwise` is
|
|
5
5
|
* the fallback. If nothing matches and there is no `@otherwise`,
|
|
6
6
|
* `resolved` is `undefined` — a graceful "no match," not an error. Never
|
|
@@ -2,7 +2,7 @@ import type { ReaderState } from "../state/reader-state.js";
|
|
|
2
2
|
/**
|
|
3
3
|
* What the reader remembers of one Variant. Deliberately narrow: the
|
|
4
4
|
* first and last branch seen, plus a count — not full branch history,
|
|
5
|
-
* not timestamps. See `docs/
|
|
5
|
+
* not timestamps. See `docs/CORE_SPEC.md` (Runtime Principles) for the
|
|
6
6
|
* rationale.
|
|
7
7
|
*/
|
|
8
8
|
export interface VariantMemory {
|
|
@@ -28,14 +28,14 @@ export declare function recordVariantSeen(reader: ReaderState, variantId: string
|
|
|
28
28
|
export declare function hasVariantChangedSinceRead(reader: ReaderState, variantId: string, currentBranchId: string): boolean;
|
|
29
29
|
/**
|
|
30
30
|
* Whether the reader has ever seen `variantId` at least once. Backs the
|
|
31
|
-
* `seen_variant(...)` Reader Memory query (docs/
|
|
31
|
+
* `seen_variant(...)` Reader Memory query (docs/CORE_SPEC.md Section
|
|
32
32
|
* 17.15). A pure query — it never records anything itself.
|
|
33
33
|
*/
|
|
34
34
|
export declare function hasSeenVariant(reader: ReaderState, variantId: string): boolean;
|
|
35
35
|
/**
|
|
36
36
|
* The branch id the reader most recently saw for `variantId`, or `null`
|
|
37
37
|
* if it has never been seen. Backs the `last_seen_variant_branch(...)`
|
|
38
|
-
* Reader Memory query (docs/
|
|
38
|
+
* Reader Memory query (docs/CORE_SPEC.md Section 17.15). A pure query —
|
|
39
39
|
* it never records anything itself.
|
|
40
40
|
*/
|
|
41
41
|
export declare function getLastSeenVariantBranch(reader: ReaderState, variantId: string): string | null;
|
|
@@ -30,7 +30,7 @@ export function hasVariantChangedSinceRead(reader, variantId, currentBranchId) {
|
|
|
30
30
|
}
|
|
31
31
|
/**
|
|
32
32
|
* Whether the reader has ever seen `variantId` at least once. Backs the
|
|
33
|
-
* `seen_variant(...)` Reader Memory query (docs/
|
|
33
|
+
* `seen_variant(...)` Reader Memory query (docs/CORE_SPEC.md Section
|
|
34
34
|
* 17.15). A pure query — it never records anything itself.
|
|
35
35
|
*/
|
|
36
36
|
export function hasSeenVariant(reader, variantId) {
|
|
@@ -39,7 +39,7 @@ export function hasSeenVariant(reader, variantId) {
|
|
|
39
39
|
/**
|
|
40
40
|
* The branch id the reader most recently saw for `variantId`, or `null`
|
|
41
41
|
* if it has never been seen. Backs the `last_seen_variant_branch(...)`
|
|
42
|
-
* Reader Memory query (docs/
|
|
42
|
+
* Reader Memory query (docs/CORE_SPEC.md Section 17.15). A pure query —
|
|
43
43
|
* it never records anything itself.
|
|
44
44
|
*/
|
|
45
45
|
export function getLastSeenVariantBranch(reader, variantId) {
|
|
@@ -2,7 +2,7 @@ import type { SceneVisitMemory } from "../reader/scene-memory.js";
|
|
|
2
2
|
import type { VariantMemory } from "../reader/variant-memory.js";
|
|
3
3
|
/**
|
|
4
4
|
* Facts about what the reader has experienced — distinct from `StoryState`
|
|
5
|
-
* (the current truth of the story world). See `docs/
|
|
5
|
+
* (the current truth of the story world). See `docs/CORE_SPEC.md`:
|
|
6
6
|
* `StoryState != ReaderState` is a locked architectural requirement.
|
|
7
7
|
*
|
|
8
8
|
* `VariantMemory` is nested here rather than being an independent
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@aftertext/runtime",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"description": "AfterText runtime domain foundation: StoryState, ReaderState, and NavigationState derived from a compiled StoryDocument.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"repository": {
|
|
@@ -30,7 +30,7 @@
|
|
|
30
30
|
"test": "vitest run"
|
|
31
31
|
},
|
|
32
32
|
"dependencies": {
|
|
33
|
-
"@aftertext/compiler": "^0.1.
|
|
33
|
+
"@aftertext/compiler": "^0.1.1"
|
|
34
34
|
},
|
|
35
35
|
"devDependencies": {
|
|
36
36
|
"@types/node": "^22.7.5",
|