hoi4-agent-tools 3.0.8 → 3.1.0

package/dist/hoi4_agent_tools/core/condition-evaluator.js

@@ -0,0 +1,399 @@
+import { assignments, astPathFor, firstScalar, nodeLocation, } from './source/index.js';
+import { resolveScopeContext, rootScopeContext, rootStateValue, scopeIdentity, scopeStateValue, } from './scenario-state.js';
+function helperWithArguments(block, invocation) {
+    const parameters = new Map();
+    for (const entry of invocation.entries) {
+        if (entry.type !== 'assignment' || entry.value.type !== 'scalar')
+            return undefined;
+        parameters.set(entry.key.value, entry.value.value);
+    }
+    const missing = new Set();
+    const substitute = (value) => value.replace(/\$([A-Za-z0-9_]+)\$/gu, (match, key) => {
+        const replacement = parameters.get(key);
+        if (replacement === undefined) {
+            missing.add(key);
+            return match;
+        }
+        return replacement;
+    });
+    const visit = (entry) => {
+        if (entry.type === 'scalar')
+            return { ...entry, value: substitute(entry.value) };
+        if (entry.type === 'block')
+            return { ...entry, entries: entry.entries.map(visit) };
+        return {
+            ...entry,
+            key: { ...entry.key, value: substitute(entry.key.value) },
+            value: entry.value.type === 'scalar'
+                ? { ...entry.value, value: substitute(entry.value.value) }
+                : { ...entry.value, entries: entry.value.entries.map(visit) },
+        };
+    };
+    const expanded = { ...block, entries: block.entries.map(visit) };
+    return missing.size === 0 ? expanded : undefined;
+}
+function combineAnd(values) {
+    if (values.includes('false'))
+        return 'false';
+    return values.includes('unresolved') ? 'unresolved' : 'true';
+}
+function combineOr(values) {
+    if (values.includes('true'))
+        return 'true';
+    return values.includes('unresolved') ? 'unresolved' : 'false';
+}
+function invert(value) {
+    return value === 'true' ? 'false' : value === 'false' ? 'true' : 'unresolved';
+}
+function bool(value) {
+    if (typeof value === 'boolean')
+        return value;
+    if (value === 'yes' || value === 'true')
+        return true;
+    if (value === 'no' || value === 'false')
+        return false;
+    return undefined;
+}
+function numeric(value) {
+    if (typeof value === 'number' && Number.isFinite(value))
+        return value;
+    if (typeof value === 'string' && value.trim() !== '' && Number.isFinite(Number(value)))
+        return Number(value);
+    return undefined;
+}
+function compare(left, right, operator) {
+    if (typeof left === 'number' && typeof right === 'number') {
+        if (operator === '>')
+            return left > right;
+        if (operator === '<')
+            return left < right;
+    }
+    return operator === '!=' ? left !== right : left === right;
+}
+function numberValue(expression, scenario, context, definitions, path, seen = new Set()) {
+    const literal = numeric(expression);
+    if (literal !== undefined)
+        return literal;
+    const identity = `${path ?? ''}:${expression}`;
+    if (seen.has(identity))
+        return undefined;
+    seen.add(identity);
+    const constant = expression.startsWith('constant:')
+        ? definitions.scriptConstants.get(expression.slice(9))
+        : expression.startsWith('@') && path !== undefined
+            ? definitions.localConstants.get(path)?.get(expression)
+            : undefined;
+    if (constant !== undefined)
+        return numberValue(constant.value, scenario, context, definitions, constant.file.displayPath, seen);
+    const direct = scopeStateValue(scenario, expression, context) ??
+        scopeStateValue(scenario, `variable.${expression}`, context);
+    if (direct !== undefined)
+        return numeric(direct);
+    for (let split = expression.lastIndexOf('.'); split > 0; split = expression.lastIndexOf('.', split - 1)) {
+        const scope = resolveScopeContext(scenario, expression.slice(0, split), context);
+        if (scope !== undefined)
+            return numberValue(expression.slice(split + 1), scenario, scope, definitions, path, seen);
+    }
+    return undefined;
+}
+function unresolved(assignment, candidate, reason) {
+    return {
+        state: 'unresolved',
+        unresolved: [
+            {
+                code: 'TRIGGER_UNRESOLVED',
+                message: reason,
+                path: assignment.key.value,
+                candidateId: candidate.id,
+                ...(candidate.provenance[0] === undefined ? {} : { provenance: candidate.provenance[0] }),
+            },
+        ],
+    };
+}
+function malformedBlock(block, candidate) {
+    if (block.entries.every(({ type }) => type === 'assignment'))
+        return undefined;
+    return {
+        state: 'unresolved',
+        unresolved: [
+            {
+                code: 'TRIGGER_UNRESOLVED',
+                message: 'Condition contains a bare value or block instead of a trigger assignment',
+                candidateId: candidate.id,
+                ...(candidate.provenance[0] === undefined ? {} : { provenance: candidate.provenance[0] }),
+            },
+        ],
+    };
+}
+function evaluateCheckVariable(block, scenario, candidate, assignment, scopeContext, definitions) {
+    const short = assignments(block).find(({ key }) => !['var', 'value', 'compare', 'tooltip'].includes(key.value));
+    const variable = firstScalar(block, 'var')?.value ?? short?.key.value;
+    const target = firstScalar(block, 'value')?.value ??
+        (short?.value.type === 'scalar' ? short.value.value : undefined);
+    if (variable === undefined || target === undefined)
+        return unresolved(assignment, candidate, 'check_variable requires declared var and value');
+    const path = candidate.provenance[0]?.path;
+    const leftNumber = numberValue(variable, scenario, scopeContext, definitions, path);
+    const rightNumber = numberValue(target, scenario, scopeContext, definitions, path);
+    if (leftNumber === undefined || rightNumber === undefined)
+        return unresolved(assignment, candidate, `Scenario does not resolve numeric operands ${variable} and ${target}`);
+    const compareName = firstScalar(block, 'compare')?.value ??
+        (short?.operator.text === '>'
+            ? 'greater_than'
+            : short?.operator.text === '<'
+                ? 'less_than'
+                : 'equals');
+    if (![
+        'greater_than',
+        'greater_than_or_equals',
+        'less_than',
+        'less_than_or_equals',
+        'not_equals',
+        'equals',
+    ].includes(compareName))
+        return unresolved(assignment, candidate, `Unsupported check_variable comparison ${compareName}`);
+    const result = compareName === 'greater_than'
+        ? leftNumber > rightNumber
+        : compareName === 'greater_than_or_equals'
+            ? leftNumber >= rightNumber
+            : compareName === 'less_than'
+                ? leftNumber < rightNumber
+                : compareName === 'less_than_or_equals'
+                    ? leftNumber <= rightNumber
+                    : compareName === 'not_equals'
+                        ? leftNumber !== rightNumber
+                        : leftNumber === rightNumber;
+    return { state: result ? 'true' : 'false', unresolved: [] };
+}
+function evaluateAssignmentCore(assignment, scenario, candidate, definitions, helperStack, scopeContext) {
+    const key = assignment.key.value;
+    if (assignment.value.type === 'block') {
+        const malformed = malformedBlock(assignment.value, candidate);
+        if (malformed !== undefined)
+            return malformed;
+        if (key === 'AND')
+            return evaluateTriggerBlock(assignment.value, scenario, candidate, definitions, helperStack, scopeContext);
+        if (key === 'OR') {
+            const children = assignments(assignment.value).map((child) => evaluateAssignment(child, scenario, candidate, definitions, helperStack, scopeContext));
+            return {
+                state: combineOr(children.map(({ state }) => state)),
+                unresolved: children.flatMap(({ unresolved: items }) => items),
+                helperProvenance: children.flatMap(({ helperProvenance }) => helperProvenance ?? []),
+            };
+        }
+        if (key === 'NOT' || key === 'NOR' || key === 'NAND') {
+            const children = assignments(assignment.value).map((child) => evaluateAssignment(child, scenario, candidate, definitions, helperStack, scopeContext));
+            const base = key === 'NAND'
+                ? combineAnd(children.map(({ state }) => state))
+                : combineOr(children.map(({ state }) => state));
+            return {
+                state: invert(base),
+                unresolved: children.flatMap(({ unresolved: items }) => items),
+                helperProvenance: children.flatMap(({ helperProvenance }) => helperProvenance ?? []),
+            };
+        }
+        if (key === 'check_variable')
+            return evaluateCheckVariable(assignment.value, scenario, candidate, assignment, scopeContext, definitions);
+        if (key === 'is_in_array' || key === 'is_variable_in_array') {
+            const arrayId = firstScalar(assignment.value, 'array')?.value;
+            const declaredValue = firstScalar(assignment.value, 'value')?.value;
+            if (arrayId === undefined || declaredValue === undefined)
+                return unresolved(assignment, candidate, `${key} requires array and value`);
+            const array = scopeStateValue(scenario, `array.${arrayId}`, scopeContext) ??
+                rootStateValue(scenario, `array.${arrayId}`);
+            if (!Array.isArray(array))
+                return unresolved(assignment, candidate, `Scenario does not declare array ${arrayId}`);
+            const compared = ['THIS', 'ROOT', 'PREV'].includes(declaredValue.toUpperCase()) ||
+                resolveScopeContext(scenario, declaredValue, scopeContext) !== undefined
+                ? scopeIdentity(resolveScopeContext(scenario, declaredValue, scopeContext) ?? scopeContext)
+                : (scopeStateValue(scenario, declaredValue, scopeContext) ?? declaredValue);
+            return { state: array.includes(compared) ? 'true' : 'false', unresolved: [] };
+        }
+        const resolvedScope = resolveScopeContext(scenario, key, scopeContext);
+        if (resolvedScope !== undefined)
+            return evaluateTriggerBlock(assignment.value, scenario, candidate, definitions, helperStack, resolvedScope);
+        const helper = definitions.scriptedTriggers.get(key);
+        if (helper !== undefined) {
+            if (helperStack.includes(key))
+                return unresolved(assignment, candidate, `Scripted trigger recursion detected at ${key}`);
+            const expanded = helperWithArguments(helper.value, assignment.value);
+            if (expanded === undefined)
+                return unresolved(assignment, candidate, `Scripted trigger ${key} requires declared scalar arguments for every parameter`);
+            const helperProvenance = {
+                path: helper.file.displayPath,
+                rootKind: helper.file.rootKind,
+                loadOrder: helper.file.loadOrder,
+                sourceHash: helper.file.sha256,
+                location: nodeLocation(helper.document, helper.node, key),
+                ...(astPathFor(helper.document, helper.node) === undefined
+                    ? {}
+                    : { astPath: astPathFor(helper.document, helper.node) }),
+                symbol: key,
+                helperChain: [...helperStack, key],
+            };
+            const evaluated = evaluateTriggerBlock(expanded, scenario, {
+                ...candidate,
+                document: helper.document,
+                provenance: [helperProvenance, ...candidate.provenance],
+            }, definitions, [...helperStack, key], scopeContext);
+            return {
+                ...evaluated,
+                helperProvenance: [helperProvenance, ...(evaluated.helperProvenance ?? [])],
+            };
+        }
+        const declaredScope = bool(rootStateValue(scenario, `scope.${key}`));
+        if (declaredScope !== undefined)
+            return { state: declaredScope ? 'true' : 'false', unresolved: [] };
+        return unresolved(assignment, candidate, `Scoped or compound trigger ${key} is not declared by the scenario`);
+    }
+    const right = assignment.value.value;
+    if (key === 'always') {
+        const value = bool(right);
+        return value === undefined
+            ? unresolved(assignment, candidate, 'always trigger is not boolean')
+            : { state: value ? 'true' : 'false', unresolved: [] };
+    }
+    if (key === 'has_country_flag' || key === 'has_global_flag' || key === 'has_state_flag') {
+        const explicit = bool(scopeStateValue(scenario, `flag.${right}`, scopeContext));
+        if (explicit !== undefined)
+            return { state: explicit ? 'true' : 'false', unresolved: [] };
+        const flags = scopeContext.expression === 'ROOT' ? scenario.flags : scopeContext.binding.flags;
+        if (scenario.closedFlags === false && flags?.includes(right) !== true)
+            return unresolved(assignment, candidate, `Scenario does not declare flag ${right}`);
+        return { state: flags?.includes(right) === true ? 'true' : 'false', unresolved: [] };
+    }
+    if (key === 'has_event_target') {
+        const eventTargets = scopeContext.binding.eventTargets ?? scenario.eventTargets;
+        return {
+            state: Object.hasOwn(eventTargets ?? {}, right) ? 'true' : 'false',
+            unresolved: [],
+        };
+    }
+    if (key === 'tag' || key === 'original_tag') {
+        const actor = scopeContext.expression === 'ROOT'
+            ? scenario.actor
+            : (scopeContext.binding.actor ?? scopeContext.binding.id);
+        if (actor === undefined)
+            return unresolved(assignment, candidate, `Scenario does not declare actor for ${key}`);
+        return {
+            state: compare(actor, right, assignment.operator.text) ? 'true' : 'false',
+            unresolved: [],
+        };
+    }
+    if (key === 'date') {
+        if (scenario.date === undefined)
+            return unresolved(assignment, candidate, 'Scenario does not declare date');
+        const dateNumber = (value) => {
+            const parts = /^(\d+)\.(\d{1,2})\.(\d{1,2})$/u.exec(value);
+            if (parts === null)
+                return undefined;
+            const month = Number(parts[2]);
+            const day = Number(parts[3]);
+            return month < 1 || month > 12 || day < 1 || day > 31
+                ? undefined
+                : Number(parts[1]) * 10_000 + month * 100 + day;
+        };
+        const leftDate = dateNumber(scenario.date);
+        const rightDate = dateNumber(right);
+        if (leftDate === undefined || rightDate === undefined)
+            return unresolved(assignment, candidate, 'Date comparison is not numeric');
+        return {
+            state: compare(leftDate, rightDate, assignment.operator.text) ? 'true' : 'false',
+            unresolved: [],
+        };
+    }
+    const helper = definitions.scriptedTriggers.get(key);
+    if (helper !== undefined && bool(right) !== undefined) {
+        if (helperStack.includes(key))
+            return unresolved(assignment, candidate, `Scripted trigger recursion detected at ${key}`);
+        const helperProvenance = {
+            path: helper.file.displayPath,
+            rootKind: helper.file.rootKind,
+            loadOrder: helper.file.loadOrder,
+            sourceHash: helper.file.sha256,
+            location: nodeLocation(helper.document, helper.node, key),
+            ...(astPathFor(helper.document, helper.node) === undefined
+                ? {}
+                : { astPath: astPathFor(helper.document, helper.node) }),
+            symbol: key,
+            helperChain: [...helperStack, key],
+        };
+        const evaluated = evaluateTriggerBlock(helper.value, scenario, {
+            ...candidate,
+            document: helper.document,
+            provenance: [helperProvenance, ...candidate.provenance],
+        }, definitions, [...helperStack, key], scopeContext);
+        return {
+            ...evaluated,
+            state: bool(right) === false ? invert(evaluated.state) : evaluated.state,
+            helperProvenance: [helperProvenance, ...(evaluated.helperProvenance ?? [])],
+        };
+    }
+    const declared = scopeStateValue(scenario, key, scopeContext) ??
+        numberValue(key, scenario, scopeContext, definitions, candidate.provenance[0]?.path);
+    if (declared === undefined)
+        return unresolved(assignment, candidate, `Scenario does not declare trigger ${key}`);
+    const expectedBoolean = bool(right);
+    const actualBoolean = bool(declared);
+    if (expectedBoolean !== undefined && actualBoolean !== undefined)
+        return { state: expectedBoolean === actualBoolean ? 'true' : 'false', unresolved: [] };
+    const leftNumber = numeric(declared);
+    const rightNumber = numberValue(right, scenario, scopeContext, definitions, candidate.provenance[0]?.path);
+    if (leftNumber !== undefined && rightNumber !== undefined)
+        return {
+            state: compare(leftNumber, rightNumber, assignment.operator.text) ? 'true' : 'false',
+            unresolved: [],
+        };
+    if (typeof declared === 'string')
+        return {
+            state: compare(declared, right, assignment.operator.text) ? 'true' : 'false',
+            unresolved: [],
+        };
+    return unresolved(assignment, candidate, `Trigger ${key} cannot compare the declared scenario value`);
+}
+function evaluateAssignment(assignment, scenario, candidate, definitions, helperStack, scopeContext) {
+    const evaluated = evaluateAssignmentCore(assignment, scenario, candidate, definitions, helperStack, scopeContext);
+    const source = candidate.provenance[0];
+    const provenance = candidate.document === undefined || source === undefined
+        ? source
+        : {
+            ...source,
+            location: nodeLocation(candidate.document, assignment, assignment.key.value),
+            ...(astPathFor(candidate.document, assignment) === undefined
+                ? {}
+                : { astPath: astPathFor(candidate.document, assignment) }),
+            symbol: assignment.key.value,
+        };
+    const expression = assignment.value.type === 'scalar'
+        ? `${assignment.key.value} ${assignment.operator.text} ${assignment.value.value}`
+        : assignment.key.value;
+    return {
+        ...evaluated,
+        trace: [
+            {
+                operation: 'eligibility',
+                expression,
+                applied: evaluated.state,
+                ...(provenance === undefined ? {} : { provenance }),
+            },
+            ...(evaluated.trace ?? []),
+        ],
+    };
+}
+export function evaluateTriggerBlock(block, scenario, candidate, definitions, helperStack = [], scopeContext = rootScopeContext(scenario)) {
+    const override = scenario.candidateOverrides?.[candidate.id];
+    if (override !== undefined)
+        return { state: override ? 'true' : 'false', unresolved: [] };
+    if (block === undefined)
+        return { state: 'true', unresolved: [] };
+    const malformed = malformedBlock(block, candidate);
+    if (malformed !== undefined)
+        return malformed;
+    const children = assignments(block).map((assignment) => evaluateAssignment(assignment, scenario, candidate, definitions, helperStack, scopeContext));
+    return {
+        state: combineAnd(children.map(({ state }) => state)),
+        unresolved: children.flatMap(({ unresolved: items }) => items),
+        helperProvenance: children.flatMap(({ helperProvenance }) => helperProvenance ?? []),
+        trace: children.flatMap(({ trace }) => trace ?? []),
+    };
+}

