@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.
@@ -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/PROJECT_SPEC.md Section 17.12 deliberately commits to
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/PROJECT_SPEC.md Sections 17.5–17.7).
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/PROJECT_SPEC.md Sections 17.5–17.7).
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/PROJECT_SPEC.md Section 17.7). The
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).
@@ -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/PROJECT_SPEC.md Section 17.7). The
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/PROJECT_SPEC.md
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/PROJECT_SPEC.md Section 17.10). A stack of frames — the top is the
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/PROJECT_SPEC.md
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/PROJECT_SPEC.md Section
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/PROJECT_SPEC.md Section
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/PROJECT_SPEC.md Section 17.8 exactly:
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/PROJECT_SPEC.md Sections
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/PROJECT_SPEC.md
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/PROJECT_SPEC.md Sections
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/PROJECT_SPEC.md
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/PROJECT_SPEC.md
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/PROJECT_SPEC.md Section 17.7).
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/PROJECT_SPEC.md Section 17.7): `@when`
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/PROJECT_SPEC.md Section 17.7): `@when`
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/PROJECT_SPEC.md` (Runtime Principles) for the
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/PROJECT_SPEC.md Section
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/PROJECT_SPEC.md Section 17.15). A pure query —
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/PROJECT_SPEC.md Section
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/PROJECT_SPEC.md Section 17.15). A pure query —
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/PROJECT_SPEC.md`:
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.0",
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.0"
33
+ "@aftertext/compiler": "^0.1.1"
34
34
  },
35
35
  "devDependencies": {
36
36
  "@types/node": "^22.7.5",