rulvar API reference / @rulvar/core
@rulvar/core
Namespaces
| Namespace | Description |
|---|---|
| StandardJSONSchemaV1 | - |
| StandardSchemaV1 | - |
Classes
| Class | Description |
|---|---|
| AdmissionController | - |
| AdmissionRejectedError | A structural admission rejection (maxDepth, maxChildrenPerNode, maxTotalSpawns) from the AdmissionController (M6-T06). The rejection verdict is embedded in the carrying spawn-admission decision entry and replays identically; the error surfaces the embedded AdmitRejectReason in data to the caller (a typed tool error for orchestrators) and MUST NOT tear down the run. Budget-code rejections throw BudgetExhaustedError instead, keeping the budget exhaustion semantics (https://docs.rulvar.com/guide/budgets). |
| AgentCallError | The rejection carrier of ctx.agent value-form calls: a real Error that structurally satisfies the typed AgentError and carries the full AgentResult for Settled mapping. Deliberately not a RulvarError: AgentError is not in the closed code registry. |
| BudgetExhaustedError | The run budget ceiling blocked further work. The budget guard denial is a decision entry; ctx primitives throw this as AgentError kind 'budget'; the run reports outcome 'exhausted', overriding 'error'. |
| ConfigError | Construction- and definition-time misconfiguration: duplicate adapterId, non-git host for worktree isolation, worker over a non-leasable store, failed schema projection. Never journaled; raised before any run effect. |
| DedupIndex | The DedupIndex: a pure fold over spawn roots, severing abandons, and node.link entries. Prices fold from journal facts (servedBy, usage) through the injected price function; on replay the embedded verdict values are authoritative and this fold serves integrity only. |
| EventBus | The per-run event bus. seq is strictly increasing in emission order; iterate() yields events from subscription onward; on() is the callback form over the same stream and the same seq values. |
| ExternalRegistry | Per-run registry of open external suspensions plus the run's activity counter: when every in-flight branch is blocked on suspensions (activity zero, waiters open), the run quiesces into outcome 'suspended'. |
| FileModelKnowledgeStore | The SPI seam. commit performs CAS on the monotonic snapshot version, mirroring the fencing-epoch discipline of LeasableStore; concurrent maintenance commits serialize through CAS rejection and rebase. commit is UNREACHABLE from the runtime: runs hold ModelKnowledgeHandle. |
| FileTranscriptStore | File-backed TranscriptStore (M6-T02): blobs (transcripts, checkpoints, persisted CompiledWorkflow sources) as one file per ref under dir, so compiled runs resume across processes. Refs follow the <runId>/<name> convention; each path segment is checked filesystem-safe and nested segments become directories. |
| GitWorktreeProvider | The shipped git worktree lifecycle. A non-git host is a typed ConfigError at acquire. |
| InMemoryStore | - |
| InMemoryTranscriptStore | In-memory TranscriptStore. Refs follow the <runId>/<name> convention so list(runId) can filter without a side index. |
| InProcessRunner | The mode (a) runner for human-authored closures. Determinism is enforced by convention, lint, and the ctx shims, NOT by a VM: only the sequence of keys must be stable. Dev mode (NODE_ENV !== 'production') patches Date.now and Math.random for the duration of execute to emit one warning per run pointing at ctx.now()/ctx.random(); the patch preserves behavior and restores the prior functions on exit (nesting-safe by capturing the prior value; concurrent runs may lose the warning, never correctness). |
| InvalidResolutionError | A resolution attempt against an already-closed suspension, rejected under the first-closing-wins fold; appends no entry (producers ship in M2). |
| JournalCompatibilityError | Refusal to open a journal whose hashVersion falls outside the engine's support window (producers ship in M2). The registry code is 'journal_compat'; the sub-codes live on subCode and in data. |
| JournalMatcher | The matching engine over a loaded journal. Consumption is per logical operation (running/terminal pairs count once); candidates are consumed in journal order, first unconsumed match wins (this also resolves cross-version double matches deterministically). |
| JournalMissError | A replay-strict run encountered a call that would go live (@rulvar/testing; producers ship in M2). |
| JournalOrderViolation | A breach of the total per-run append order: an unfenced concurrent writer or a store violating contract A2 (https://docs.rulvar.com/guide/stores). |
| JsonlFileStore | - |
| KeyedLimiter | - |
| KnowledgeCasError | commit() on a ModelKnowledgeStore against a snapshot version that is no longer current. Retryable by contract: re-read current(), rebase the ops, commit again, mirroring the lease fencing discipline. |
| LeaseHeldError | acquire() on a currently held lease. Retryable by contract: retry after the lease ttl elapses or the holder releases. |
| LineageIndex | The incremental lineage fold: attempts, escalation debits, stall streaks, single-live-attempt, and legacy canonization, computed from journal entries only. absorb is idempotent by seq cursor; every read accepts an optional uptoSeq pin so renders stay snapshot-stable. |
| ModelRetry | - |
| NonSerializableValueError | A value failed the journal append JSON-serializability check. Never journaled; thrown at the call site whose value failed the check. |
| NoProgressDetector | Counts consecutive progress-free turns. A turn with at least one tool call (or, later, an artifact delta) resets the streak; a turn with neither lengthens it; the detector trips when the streak reaches the threshold AND the loop would otherwise continue. |
| OrchestratorCapConfigError | Invalid orchestrator cap and finalize-reserve configuration, thrown before the first LLM call (DEF-7; producers ship in M6/M7). |
| ParallelSiteCounter | Allocates parallel site numbers per enclosing scope: a monotonic counter in execution order, not source position. Because every scope body is sequential by construction (I3), allocation order is deterministic and identical on every replay. |
| PlanInvariantError | PlanRunner plan-invariant rejection (producers ship in M7). |
| Replayer | Per-run journal kernel front end. Everything is per instance: no module state anywhere. |
| ReplayPlanHashMismatch | Raised at resume when the refolded plan state disagrees with the journaled planHash chain (producers ship in M7). |
| ResolutionArbiter | Per-run, per-target FIFO serializer of resolution/abandon attempts: classification against the in-memory fold -> durable append -> settle exactly once; losing attempts are ALSO appended and become journaled noops by fold classification. Winner effects run strictly after the critical section (the caller's job). Cross-process protection remains the LeasableStore fencing epoch. |
| ResolutionFold | The first-closing-wins fold over a loaded journal: one pass by seq, bit-identical on every store returning the same entries. Resolution values are validated at consumption against the schema pinned INSIDE the suspended entry payload (canonical bare JSON Schema); a schema-invalid offline resolution classifies invalid and does NOT close the target. Abandon coverage is the target seq plus the transitive child scope-prefix; the AbandonFold consumed by the replay predicate is a projection of THIS fold (not a separate pass). |
| RulvarError | Base class for all engine-raised errors. "Retryable" means the engine's own retry machinery (RetryPolicy under the journal) MAY retry; it never means a provider SDK autoretry, which is disabled. |
| RunBudget | The per-run budget account tree. All spend accounting is per instance; the journal remains the durable source (the root is seeded by the ledger fold on resume, M2; sub-account reserves are recovered from spawn-admission decision entries, M6). |
| SandboxError | A WorkerSandboxRunner resource-limit breach (M6-T02): crossing timeoutMs or memoryMb terminates the worker and the run completes with outcome 'error' carrying this error's WireError projection; data records { reason: 'timeout' |
| ScriptRejected | compileScript rejected planner-generated source. Never journaled as its own entry; surfaced as diagnostics to the plan() self-repair loop (producers ship in M6). |
| Semaphore | - |
| SpanRegistry | Spans form a tree per run; spanId values are engine-minted opaque strings, unique per run, pure telemetry, never identity. |
| TerminationAccount | The single per-run TerminationAccount: debit ONLY. No credit operation exists by construction; reclaim never replenishes anything (DEF-5 interaction). Live: the engine debits the in-memory account, writes the carrying entry with the balance-after, then applies effects. Resume state is rebuilt by TerminationFold from the journal, never from live config. |
Interfaces
| Interface | Description |
|---|---|
| AbandonedSpendView | The abandoned-spend ledger fold. |
| AbandonFold | - |
| AdmissionDecision | The full admission decision embedded in the carrying entry. |
| AdmissionStatsBefore | Live pre-append snapshot embedded in the decision entry (DEF-2/DEF-3). |
| AdmitLineage | The lineage block every non-reject verdict carries (DEF-3). |
| AdmitSpec | What the admission point needs to know about one spawn. |
| AgentIdentityInput | Spawn entries: ctx.agent and orchestrator spawn tools (kind 'agent'). |
| AgentOpts | Per-spawn options. The identity split is normative: agentType, model/routing/effort (the requested modelSpec), schema (schemaHash), and key enter the content key; everything else is policy or telemetry and never re-keys entries. Fields whose machinery lands later (tools, isolation, escalation, lineage, ladder, retry) arrive with their milestones. |
| AgentProfile | The canonical, complete AgentProfile shape; M1 honors description, model, routing, effort, limits, and estCost. A profile never carries a prompt or a schema. |
| AgentProfilePermissions | Profile-level permissions. inheritPermissions governs SUBAGENT inheritance (mode c orchestrators, M6+): children get their own config only unless explicitly opted in. It is carried as data here and consumed by the spawning layers. |
| AgentResult | - |
| AgentResultMeta | The consumer-facing reuse mark on results. |
| ApproachSignatureInputs | The identity inputs of the coarse signature (prompt prose excluded). |
| ApprovalDecision | The resolution value shape of a tool-approval suspension (M3-T03). |
| ApprovalIdentityInput | Tool-approval suspensions (kind 'approval'). |
| Artifact | Artifact: the normative shape of AgentResult.artifacts entries. |
| BriefOpts | Options of ctx.brief (concrete shape fixed in M6-T10): the content to distill plus an optional instruction; the invocation resolves role 'summarize', so it needs defaults.routing.summarize, a profile, or the explicit model. |
| BudgetAccountView | Read-only projection of one account. |
| BudgetDefaults | - |
| BudgetHooks | Budget hooks bound by the three-layer budget. |
| BudgetReserve | Layer-1 reservation embedded in the carrying decision entry. |
| CacheHint | Provider-neutral declaration of intended prompt-cache boundaries. Transport-level cost optimization only: MUST NOT enter IdentityInput and MUST NOT change response semantics. |
| CanonicalLadderSpec | LadderSpec after canonicalization: every rung's effort resolved to an explicit value. |
| ChatRequest | The provider-neutral chat request. Sampling parameters (temperature, top_p, top_k) are deliberately absent from the first-class surface: both first-class providers reject them on current reasoning models; where a target legitimately supports them they travel through the adapter's providerOptions namespace, subject to caps scrubbing. |
| CheckpointState | The canonical-history snapshot at a turn boundary. |
| ChildIdentityInput | Nested workflow spawns: ctx.workflow (kind 'child'). |
| ClaimValidationOptions | - |
| CollectedTurn | One collected model turn, assembled from the stream by the agent loop. |
| CollectOpts | - |
| CompactionConfig | Per-profile compaction config (AgentProfile). |
| CompiledPermissionChain | - |
| CompiledWorkflow | Source-backed workflow admissible to the worker sandbox; produced by compileScript (M6). Declared now so the ScriptRunner seam is shaped once; feeding a closure to the sandbox stays impossible by types. |
| CostAttribution | Per-run cost attribution buckets consumed by CostReport (M1-T10/T11). |
| CostReport | Full contract: https://docs.rulvar.com/guide/observability. |
| CreateEngineOptions | - |
| Ctx | The canonical Ctx interface, M1 members. |
| DeclaredLadder | One declared ladder of the run, named by its agentType. |
| DedupNote | Telemetry for a SpawnKey match admitted fresh. |
| DonorCandidate | One donor candidate surfaced by the DedupIndex fold. |
| DonorRef | The rich donor descriptor embedded in reuse verdicts. |
| DroppedItem | One dropped result: its source, scope, entry ref, and wire error. |
| EffectiveUsageLimits | - |
| Engine | - |
| EngineDefaults | - |
| EscalationDigest | The escalation block of a digest. |
| EscalationLimits | Lineage limits, monotonically consumed and never replenished (DEF-3). |
| EscalationOptions | - |
| EscalationReport | - |
| EscalationRequest | The model-facing request: the report minus the runtime-filled fields. |
| ExtensionAppendInput | One append into an extension-owned sequential scope. |
| ExtensionDispatchSpec | A child dispatch under an explicit scope (plan/NodeId). |
| ExternalIdentityInput | External inputs: ctx.awaitExternal (kind 'external'). |
| ExtractNecessityInput | The inputs of the extract-necessity rule. |
| FailoverTarget | One resolved failover target (rich form). |
| FallbackField | The degenerate fallback field: one agent-level second attempt. |
| FileModelKnowledgeStoreOptions | - |
| GateAudit | The ctx-side verdict for one dispatch, produced by the permission chain (M3-T03). For 'ask' the loop writes the turn checkpoint with the pending state FIRST, then suspend() journals the approval entry (or re-matches an existing one) and parks until a resolution closes it. |
| GitWorktreeProviderOptions | - |
| GraftBoot | Graft bootstrap payload. |
| IsolationProvider | - |
| JournalOperation | One logical journaled operation: its dispatch entry plus its terminal, when present. |
| JournalSerializationHook | - |
| JournalStore | - |
| KbProposal | One orchestrator model-knowledge proposal (phase 3). A proposal is a run-ledger record, NOT a claim: it lives ONLY in the RunLedger section modelObservations, is never rendered into any prompt of any run before the human gate (absolute quarantine, the note included), and reaches the gate exclusively through LedgerExport. The engine assembles it from the tier-relative kb_propose payload: the subject model is resolved by the engine from the referenced lineage's declared ladder, never named by the orchestrator; evidence must resolve into the proposing run's own decision entries. |
| KeyDeriver | - |
| KeyRing | - |
| KnowledgeSnapshot | - |
| LadderSpec | The author-facing ladder declaration. This is the SINGLE declaration of the ladder family: other layers reference it and never redeclare (runtime semantics land in M7). |
| LeasableStore | Lease capability: acquire on a held lease MUST reject with a typed LeaseHeldError; renew MUST run at an interval of at most ttl/3; an append carrying a stale epoch MUST be rejected and never appear in load. |
| Ledger | - |
| LineageCounters | - |
| LineageRef | The computed lineage record of one spawn-authorizing decision entry. |
| LineageStats | The pure lineage fold rendered in plan_view and WakeDigest, always pinned to a snapshot (uptoSeq), never a live read inside a turn. approaches groups settled history by approachSig; a group whose attempts have not settled yet is omitted (there is no outcome to learn from), while attemptsUsed still counts every authorized attempt. |
| McpConfig | - |
| MechanicalGateVerdict | The verdict of one mechanical acceptance gate evaluation. |
| ModelChoice | - |
| ModelClaim | - |
| ModelEpochInputs | - |
| ModelKnowledgeStore | The SPI seam. commit performs CAS on the monotonic snapshot version, mirroring the fencing-epoch discipline of LeasableStore; concurrent maintenance commits serialize through CAS rejection and rebase. commit is UNREACHABLE from the runtime: runs hold ModelKnowledgeHandle. |
| Msg | - |
| NodeLinkValue | The node.link entry value: an ordinary content-keyed effect entry. |
| OrchestrateOptions | Options for orchestrate(engine, goal, o?). |
| OrchestratorBudgetSpec | Budget contract: https://docs.rulvar.com/guide/budgets; the cap machinery (reserves, freeze) completes in M7 (DEF-7). |
| OrchestratorExtension | The extension contract. PlanRunner implements it in @rulvar/plan; the mode (c) orchestrator hosts it. Everything is optional except the toolset: an extension that adds no tools has no reason to exist. |
| OrchestratorExtensionIO | The per-run IO the extension closes over (engine-owned effects). |
| OrchestratorRuntime | The engine seam the spawn tools close over (never on ToolContext). |
| PendingExternal | Suspensions still open at settle time; producers arrive with M2. |
| PendingToolTurn | Mid-turn suspension state (M3-T03): the turn's already-executed tool results plus the call awaiting an approval resolution, so resume continues the SAME turn without re-running executed tools. |
| PermissionConfig | Host-side permission configuration (engine defaults.permissions). |
| PhaseTarget | One serving target of a phase: the primary or a failover fallback. |
| PipelineCollected | Pipeline results plus the dropped evidence, returned by onItemError: 'collect'. |
| PipelineOpts | - |
| PriceTable | - |
| Pricing | Per-model pricing in USD per million tokens. The registry's versioned price table wins over adapter- reported caps.pricing, which is a fallback only. |
| ProviderAdapter | - |
| QualityFloors | - |
| RandIdentityInput | Deterministic shims: ctx.now / ctx.random / ctx.uuid (kind 'rand'). |
| RefEntryAppender | The append surface the arbiter drives (implemented by the Replayer). |
| RefusalInfo | - |
| ResolutionLayer | One layer's contribution to the resolution merge. |
| ResolvedInvocation | The resolved, scrubbed result of one invocation's resolution. |
| ResolvedToolset | The spawn's frozen toolset snapshot plus its identity hash. |
| ResumeHandle | - |
| ResumeOptions | - |
| ResumePreview | Resume-time hit/miss/orphan accounting. |
| ResumeReport | - |
| RetryPolicy | - |
| ReuseConfig | The reuse block of AdmissionConfig. |
| RunAgentOptions | - |
| RunEventSink | Span-aware event sink: bodies are stamped into the WorkflowEvent envelope by the per-run EventBus (M1-T10); spanId defaults to the run root span when omitted. |
| RunHandle | - |
| RunInternals | Everything one run's ctx needs; created per run by the engine (M1-T11). |
| RunOptions | - |
| RunProfile | - |
| RuntimeEventSink | Minimal internal event sink; the typed WorkflowEvent envelope wraps it in M1-T10. |
| SandboxBridge | - |
| SandboxBridgeOptions | - |
| ScriptRunner | - |
| ScrubNote | A scrub performed by the router; surfaced as a warning-level event by the engine. |
| SerializationHook | createEngine({ serialization }): absent means identity, no wrapping. |
| ShellPatternRules | - |
| ShellSegment | Argv-parsing shell matcher (M5-T06): shell allow/ask/deny is matched through a real argv parser, never a string prefix. The composition rule is the entire point: for a compound command the verdict is the strictest across segments, and any unmatched segment yields ask, never a silent allow: npm test; rm -rf / MUST yield ask (or deny when rm patterns are denied) even when npm test is allow-listed. |
| SinglePhaseAppend | - |
| SpanMinter | Mints span ids in the run > phase > agent > tool > child hierarchy. |
| SpawnAdmissionValue | The journaled spawn-admission payload the runtime writes and recovers. |
| SpawnAgentParams | The spawn parameters as validated JSON (a TaskSpec subset). |
| SpawnLineage | The value-part lineage block embedded in decision entries: the computed LineageRef plus the normalized tag (the request part holds the RAW proposal; the value part holds what was COMPUTED and is reused byte-exact on replay). |
| SpawnLineageOpt | The spawn-options lineage block (ctx.agent, ctx.workflow, spawn_agent, add_task). |
| SpawnRecord | One spawned child tracked by the orchestrator runtime. |
| StandardJSONSchemaV1 | The Standard JSON Schema interface. |
| StandardSchemaV1 | The Standard Schema interface. |
| StepIdentityInput | Journaled effectful steps: ctx.step (kind 'step'). |
| SuspendedAppend | - |
| TaskDigest | The per-child digest handed to the orchestrator. |
| TerminalPatch | - |
| TerminationAccountSnapshot | - |
| TerminationDeniedValue | The value payload of a termination.denied entry. |
| TerminationInitValue | The value payload of a termination.init entry. |
| TerminationLimits | The frozen limits vector written into termination.init. |
| ToolCallRequest | One model-issued tool call as the loop dispatches it. |
| ToolContext | The context handed to execute (and to permission hooks and canUseTool). Deliberately exposes NO spawn primitives: tools are leaves of the call-and-return tree (invariant I3); all spawning flows through Ctx primitives. |
| ToolContextSeed | - |
| ToolContract | The identity-bearing tool contract: exactly what the model sees and exactly what toolsetHash hashes. Never contains execute or any closure. |
| ToolDef | A defined tool. The identity projection is the ToolContract { name, description, parameters, version }: exactly what the model sees and exactly what toolsetHash hashes; execute and every other non-contract field are excluded by construction. |
| ToolInit | - |
| ToolRuntime | The spawn's frozen toolset plus the per-call context factory, prepared by the ctx layer (M3-T01). The contracts are the canonical identity projection already hashed into the spawn's content key; the loop sends exactly them to the model. |
| ToolSource | The ToolSource seam: tools() yields the source's current ToolDefs. The toolset snapshot for a given agent spawn is captured at spawn time and hashed into the spawn's identity via toolsetHash; a mid-run change MUST NOT mutate an in-flight agent's toolset. |
| ToolSourceSession | Session handle passed to ToolSource.tools (minimal in v1; audited at M9). |
| TranscriptSerializationHook | - |
| TranscriptStore | - |
| UsageLimits | UsageLimits (M1-T06): normative limit vocabulary and the per-spawn merge. |
| VerifiedRecommendation | One compiled start-tier recommendation of the verified layer. |
| WakeBudgetBlock | Passive budget visibility in every digest (DEF-7). |
| WakeDigest | The FINAL normative WakeDigest: one coordinated schema change inside the hashVersion-2 profile (XF-12). The digest render enters the content key of orchestrator turns. In runs without the PlanRunner extension the termination, budget, and reuse blocks are all-zero and planHash is empty, mirroring the CostReport convention. |
| Workflow | Closure-form workflow value; in-process only. |
| WorkflowCallOpts | Options of ctx.workflow; key replaces args in the child identity. |
Type Aliases
| Type Alias | Description |
|---|---|
| AbandonAttempt | - |
| AbandonPayload | Payload of abandon ref-entries (DEF-4/DEF-5). |
| AbortClass | The consumer-visible dedicated class marker (FR-424). |
| AdaptiveEvents | Adaptive orchestration, resolutions, and accounting: emitted only by runs where the corresponding machinery is active (applicability per mode: https://docs.rulvar.com/guide/adaptive-orchestration). The types land as one closed catalog with M7-T03; emitters arrive with their tasks. |
| AdmitRejectReason | The merged reject-code set. |
| AdmitVerdict | The unified admission verdict (XF-11). One union, closed now; every debit is atomic with its carrying decision entry and embeds the balance-after (DEF-2). |
| AgentError | The structured error value carried on AgentResult.error and journaled inside the agent terminal entry. Deliberately NOT a RulvarError subclass. |
| AgentEvents | Agent lifecycle. |
| AgentStatus | - |
| AttemptOutcomeClass | Attempt outcome classes entering LineageStats. |
| Bytes | L0 byte-blob alias consumed by TranscriptStore and IsolationProvider. |
| CacheTtl | - |
| CanonicalId | Engine-minted ULID identifying a tool call across providers. The library, not the provider, mints tool-call ids; each adapter keeps a bijective map between canonical ids and wire ids (toolu_* / call_*) in both directions. |
| CanonicalIdentity | The projected, JCS-serializable identity under one profile. |
| CanonicalModelSpec | Identity-facing canonical form of a RESOLVED model request; the value that enters AgentIdentityInput.modelSpec. providerOptions and fallbacks NEVER enter this form: they are delivery options, excluded from identity exactly like label, phase, onError, retry, and replay. effort is absent exactly when no layer of the chain and no role effort default resolves one. |
| CanUseTool | - |
| ChatEvent | The single canonical stream-event vocabulary yielded by ProviderAdapter.stream. Adapters MUST emit exactly one terminal event per stream (finish or error). |
| ClaimClass | - |
| ClaimOp | - |
| ClaimStatus | - |
| CoreEvents | Run lifecycle and core telemetry (M1 subset). |
| DebitResult | - |
| DerivedKey | A derived key, or the guaranteed non-match marker. |
| DeriverRegistry | - |
| DispositionRule | Per-effective-status disposition rules; DATA on the profile, consumed only by the single canonical replayDisposition function (there is NO replayAction method). |
| DispositionTable | - |
| Effort | Canonical effort: exactly five levels, a string-literal union, never a TS enum. OpenAI 'none' has no canonical equivalent and is reachable only via providerOptions. |
| EntryKind | The single kinds registry v2. Readers MUST tolerate unknown kinds; stores pass them through byte-for-byte (obligation A4). |
| EntryRef | The canonical EntryRef between entries is seq. |
| EntryStatus | The stored status vocabulary, exactly. 'skipped' is DELIBERATELY absent: it is a derived fold status, never persisted. |
| ErrorClass | - |
| ErrorCode | The closed error-code registry. 'agent' is carried by the AgentError value projection, not by a RulvarError subclass. |
| ErrorPolicy | - |
| EscalatedResult | - |
| EscalationDecision | - |
| EscalationKind | Closed in v1. |
| EvidenceRef | entryRef is the journal entry seq (canonical EntryRef; XF ruling). |
| FailoverTrigger | Transport-level failover triggers; budget is explicitly excluded. |
| FallbackTrigger | The degenerate fallback triggers. |
| FinishInfo | Typed finish outcomes. A refusal MUST surface as a typed finish outcome carrying the provider stop details; it MUST NOT be projected to a null output silently. |
| Gate | Ladder acceptance gates. Spot-check sibling selection is strictly via ctx.random, never Math.random. |
| GateRecord | The write gate. The human variant carries the MANDATORY attribution attestation (ruledOut over the checklist prompt, tools, difficulty, transient-provider; recommended contrast evidence): rubber-stamping "evidence exists" is constructively impossible. The eval-confirmed variant is reserved for v2, outside the committed roadmap. |
| HashVersion | Versions the ENTIRE identity and replay pipeline as one unit: canonical JSON algorithm, identity field sets, hash function, schema/toolset hash derivation, scope grammar and ordinal rules, replay predicate, fold defaults, and the kind/status vocabularies. |
| HookVerdict | - |
| IdentityInput | - |
| InvocationRole | - |
| IsolationSpec | The canonical identity encoding of spawn isolation: this exact value domain enters spawn identity. 'readonly' is a determinism and blast-radius declaration, not containment. |
| Issue | The vendored Standard Schema issue shape: validation issues carried on AgentError and surfaced to the model during bounded schema re-prompts. |
| JournalCompatSubCode | Sub-code detail of JournalCompatibilityError. |
| JournalEntry | Final entry form (hashVersion 2). All journaled values MUST be JSON-serializable; a violation raises a typed NonSerializableValueError at the call site. append is serialized by a per-run queue. |
| Json | L0 JSON value domain. |
| JsonSchema | A JSON Schema document (draft 2020-12) as plain JSON data. Canonical serialization and hashing rules live with the KeyDeriver. |
| KbProposalTrigger | The closed trigger vocabulary of kb_propose (phase 3). |
| Lease | Lease token for queue-mode ownership; epoch is the fencing token. |
| LineageRelation | The closed relation vocabulary of the minting and inheritance table. |
| LogicalTaskId | Logical-task identity across rebirths (DEF-3); engine-minted ULID. |
| MatchResult | - |
| MechanicalGateProfile | A mechanical acceptance gate: an engine-registered NAMED pure function over AgentResult.artifacts. The registry is per engine like every other registry; the ladder driver journals each evaluation as a decision entry, so the ladder fold consumes only journaled verdicts, never live re-evaluation. |
| ModelCaps | Capability facts the router consumes for tier selection and scrubbing. |
| ModelKnowledgeHandle | The runtime handle: with propose() deleted from the design and commit absent from this shape, a run has no write path into the cross-run medium at all. |
| ModelListConstraint | An explicit allowlist and denylist; deny wins over allow. |
| ModelRef | Strictly 'adapterId:model', no query parameters. |
| ModelSpec | What authors write wherever a model is configurable: a call override, an agent profile, a workflow default, or an engine default. |
| NodeId | Plan-node identity; engine-minted ULID. |
| OnEscalation | Escalation hook: decides for value-form calls. |
| OperationDisposition | - |
| Out | Inferred output type per form: the Standard Schema output type; the type-guard target of validate(); unknown for a bare JSON Schema. |
| Part | The canonical part union. provider-raw parts carry opaque provider blocks that must survive round trips (thinking blocks with signatures, reasoning items including encrypted_content). Retention is unconditional; dropping happens only in projection, never in retention. |
| PermissionGate | - |
| PermissionHook | - |
| PermissionPreset | - |
| PermissionRule | - |
| PermissionVerdict | - |
| RandPayload | Rand-entry payload. |
| RefEntryClassification | Fold classification of one ref-entry; NEVER persisted. |
| ReplayDisposition | - |
| ReplayMode | - |
| ResolutionAttempt | - |
| ResolutionBy | The journaled by-source of a resolution. |
| ResolutionOutcome | - |
| ResolutionPayload | Payload of resolution ref-entries (DEF-4). |
| RetryClass | - |
| RiskRuleValue | Declarative rule tables (no closures). 'undeclared' in risk position matches every tool WITHOUT declared risk: presets treat the undeclared state conservatively. Argv rules match through the real shell matcher; domain rules are ADVISORY outside the first-party fetch tool: they never change a verdict in M5, and matches surface in audit events. |
| Role | - |
| RulvarErrorCode | An alias for the registry type; both names are public. |
| RunFilter | - |
| RunMeta | Run-level metadata written by the ENGINE via putMeta as a separate record, so listRuns never parses payloads. The hashVersion range fields are advisory only; the journal is authoritative. |
| RunOutcome | - |
| RunStatus | Adds 'running' for in-flight inspection. |
| SandboxHostToWorker | Host-to-worker protocol messages (JSON only). |
| SandboxMethod | Methods a sandbox script may proxy to the host ctx. |
| SandboxWorkerToHost | Worker-to-host protocol messages (JSON only). |
| SchemaPair | Form 2 of SchemaSpec: an explicit JSON Schema plus a runtime type guard. |
| SchemaSpec | The L0 schema contract with exactly three accepted forms: a Standard Schema (Zod, ArkType, Valibot, ...), a { jsonSchema, validate } pair, or a bare JSON Schema literal. |
| SchemaValidationResult | Result of validating a value against a SchemaSpec. |
| ScopeSegment | A parsed scope-path segment. |
| Settled | The discriminated union over AgentStatus carrying the underlying AgentResult where one exists. |
| ShellVerdict | - |
| SpawnKey | Kernel contentHash of a spawn root entry. |
| SpawnOrigin | Every spawn origin routed through the single admission point. |
| Spend | - |
| Stage | - |
| StructuredOutputTier | - |
| SuspensionState | - |
| TaskClass | Task-class vocabulary aligned with the role quality floors vocabulary (https://docs.rulvar.com/guide/model-routing). Scopeless global statements are inexpressible: every claim binds a taskClass. |
| TaskSpec | Minimal TaskSpec stand-in: the full typed TaskSpec is owned by the PlanRunner surface and ships with M7; script modes carry proposals opaquely until then. |
| TerminationDeniedWriter | Injected appender for termination.denied entries (engine-owned I/O). |
| TerminationResource | The countable resource vocabulary. |
| ToolChoice | - |
| ToolEvents | Tool lifecycle (emitters arrive with the tool system, M3). |
| ToolExecutor | Where execute runs. A declared capability consumed by dispatch and policy; only 'inprocess' is enforced in v1, subprocess/container remain declared capability while the executor design stays an open question. |
| ToolRisk | Declarative risk metadata on the tool contract. Policy input, not identity: it does NOT enter toolsetHash. |
| ToolsOption | The per-spawn tools option value domain. |
| TriggerClass | - |
| TtlState | The TTL state a maintenance view renders per claim. |
| Usage | Usage under the Usage invariant: inputTokens is the FULL prompt size including cache reads and cache writes. Adapters MUST normalize provider-reported usage to satisfy this invariant, and the core verifies it at the adapter boundary. |
| WakeTrigger | The closed v1 trigger vocabulary. |
| WireError | JSON-serializable error projection stored in journal entries (JournalEntry.error) and sent across process boundaries (worker sandbox RPC, HTTP server). Raw Error objects never enter the journal. |
| WorkflowEvent | The envelope: seq is an independent per-run telemetry counter, strictly increasing in emission order and DISTINCT from JournalEntry.seq (never compare or join the two; entryRef fields carry journal seqs explicitly). ts is wall clock, telemetry only. replayed is true only on re-emitted journal-backed lifecycle events; stream deltas are never re-emitted. |
| WorkflowEventBody | - |
| WorkflowRegistry | The per-engine workflow registry (M5-T01): an explicit, first-class value; no module-level registry exists. Shells resolve by-name runs against it; ctx.workflow's string form (M6) and the queue worker (M8) resolve against it too. CompiledWorkflow values join the union when they first exist (M6). |
Variables
| Variable | Description |
|---|---|
| AWAIT_SCHEMA | await_any and await_all share one parameter shape. |
| BUDGET_ABORT_REASON | Reason marker distinguishing a budget-ceiling abort from host cancellation. |
| CANCEL_AGENT_SCHEMA | The cancel_agent parameter schema. |
| CHECKPOINT_FORMAT_V1 | Leading format byte of the v1 checkpoint blob. |
| CLAIM_STATEMENT_MAX_CHARS | The committed data model bound: statement <= 200 chars. |
| CLAIM_TTL_DAYS | The asymmetric TTL table: a false negative is costlier through lock-in, so weaknesses expire sooner than strengths. |
| COMPACTION_SUMMARY_PREFIX | Deterministic marker opening every compaction summary message. |
| CURRENT_HASH_VERSION | 1 = round 1; 2 = current. |
| DEFAULT_CHILD_BUDGET_FRACTION | - |
| DEFAULT_COMPACTION_THRESHOLD | Compaction threshold default, 0.8 of contextWindow. |
| DEFAULT_ESCALATION_LIMITS | - |
| DEFAULT_FLAT_RESERVE_USD | Last resort of the admission reserve formula. |
| DEFAULT_MAX_CHILDREN_PER_NODE | - |
| DEFAULT_MAX_DEPTH | - |
| DEFAULT_MAX_OSCILLATIONS_PER_KEY | - |
| DEFAULT_MAX_PINNED_WORKTREES | Appendix A: the shared pin cap (park/unpark and retainWorktree). |
| DEFAULT_MAX_REVISIONS_PER_RUN | Appendix A committed defaults for the countable resources. |
| DEFAULT_MAX_TOTAL_SPAWNS | - |
| DEFAULT_MAX_TURNS | - |
| DEFAULT_MODEL_RETRY_ATTEMPTS | Bounded semantic retries per tool call chain. |
| DEFAULT_NO_PROGRESS_TURNS | The committed no-progress detector N. |
| DEFAULT_PER_RUN_CONCURRENCY | FIFO semaphore; default per-run width is 12. |
| DEFAULT_RETRY_POLICY | Appendix A committed defaults (M4 entry gate, PR #26). |
| DEFAULT_STREAM_IDLE_TIMEOUT_MS | - |
| deriverV1 | The frozen v1 (round 1) profile: the projection removes effort from the requested modelSpec (the v1 predicate is effort-insensitive by construction); features outside the v1 domain are incomparable. |
| deriverV2 | The current (hashVersion 2) frozen profile. |
| EMIT_RESULT_TOOL | The synthesized forced-tool contract name. |
| EMPTY_SCHEMA_HASH | The schemaHash used when no structured-output schema is declared: the hash of the canonical true schema. |
| EMPTY_TOOLSET_HASH | The toolsetHash of an empty toolset: the hash of the canonical empty contract array. |
| ESCALATE_TOOL_NAME | - |
| ESCALATION_REPORT_SCHEMA | The full-report schema applied BEFORE append. |
| ESCALATION_REQUEST_SCHEMA | The escalate tool's exact request schema. costToDate and salvage MUST NOT appear here: additionalProperties false rejects model-authored values for them at argument validation. |
| FINISH_SCHEMA | finish; result validates against the declared output schema. |
| FINISH_TOOL_NAME | - |
| INBOX_PROPOSAL_TTL_DAYS | Inbox proposals expire after 14 days (reserved for M12 phase 3). |
| KB_ACTIVE_CLAIMS_CAP | Appendix A: KB active-claims cap, default 8 per (model, taskClass). |
| KB_CARD_RENDER_BUDGET_CHARS | The KB card render budget (characters). |
| LARGE_VALUE_WARN_BYTES | Large-value soft warn threshold (committed for M2). |
| LEGACY_LTID_PREFIX | Deterministic LTIDs canonized onto legacy journals. |
| LEGACY_SIGNATURE_INPUTS | The deterministic signature inputs assigned to legacy spawns (journals written before lineage existed) and to attempts whose producers did not record signature inputs: stable constants, never wall-clock, so replay canonizes identically on every engine. |
| LINEAGE_SIG_VERSION | approachSig/approachSigCoarse derivation version. |
| MASKED_SECRET | The replacement marker; deterministic and greppable. |
| MAX_DEPTH_CEILING | - |
| ORCHESTRATE_WORKFLOW_NAME | - |
| PARALLEL_AGENTS_SCHEMA | parallel_agents wraps the spawn_agent params. |
| ROLE_EFFORT_DEFAULTS | Role effort defaults: orchestrate and plan default to high; summarize and extract default to low. loop and finalize have NO role default: when the chain resolves nothing, the wire omits effort and identity records the spec with the effort member absent. |
| ROOT_ACCOUNT | The run-root account scope. |
| ROOT_SCOPE | The root sequential body of the run is the empty path. |
| RUN_PROFILES | The shipped presets (fast / standard / deep / ultra "and similar"). Data only; a review-time assertion checks the engine has zero behavioral branches keyed on these names. |
| SPAWN_AGENT_SCHEMA | The spawn_agent parameter schema (normative). |
| TOOL_NAME_PATTERN | First-party provider tool-name constraint intersection. |
| WAIT_FOR_EVENTS_SCHEMA | The wait_for_events parameter schema (normative). |
| WAIT_FOR_EVENTS_TOOL_NAME | - |
| WAKE_SUMMARY_RENDER_BUDGET_CHARS | The committed WakeDigest render budget (Appendix A: 400 chars per outputSummary row, the character measure; committed at M10 entry by adopting the implemented distillation cap unchanged, the value frozen into every cassette since M6). One value serves both stages: the deterministic distillation cap here and the digest render default in orchestrate (renderBudgetChars). |
Functions
| Function | Description |
|---|---|
| admissionReserveUsd | The admission reserve for a spawn: opts.estCost, else profile.estCost, else price(countTokens(input) + caps.maxOutputTokens), else the engine flat default. |
| agentErrorFromWire | Reads an AgentError back from its WireError projection. Throws a ConfigError when the wire code is not 'agent'. |
| agentErrorToWire | Projects an AgentError to its WireError form: code 'agent', with kind, retryAfterMs, and issues carried in data. Issue paths are flattened to JSON-safe segments. |
| agentScope | Orchestrator handle spawns nest under the orchestrator's own spawn entry: agent:<seq>. |
| applyClaimOps | Applies one op batch to a claims array, mechanically (M10-T01). The editorial validators (attestation, caps, statement bounds) layer on top in M10-T02; referential integrity is enforced here because a dangling supersede or archive would corrupt the append-only chain. |
| applyStructuredOutputTier | Applies the selected tier to an outgoing request. Native rides ChatRequest.schema; forced-tool synthesizes a single emit_result tool with toolChoice pinned to it; prompt injects the schema into the last user message. |
| approachSigCoarse | approachSigCoarse = sha256(JCS({ sigVersion, agentType, toolsetHash, schemaHash, isolation })). Feeds the stall detector and the oscillation guard, which keys ACROSS LTID boundaries. |
| approachSigOf | approachSig = sha256(JCS({ sigVersion, coarse, approachTag })); keys lessons. |
| archiveDeprecatedModelOps | Deprecation maintenance (deprecations archive claims, never delete them, so historical runs keep their audit trail): archive ops for every non-terminal claim of the deprecated models. The caller commits them under its own gate-free archive ops. |
| atCompactionThreshold | The summarize trigger: the compaction threshold on the context window (default 0.8). Pure predicate; the compaction pipeline that acts on it is M4-T03. |
| buildAbandonFold | Builds the AbandonFold in ONE pass at load, in append order, pinned for the entire resume (DEF-1 ordering rule 4). Coverage is the target seq itself plus, transitively, every entry under the target's child scope-prefix. Repeated abandons over an already-covered target fold to noop. |
| buildAdapterRegistry | Per-engine adapter registry: strictly per engine, no global mutable registry exists. A duplicate adapterId is a typed ConfigError. |
| buildCostReport | Folds the per-run attribution buckets into the normative CostReport. |
| buildDeriverRegistry | Builds the per-engine deriver registry: the shipped v1/v2 profiles plus EngineOptions.extraDerivers, the ONLY window extender. A malformed extra deriver is a ConfigError before any run effect. |
| buildOrchestratorTools | Builds the mode (c) toolset over the per-call runtime. profileCardText rides the spawn tools' descriptions so both modes speak one agent vocabulary (M6-T04). |
| buildTerminationInitValue | Builds the termination.init value payload. |
| buildToolContext | Builds the per-call ToolContext; one fresh span per tool call. |
| canonicalIsolationTag | The isolation string entering approachSigCoarse. |
| canonicalizeLadder | Canonicalizes a declared LadderSpec: validates the shape once (FR-119 judge declaration included) and resolves every rung's effort to an explicit value. chainEffort is the effort the resolution chain would contribute at the declaring layer; a rung that resolves no effort at all is a ConfigError (the canonical form has no absent-effort member by declaration). |
| canonicalizeSchema | Canonical schema derivation: local fragment-only $ref inlined (recursion is a ConfigError), remote and dynamic references forbidden, annotation keywords stripped (format retained), reference infrastructure ($defs, definitions, $anchor) removed once inlined. The result feeds JCS serialization and sha256. |
| canRideLoopTurn | True when the given structured-output tier can ride the last loop turn. native and prompt coexist with tool availability; forced-tool pins toolChoice to the synthesized emit_result contract and therefore cannot ride while the agent's tools must remain available. For an agent with no tools every tier rides (the M1 behavior, unchanged). |
| capIssues | The commit-time cap (Appendix A): active claims per (model, taskClass) after the batch applies. Supersede chains keep only the head active by construction (applyClaimOps flips the prior to 'superseded'), so a supersede never grows the count. |
| capsHashOf | Deterministic hash of a caps declaration (JCS + sha256). |
| checkFloors | Enforces the floors for one resolved invocation. taskClass is the profile-declared class; when absent (unclassified) only byRole floors apply. Throws a typed ConfigError on violation. |
| checkpointRefFor | Deterministic checkpoint blob ref for an agent dispatch (running seq). |
| childCoveragePrefix | The child scope-prefix an abandon over target covers transitively. Agent spawns nest under agent:<seq>; a child workflow's subtree runs under the wf:<name>:<ordinal> scope recorded in its dispatch payload (M6-T06). A child entry without the payload (foreign journals) degrades to the agent:<seq> convention, which covers nothing real and keeps the fold total. |
| claimExpired | True when the claim steers nothing at at (the read-path filter). |
| claimExpiry | The asymmetric TTL applied to an observedAt ISO date. |
| claimIssues | Issues of one claim record (empty = valid). |
| claimOpIssues | Issues of one op (empty = valid). GATE-DRIVEN (M11-T01): the gate on the op decides which claim rules apply, so the identity is enforced by shape alone. Referential integrity stays with apply. |
| classifyAgentError | task-class: schema-mismatch, terminal, non-retryable tool. transport, rate-limit, and budget are never memoized. |
| classifyAttemptOutcome | Classifies one settled root terminal into its attempt outcome class. |
| collectDeclaredLadders | The ladders a run declares: every advertised profile whose model spec is a ladder. The card is tier-relative to exactly these. |
| compactMessages | Applies a produced summary: everything after the first message (the spawn prompt) is replaced by ONE user-role summary message. Compaction fires at tool turn boundaries only, so the replaced span never splits a tool-call/tool-result pair. |
| compilePermissionChain | Merges the engine-wide config and the profile config into one chain. Layers concatenate engine-first; since rules only deny or ask, ordering within a layer cannot change the verdict. The profile's canUseTool wins over the engine's (a single slot by construction). A declared preset compiles INTO the same layers, after the host-authored rules, never as a fifth layer (M5-T05). |
| compilePermissionPreset | - |
| compileVerifiedLayer | The verified-layer compiler (M11-T06): start-tier recommendations per (ladder, taskClass) compiled EXCLUSIVELY from eval-measured claims. A strength on a rung below the default votes down (start cheaper); a weakness on the default rung or below votes up. The net sign shifts EXACTLY one rung, bounded to the ladder (the clamp: the price of any false belief is one rung); ties hold the default and compile nothing. Editorial claims NEVER compile. Floors and ModelCaps stay hard router constraints; budget is touched only through the existing admission path. A deterministic pure function: the M12 consumers read THIS, never the card text. |
| costReportFromJournal | The pure journal fold: byModel and totals from terminal entries, the same summation the kernel ledger uses (terminal usage exactly once, priced per servedBy, abandoned subtrees contribute zero). |
| countsAgainstLimit | countsAgainstLimit derivation (XF-06): true iff scope_bigger; scope_different and blocked_with_evidence are exempt and never debit the escalation counter. |
| createCanonicalIdMinter | Returns a per-engine minter of CanonicalId values. Monotonic within the factory instance; never a module-level singleton (no module state). |
| createCtx | Creates the per-run Ctx bound to internals. The current scope travels through AsyncLocalStorage so parallel branches and pipeline stages keep one ctx object while journaling under their own scope paths (I3: structure from call-and-return only). |
| createEngine | - |
| createSandboxBridge | - |
| currentOnlyKeyRing | - |
| decodeCheckpoint | Decodes a checkpoint blob. Returns undefined for an empty blob or an unknown format byte: a resume never trusts a checkpoint it cannot parse; the dangling dispatch reruns from the top instead (at-least-once is the documented floor). |
| defineWorkflow | - |
| deriveContentKey | key = sha256(JCS(IdentityInput)). |
| digestOf | Folds one settled child into its digest (spawn-ordinal ordering is the caller's). |
| dispositionHook | Adapts the predicate to the matcher's disposition hook: two-phase operations dispatch on their terminal, single-phase on themselves. |
| emptyDigestBlocks | The all-zero blocks of runs without the PlanRunner extension. |
| emptyToolset | The empty toolset (no tools declared anywhere). |
| encodeCheckpoint | Serializes a checkpoint to its blob: format byte then UTF-8 JSON. |
| escalateTool | The engine opt-in tool: registered through the same path as any tool under escalation opt-in of EITHER flavor (the worker's only authoring channel for a report), never available without opt-in, and dispatched through the same permission chain. The loop intercepts accepted calls; execute is unreachable by construction. |
| evaluatePermission | Evaluates the chain for one dispatch, or OFFLINE against a hypothetical call by tool name (the dry-run API: nothing executes; shells and tests read the verdict, the deciding layer, and the matched rule). Hooks run in deterministic registration order; { modifiedInput } substitutes the input and continues; the first decisive verdict wins. The returned input is what execute receives and what the approval identity hashes (post hook modification). Advisory domain-rule matches ride every verdict for the audit payload. |
| evaluateReuse | The four-outcome verdict evaluation on a SpawnKey match, computed once live at the fold head and embedded into the deciding entry; replay never re-evaluates. |
| executeWorkflow | Runs a workflow body against a fresh ctx: the engine core that engine.run wraps with RunHandle, events, and outcome assembly (M1-T11). Validates args against the declared schema, then executes single-pass. |
| exhaustionCodeOf | The typed error code surfaced after a denied debit. |
| extractCandidate | Extracts the structured-output candidate from a collected turn per tier. Returns undefined when the turn carries no candidate (for example the model answered prose without the forced tool call). |
| failoverTriggerOf | Maps a retry class to its failover trigger once retries exhaust. Overloaded (529) is transport-class for failover purposes; a non-retryable error never fails over. |
| fallbackTriggerOf | Classifies a terminal agent outcome for the degenerate fallback: schema-mismatch errors are 'schema-exhausted'; any other error is 'error'; limit terminals (the no-progress abort included) are 'limit'; cancelled, escalated, and skipped never trigger. |
| filterClaimsForRun | The admission filter: status active, unexpired at now, and the subject reachable through the run's declared ladders after the role-floor filter. |
| finalizeFires | The finalize firing rule: only if configured in routing, and only after tools stop, which presupposes a non-empty toolset. A no-tools agent's single loop turn is already its synthesis (as amended in M4-T01). The caller additionally gates on the loop having ended without an abort: a limit/error/cancelled/escalated loop never reaches synthesis. |
| foldTermination | The replay fold: rebuilds the account from termination.init and the debiting decision entries, asserting every embedded balance-after against the recomputation. A divergence raises the typed journal-integrity error at exactly the diverging entry; denials are re-issued from termination.denied with zero live calls. |
| formatRePrompt | The bounded re-prompt message sent back to the model on a validation miss. |
| formatScopePath | Serializes parsed segments back to the canonical path (round-trip). |
| hashWorkflowBody | Content hash of an in-process workflow body (run-to-definition binding). |
| hashWorkflowSource | Content hash of a compiled workflow source (run-to-definition binding). |
| identityJcs | The JCS form of an IdentityInput under the hashVersion 2 profile. |
| isEscalated | - |
| isSchemaPairSpec | Form-2 guard: an explicit { jsonSchema, validate } pair. |
| isStandardSchemaSpec | Form-1 guard: the value implements the Standard Schema interface. Some libraries expose callable schemas (ArkType types are functions), so both object- and function-typed values qualify. |
| isStrictCompatibleSchema | Strict-schema compatibility as both first-class providers define it: every object node declares additionalProperties: false and lists every property in required. Boolean schemas and non-object shapes are trivially compatible. |
| kMaxOf | kMax: the maximum declared ladder length across the registry snapshot. |
| knowledgeHash | Deterministic content hash of the claims array (JCS + sha256). |
| ladderLengthOf | Reads the declared ladder length of one agent profile. Ladders are declared through the profile's ModelSpec (model: { ladder }, or the loop-role routing entry). The reader is defensive so the snapshot is total over every registry shape (an undeclared ladder has length 1: the single implicit rung). |
| ladderRungChoice | The concrete ModelChoice of one rung attempt: each attempt is an ordinary agent scope whose CanonicalModelSpec is that rung's { kind: 'model' } form. |
| lexShellCommand | Lexes a command into segments per the matching algorithm above. Quotes and escapes are honored; nothing is expanded; $(, backticks, <(, >(, and << (outside single quotes) poison their segment. |
| liftRetainedParts | Lifts the adapter-shipped retention payload of one finished turn into provider-raw parts (the retention transport). Reads providerMetadata[<adapter id>].retainedParts and tags each block with the adapter's provider family. Returns [] when the adapter shipped nothing. |
| lineageWeightOf | C = E0 + kMax: the per-spawn weight of the variant function. |
| makeOrchestratorWorkflow | Builds the orchestrator workflow: ONE implementation behind both surfaces. The body wires the spawn tools over the per-call runtime, recovers spawn records from the journal on resume, and runs the orchestrator agent with the finish terminal tool. |
| maskSecrets | Masks credential-shaped substrings in one string. |
| maskSecretsDeep | Deep-masks every string value in a JSON tree; non-strings pass through. Returns the input identity when nothing matched, so the default-on policy costs no allocation on clean events. |
| maskSecretsJson | Convenience for hosts: masks a Json value (alias of the deep walk). |
| matchArgvPattern | Pattern grammar (5.1): literal words match one identical token; * matches exactly one token; ** matches zero or more remaining tokens and may appear only as the final word. A pattern matches only if it consumes the segment's ENTIRE argv. |
| matchShellCommand | The strictest-across-segments composition (5.3): deny if ANY segment denies; otherwise ask if ANY segment asks or fails to match an allow pattern; otherwise allow. |
| mcp | Imports MCP tools as a ToolSource. The client connects lazily on the first tools() call; tools/list is fetched with cursor pagination until exhaustion and cached per session; a listChanged notification invalidates the cache, affecting subsequently spawned agents only (a spawn's toolset snapshot is immutable by construction). |
| mergeUsageLimits | Limits merge per spawn: AgentOpts.limits over profile limits over engine defaults.limits. |
| modelEpochOf | Builds the optional modelEpoch block; empty inputs give undefined. |
| modelKnowledgeCard | The deterministic card render. Pure: same filtered claims and ladders give byte-identical text. The render budget is 4096 chars; over it, the OLDEST-observed notes withhold first behind an explicit marker. |
| modelSpecIdentity | The identity projection of a CanonicalModelSpec. For the plain-model kind the projection is { model, effort? } WITHOUT the kind discriminant, exactly as frozen by the hashVersion 2 profile; effort is omitted when unresolved. The ladder embedding lands with ladder execution (M7). |
| needsSeparateExtract | The completed extract-necessity rule: a separate final structured-output invocation fires only when a schema is set AND (routing directs extract to a different model OR the loop model's caps cannot serve the required tier OR finalize is routed, in which case the schema never rides a loop or synthesis turn). Otherwise the schema rides the last loop turn with no extra call (as amended in M4-T01). |
| nextFailover | The next target index past from that serves trigger, or undefined when the chain is exhausted. Index 0 is the primary; the chain never moves backwards (sticky failover). |
| nodeLinkKey | node.link identity: sha256 of {kind, spawnKey, donorScope, targetNodeId}; targetNodeId is deterministic on replay because NodeIds are assigned inside plan.revision. |
| normalizeApproachTag | Approach-tag normalization: NFC, lowercase, runs of non-alphanumerics collapse into a hyphen, truncate to 32 characters; an empty value canonicalizes to 'default'. Prompt prose never enters any signature: rephrasings collide by construction, not by heuristic. |
| normalizeEntry | Round-1 normalization: hashVersion is taken from hashVersion, else from the legacy v field, else 1. Stores are never rewritten; normalization happens at read. |
| normalizeFallbacks | Normalizes the author-facing ModelChoice.fallbacks list. |
| orchestrate | Top-level surface: creates a run. |
| parallelScope | Branch branch of parallel site site: par:<site>:<branch>. |
| parseModelRef | ModelRef is strictly 'adapterId:model', no query parameters. The wire model id may itself contain colons (for example ollama tags), so only the FIRST colon splits. |
| parseScopePath | Parses a scope path against the frozen grammar (M2-T04): |
| phiInitialOf | Phi0 = V0 + C * S0, finite and fixed in termination.init. |
| pipelineScope | Stage stage processing source item item: pipe:<stage>:<item>. |
| planNodeScope | PlanRunner node scopes: plan/<NodeId> (NodeIds are engine-minted ULIDs). |
| priceUsdOf | Dollars from normalized usage against one pricing row (the adapter normalized the usage; inputTokens is the full prompt). Cache writes price at the 5m premium rate; the 1h rate applies where a provider distinguishes it in usage, which the canonical Usage does not yet carry. |
| profileCard | Renders the registry into the shared agent vocabulary card. Sorted, deterministic, byte-stable; an empty registry renders explicitly so the planner never guesses at unregistered agentTypes. |
| profileRegistrySnapshotHash | The deterministic profile-registry snapshot hash frozen inside termination.init: profile names mapped to their declared ladder lengths, canonical JSON, sha256. |
| projectHistory | Projects the canonical history into the target provider's view: provider-raw parts of a DIFFERENT provider are omitted; everything else (text, images, tool calls, tool results, compaction content) passes through untouched. Messages whose parts all belong to another provider vanish entirely rather than ride as empty messages. |
| projectIdentity | The canonical identity object of an IdentityInput under the hashVersion 2 profile: what JCS serializes and sha256 hashes. The agent kind projects modelSpec through modelSpecIdentity; every other kind serializes its fields verbatim. Fields not listed for a kind are never included (the types make them unrepresentable). |
| projectToJsonSchema | Derives the JSON Schema of a SchemaSpec. Form 1 projects via the StandardJSONSchemaV1 input() converter, target draft 2020-12 with draft-07 fallback; a library without the projection is a typed ConfigError at definition time, never at first call. Transforming schemas therefore project their INPUT type. Forms 2 and 3 are taken verbatim. |
| proposalStatement | The typed statement template for a proposal-born claim (phase 3): assembled over the closed enum vocabulary ONLY, so tool-output text is unquotable into persistence, and model-free, because a claim statement renders into the knowledge card's notes layer, which never leaks model names to the orchestrator. |
| providerOf | The provider family of an adapter: provider when set, else id. |
| readTerminationInit | Reads a termination.init entry's payload; undefined when malformed. |
| registryKeyRing | KeyRing over the registry: the live call is projected DOWN into the profile of the stored entry; there is no upward canonization. |
| remeasureQueue | The re-measurement queue: expired eval-measured claims that are still ACTIVE. Just a status filter: the next sweep re-measures these subjects; nothing archives them (archiving would empty the queue and hide the decay). |
| replayDisposition | The single canonical predicate, dispatched on the entry's own hashVersion (compatibility lemma: on the v1 domain the tables coincide). Suspended entries are outside the table (the DEF-4 fold consumes them); the alias column (DEF-5) activates with node.link producers in M7: a skipped entry WITHOUT an incoming alias is always skipped. |
| resolveModelInvocation | Resolution runs on every model invocation, not once per agent: a layered merge of { model, effort, providerOptions, fallbacks } in the order call override > agent profile > workflow defaults > engine defaults, with the invocation role attached as a tag. After resolution the router reads ModelCaps and scrubs illegal parameters visibly: unsupported effort is removed from the wire but kept in identity; sampling params rejected by the model are removed from the adapter's namespace, never silently sent. |
| resolvePricing | Resolves the pricing for a model: the versioned table wins; the adapter-reported caps.pricing is the fallback; undefined means unpriced (the CostReport surfaces it, never a silent zero). |
| resolveToolset | Expands sources, validates every tool name and duplicate names across the whole toolset (ConfigError at spawn time), and computes the toolsetHash over contracts sorted by name. |
| retryClassOf | Classifies a WireError for the retry engine. Task-class failures are never retryable by construction: adapters mark them retryable: false and this returns undefined. The kind travels in WireError.data.kind; anything retryable without a specific kind is transport. |
| retryDelayMs | The delay before retry number retryIndex (0-based: the delay after the first failed attempt has index 0). A provider-supplied retryAfterMs REPLACES the computed delay (Appendix A). Jitter is equal-jitter: half the backoff is deterministic, half random, so a jittered delay never collapses to zero. |
| roleConfiguredInRouting | True when any resolution layer configures the given role in its routing map. This is the finalize TRIGGER: firing is decided by the presence of a routing entry at any layer; the model it fires ON still resolves through the full chain (a higher layer's all-roles model may override the routed choice). |
| roundOneDisposition | The round-1 interim disposition; replaced by replayDisposition (M2-T06). |
| runAgent | Runs one agent to a typed AgentResult. Never throws past policy: every failure mode becomes a typed status on the result. |
| runProfile | Looks up a shipped RunProfile by name; undefined for unknown names. |
| scanJournalCompatibility | The one compatibility scan: immediately after load, strictly BEFORE any live call, any append, and any admission reserve; repeated at lease acquire in queue mode. Side-effect free. |
| schemaHash | schemaHash = sha256(JCS(canonicalize(schema))). Accepts the derived JSON Schema (or a boolean schema); pass undefined for "no schema declared". |
| schemaHashOfSpec | Derives and hashes a SchemaSpec in one step (identity path for spawns). |
| selectStructuredOutputTier | Tier selection: the model's declared ceiling bounds the tier; the native tier additionally requires a strict-compatible canonical schema (relying on silent server-side fallback is forbidden), degrading to forced-tool. Prefill is not a tier. |
| shouldCompact | The threshold check (M4-T03 committed semantics): the context estimate is the last loop turn's inputTokens + outputTokens; the Usage invariant makes inputTokens the full prompt, and the turn's output joins the next prompt. |
| spawnDepthOf | Nesting depth of a child scope: its workflow, agent, and plan-node segments. |
| summarizeInstruction | The instruction message appended to the projected transcript for the summarize invocation. Deterministic wording; the response text becomes the summary message body. |
| summarizeOutput | The M6 outputSummary: a deterministic truncation of the child's output (or error message), identical live and on replay (distillation lives with the child, ordered by spawn ordinal; the LLM distillation upgrade is M7 territory). |
| terminationConfigDrift | Config-drift detection at resume: the journaled vector always wins; every differing field is reported for the termination:config-drift event. Dynamic budget top-up via restart is excluded by construction. |
| tierWithinCaps | True when tier is at or below the model's declared ceiling. |
| toApprovalDecision | Normalizes a resolution value into an ApprovalDecision. Anything that is not an explicit allow is a deny: an approval never fails open. |
| toJournalValue | Validates and snapshots a value for the journal: the returned value is a JSON round-trip clone, decoupled from later caller mutations, with undefined object members dropped. |
| tool | Defines a tool. Definition-time failures are typed ConfigErrors, never first-call surprises: an illegal name, a Standard Schema without the JSON Schema projection, a recursive local $ref, or a remote/dynamic reference all fail here. |
| toolContract | The identity projection: the contract tuple that enters toolsetHash. parameters is the canonicalized derived JSON Schema. |
| toolsetHash | toolsetHash = sha256 over the JCS-canonical JSON array of per-tool contract tuples (name, description, canonical parameters, version) sorted by name. Tool description IS part of the contract; schema annotations inside parameters are not. An absent version participates as absent. |
| ttlState | - |
| validateEditorialCommit | The commit-batch validation: op shapes and gates first (GATE-DRIVEN since M11-T01: the human gate carries editorial claims, the eval-committer gate carries eval-measured claims with metrics), the post-apply cap second. Throws one ConfigError carrying every issue, so a maintenance caller fixes the batch in one round trip. |
| validateEntryShape | Validates the shape the engine is about to append. Returns issues; empty means valid. Unknown kinds are rejected here (the engine never writes them); stores still pass them through on read. |
| validateEscalationLimits | Validates a lineage-limits config record. The pre-rename knob name is rejected with a migration hint (XF-10): silently honoring it would change semantics (per logical task, not per node). |
| validateEscalationReport | Validates the runtime-completed report BEFORE append; returns issues. |
| validateSchemaSpec | Runtime validation per form: form 1 via the Standard Schema's own validate, form 2 via the pair's type guard, form 3 via the vendored draft 2020-12 validator. The same machinery backs the structured-output tiers of the Agent Runtime. |
| validateTerminationLimits | Validates a raw limits record into the frozen vector. The pre-rename escalation knob is rejected with a migration hint (XF-10); counters must be non-negative integers; kMax at least 1. |
| workflowScope | ctx.workflow child scope: wf:<name>:<ordinal> (ordinal counts invocations of that name). |
| workflowSourceRef | TranscriptStore ref of the persisted CompiledWorkflow source blob. |
| wrapJournalStore | Wraps a journal store with the hook; lease capability is preserved. |
| wrapTranscriptStore | Wraps a transcript store with the hook. |