package/dist/hoi4_agent_tools/core/condition-model.js

@@ -0,0 +1 @@
+export {};

package/dist/hoi4_agent_tools/core/condition-schema.js

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+export const ScenarioScalarSchema = z.union([
+    z.string().max(16_384),
+    z.number(),
+    z.boolean(),
+    z.null(),
+]);
+export const ScenarioValueSchema = z.union([
+    ScenarioScalarSchema,
+    z.array(ScenarioScalarSchema).max(10_000),
+]);
+export const ConditionScopeBindingSchema = z
+    .object({
+    id: z.string().min(1).max(256),
+    type: z
+        .enum([
+        'country',
+        'state',
+        'character',
+        'unit_leader',
+        'operative',
+        'strategic_region',
+        'province',
+        'unknown',
+    ])
+        .optional(),
+    actor: z.string().max(256).optional(),
+    state: z.record(z.string(), ScenarioValueSchema).default({}),
+    flags: z.array(z.string().max(256)).max(10_000).optional(),
+    eventTargets: z.record(z.string(), z.string().max(256)).optional(),
+    weight: z.union([z.number(), z.string().max(256)]).optional(),
+})
+    .strict();
+export const ConditionResultSchema = z
+    .object({
+    token: z.string(),
+    sourcePath: z.string(),
+    state: z.enum(['true', 'false', 'unresolved']),
+    localisationKey: z.string().optional(),
+    unresolved: z.array(z.string()),
+})
+    .strict();

package/dist/hoi4_agent_tools/core/dependency-pages.js

@@ -0,0 +1,216 @@
+import { z } from 'zod/v4';
+import { hashCanonical } from './canonical.js';
+import { ServiceError } from './result.js';
+const ordinal = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+export const dependencyPageCursorSchema = z
+    .object({
+    version: z.literal(1),
+    key: z.string().regex(/^[a-f0-9]{64}$/u),
+    root: ordinal,
+    steps: ordinal,
+    emitted: ordinal,
+    cycles: ordinal,
+    depthStops: ordinal,
+    frames: z
+        .array(z.object({ edge: ordinal, next: ordinal, entered: z.boolean() }).strict())
+        .max(256),
+    visited: z.array(z.string().min(1)).max(1_000_000),
+})
+    .strict();
+/** Bounded DFS pages: retain only active ancestors and, for node policy, this root's visited nodes. */
+export class DependencyPages {
+    input;
+    key;
+    state;
+    roots;
+    outgoing = new Map();
+    branches;
+    visited;
+    constructor(input, restored) {
+        this.input = input;
+        if (!Number.isSafeInteger(input.maximumDepth) ||
+            input.maximumDepth < 1 ||
+            input.maximumDepth > 256 ||
+            input.edges.length > 1_000_000)
+            throw new ServiceError('DEPENDENCY_PAGE_INPUT_INVALID', 'Dependency pagination requires bounded edge and depth inventories');
+        const byId = new Map(input.edges.map(({ id }, index) => [id, index]));
+        if (byId.size !== input.edges.length ||
+            input.roots.some((id) => !byId.has(id)) ||
+            new Set(input.roots).size !== input.roots.length)
+            throw new ServiceError('DEPENDENCY_PAGE_INPUT_INVALID', 'Dependency edge and root identities must be unique and all roots must exist');
+        this.key = hashCanonical({ algorithm: 'dependency-pages.v1', ...input });
+        this.roots = input.roots.map((id) => byId.get(id));
+        this.branches = new Set(input.branches);
+        for (const [index, { from }] of input.edges.entries()) {
+            const values = this.outgoing.get(from) ?? [];
+            values.push(index);
+            this.outgoing.set(from, values);
+        }
+        if (input.reverseEdges)
+            for (const values of this.outgoing.values())
+                values.reverse();
+        if (restored === undefined)
+            this.state = {
+                version: 1,
+                key: this.key,
+                root: 0,
+                steps: 0,
+                emitted: 0,
+                cycles: 0,
+                depthStops: 0,
+                frames: [],
+                visited: [],
+            };
+        else {
+            const parsed = dependencyPageCursorSchema.safeParse(restored);
+            if (!parsed.success)
+                throw new ServiceError('DEPENDENCY_CURSOR_INVALID', 'Dependency continuation has an invalid state schema');
+            this.state = parsed.data;
+        }
+        if (this.state.key !== this.key)
+            throw new ServiceError('DEPENDENCY_CURSOR_STALE', 'Dependency continuation does not match the exact source revision and traversal contract');
+        this.validate();
+        this.visited = new Set(this.state.visited);
+    }
+    validate() {
+        const invalid = () => {
+            throw new ServiceError('DEPENDENCY_CURSOR_INVALID', 'Dependency continuation has inconsistent counters or DFS ancestry');
+        };
+        const { root, frames, visited, steps, emitted, cycles, depthStops } = this.state;
+        if (root > this.roots.length ||
+            frames.length > this.input.maximumDepth ||
+            (root === this.roots.length && frames.length !== 0) ||
+            emitted > steps ||
+            cycles + depthStops > emitted ||
+            new Set(visited).size !== visited.length ||
+            (frames.length === 0 && visited.length !== 0) ||
+            (this.input.visitPolicy === 'edge_path' && visited.length !== 0))
+            invalid();
+        const nodes = new Set(this.input.edges.map(({ to }) => to));
+        if (visited.some((node) => !nodes.has(node)))
+            invalid();
+        const ancestors = new Set();
+        for (const [index, frame] of frames.entries()) {
+            const edge = this.input.edges[frame.edge];
+            if (edge === undefined || ancestors.has(edge.to))
+                invalid();
+            ancestors.add(edge.to);
+            if (frame.next > (this.outgoing.get(edge.to)?.length ?? 0) ||
+                (!frame.entered && (index !== frames.length - 1 || frame.next !== 0)))
+                invalid();
+            if (index === 0) {
+                if (frame.edge !== this.roots[root])
+                    invalid();
+            }
+            else {
+                const parent = frames[index - 1];
+                const previous = this.input.edges[parent.edge];
+                if (!parent.entered ||
+                    parent.next === 0 ||
+                    this.outgoing.get(previous.to)?.[parent.next - 1] !== frame.edge ||
+                    previous.to !== edge.from ||
+                    !this.branches.has(edge.to))
+                    invalid();
+            }
+            if (this.input.visitPolicy === 'node' && !visited.includes(edge.to))
+                invalid();
+        }
+    }
+    cursor() {
+        return {
+            ...this.state,
+            frames: this.state.frames.map((frame) => ({ ...frame })),
+            visited: [...this.visited],
+        };
+    }
+    page(maximumRecords, maximumWork, signal) {
+        if (!Number.isSafeInteger(maximumRecords) ||
+            maximumRecords < 1 ||
+            maximumRecords > 5_000 ||
+            !Number.isSafeInteger(maximumWork) ||
+            maximumWork < 1 ||
+            maximumWork > 100_000)
+            throw new ServiceError('DEPENDENCY_PAGE_BOUND_INVALID', 'Dependency pages require 1–5,000 records and 1–100,000 work transitions');
+        const records = [];
+        const startedAt = this.state.steps;
+        const emit = (kind, extra) => {
+            records.push({
+                kind,
+                root: this.state.root,
+                path: [
+                    ...this.state.frames.map(({ edge }) => edge),
+                    ...(extra === undefined ? [] : [extra]),
+                ],
+            });
+            this.state.emitted++;
+            if (kind === 'cycle')
+                this.state.cycles++;
+            if (kind === 'depth')
+                this.state.depthStops++;
+        };
+        while (this.state.root < this.roots.length && this.state.steps - startedAt < maximumWork) {
+            signal?.throwIfAborted();
+            if (this.state.steps === Number.MAX_SAFE_INTEGER)
+                throw new ServiceError('DEPENDENCY_PAGE_COUNTER_LIMIT', 'Dependency pagination exhausted its exact integer work counter');
+            const frame = this.state.frames.at(-1);
+            if (frame === undefined) {
+                const edge = this.roots[this.state.root];
+                this.state.frames.push({ edge, next: 0, entered: false });
+                this.visited.clear();
+                if (this.input.visitPolicy === 'node')
+                    this.visited.add(this.input.edges[edge].to);
+            }
+            else if (!frame.entered) {
+                if (records.length >= maximumRecords)
+                    break;
+                emit('visit');
+                frame.entered = true;
+            }
+            else {
+                const node = this.input.edges[frame.edge].to;
+                const candidate = this.outgoing.get(node)?.[frame.next];
+                if (candidate === undefined) {
+                    this.state.frames.pop();
+                    if (this.state.frames.length === 0) {
+                        this.state.root++;
+                        this.visited.clear();
+                    }
+                }
+                else {
+                    const edge = this.input.edges[candidate];
+                    const cycle = this.state.frames.some((ancestor) => this.input.edges[ancestor.edge].to === edge.to);
+                    const kind = !this.branches.has(edge.to)
+                        ? 'terminal'
+                        : cycle
+                            ? 'cycle'
+                            : this.state.frames.length >= this.input.maximumDepth
+                                ? 'depth'
+                                : undefined;
+                    if (kind !== undefined) {
+                        if (records.length >= maximumRecords)
+                            break;
+                        emit(kind, candidate);
+                        frame.next++;
+                    }
+                    else {
+                        frame.next++;
+                        if (this.input.visitPolicy === 'edge_path' || !this.visited.has(edge.to)) {
+                            if (this.input.visitPolicy === 'node')
+                                this.visited.add(edge.to);
+                            this.state.frames.push({ edge: candidate, next: 0, entered: false });
+                        }
+                    }
+                }
+            }
+            this.state.steps++;
+        }
+        return {
+            records,
+            finished: this.state.root === this.roots.length,
+            completedRoots: this.state.root,
+            totalRoots: this.roots.length,
+            work: this.state.steps - startedAt,
+            cursor: this.cursor(),
+        };
+    }
+}