agentfootprint 13.0.0 → 14.0.0

package/dist/esm/core/agent/callerIdentity.d.ts

@@ -1,68 +1,15 @@
 /**
- * callerIdentity — WHO a resumed run is for, read back from the run it resumes.
- *
- * Seed (`stages/seed.ts · seedFrom`) writes the run's memory namespace on one of
- * three rungs: the caller's EXPLICIT identity; `{ conversationId: sessionId }`
- * for a session-bound run that named none (recorded as
- * `runIdentitySource: 'session'`); or the per-run default
- * `{ conversationId: '<runId>' }`. Only the first rung is a caller's identity —
- * the other two are derivations this library made, and `Agent.lastRunIdentity`
- * (what `checkpoint()`, `EventMeta.principal` and a tool's `ctx.identity` read)
- * must stay absent for them, so "absent" keeps meaning "nobody named one".
- *
- * `Agent.resume` does not re-seed: the resumed run keeps the paused run's
- * `runIdentity`, restored from the flowchart checkpoint. So the checkpoint is
- * the one carrier of "who the paused run was for" that survives a shared
- * instance, a pooled instance rebuilt after eviction, and a restart. This
- * module is the inverse of seed's rungs over that carrier.
- *
- * THE LAW: never drop an identity the caller named, never promote a derived
- * one. The session rung is recorded, so it is certain. The per-run default is
- * NOT recorded (writing a marker would change the committed keys of every
- * run that names nobody), and a flowchart checkpoint does not carry the paused
- * run's id — so it is recognised by the strongest evidence available, in order:
- *
- *  1. **The caller named exactly this identity on this instance** (`named`, the
- *     instance's last caller identity) → it is the caller's. This is what keeps
- *     a single-user app's `{ conversationId: 'run-1-1' }` across a bare resume.
- *  2. **This instance minted that conversation id as a run id** (`minted`) →
- *     derived, for certain.
- *  3. **The checkpoint's own receipt names that id as its run** (the paused run's
- *     `receipt.basis.runId`, present once it called a model) → derived, for
- *     certain.
- *  4. **LAST RESORT — the SHAPE `makeRunId` mints** (`isMintedRunId`), for a
- *     checkpoint from another instance with no receipt to match → read as
- *     derived. The one stated edge: a caller who names exactly
- *     `{ conversationId: 'run-<digits>-<digits>' }` and resumes it BARE loses
- *     it whenever step 1 cannot see it — on another instance, or on the same
- *     instance once anyone else has run in between — and no receipt matches.
- *     The fail-closed direction: a derived namespace is never published as a
- *     person. Pass `identity` on `resume` to keep it.
- *
- * A checkpoint names who it is for; it is not proof. A host that lets
- * checkpoints leave its trust boundary signs them or keeps them server-side —
- * see `Agent.resume`.
+ * Caller identity is read from the checkpoint's explicit origin facts.
+ * Names and identifier shapes never establish provenance or authentication.
+ * Migration: 14 requires the source marker written by its seed for a stored
+ * runIdentity. Older ambiguous pause state is refused rather than guessed.
  */
 import type { MemoryIdentity } from '../../memory/identity/types.js';
-/** What the resuming instance knows about identities and run ids. */
-export interface CallerIdentityEvidence {
-    /** The identity a caller last NAMED on this instance, if any. */
-    readonly named?: MemoryIdentity;
-    /** Run ids this instance minted (bounded). */
-    readonly minted?: ReadonlySet<string>;
-}
 /**
- * The identity the CALLER of the run whose state this is named, as a COPY, or
- * undefined when that run's identity was derived (session rung, per-run
- * default), is malformed, or the state carries none.
- *
- * @example
- * ```ts
- * // Agent.resume — a resuming call that names a DIFFERENT identity is refused:
- * const named = callerIdentityOf(checkpoint.sharedState, { named: last, minted });
- * ```
+ * A copy of the caller-named identity, only when the checkpoint explicitly
+ * records the caller rung. Derived namespaces are never promoted to a caller.
  */
-export declare function callerIdentityOf(state: unknown, evidence?: CallerIdentityEvidence): MemoryIdentity | undefined;
+export declare function callerIdentityOf(state: unknown): MemoryIdentity | undefined;
 /**
  * The identity the paused run's memory namespace and credentials are restored
  * from — `scope.runIdentity` as the checkpoint carries it, whatever its source —
@@ -73,10 +20,8 @@ export declare function callerIdentityOf(state: unknown, evidence?: CallerIdenti
  */
 export declare function restoredIdentityOf(state: unknown): MemoryIdentity | 'malformed' | undefined;
 /**
- * The session the paused run ran under, as its own state records it: the
- * `runSessionId` seed writes on every session-bound run, else — for a
- * checkpoint written before that key existed — the session rung's
- * `runIdentity.conversationId`. `undefined` when neither says.
+ * The session actually recorded by seed. No conversation-id or run-id shape
+ * fallback: a checkpoint cannot manufacture the host's transport context.
  */
 export declare function pausedSessionOf(state: unknown): string | undefined;
 /**

package/dist/esm/core/agent/callerIdentity.js

@@ -1,81 +1,18 @@
 /**
- * callerIdentity — WHO a resumed run is for, read back from the run it resumes.
- *
- * Seed (`stages/seed.ts · seedFrom`) writes the run's memory namespace on one of
- * three rungs: the caller's EXPLICIT identity; `{ conversationId: sessionId }`
- * for a session-bound run that named none (recorded as
- * `runIdentitySource: 'session'`); or the per-run default
- * `{ conversationId: '<runId>' }`. Only the first rung is a caller's identity —
- * the other two are derivations this library made, and `Agent.lastRunIdentity`
- * (what `checkpoint()`, `EventMeta.principal` and a tool's `ctx.identity` read)
- * must stay absent for them, so "absent" keeps meaning "nobody named one".
- *
- * `Agent.resume` does not re-seed: the resumed run keeps the paused run's
- * `runIdentity`, restored from the flowchart checkpoint. So the checkpoint is
- * the one carrier of "who the paused run was for" that survives a shared
- * instance, a pooled instance rebuilt after eviction, and a restart. This
- * module is the inverse of seed's rungs over that carrier.
- *
- * THE LAW: never drop an identity the caller named, never promote a derived
- * one. The session rung is recorded, so it is certain. The per-run default is
- * NOT recorded (writing a marker would change the committed keys of every
- * run that names nobody), and a flowchart checkpoint does not carry the paused
- * run's id — so it is recognised by the strongest evidence available, in order:
- *
- *  1. **The caller named exactly this identity on this instance** (`named`, the
- *     instance's last caller identity) → it is the caller's. This is what keeps
- *     a single-user app's `{ conversationId: 'run-1-1' }` across a bare resume.
- *  2. **This instance minted that conversation id as a run id** (`minted`) →
- *     derived, for certain.
- *  3. **The checkpoint's own receipt names that id as its run** (the paused run's
- *     `receipt.basis.runId`, present once it called a model) → derived, for
- *     certain.
- *  4. **LAST RESORT — the SHAPE `makeRunId` mints** (`isMintedRunId`), for a
- *     checkpoint from another instance with no receipt to match → read as
- *     derived. The one stated edge: a caller who names exactly
- *     `{ conversationId: 'run-<digits>-<digits>' }` and resumes it BARE loses
- *     it whenever step 1 cannot see it — on another instance, or on the same
- *     instance once anyone else has run in between — and no receipt matches.
- *     The fail-closed direction: a derived namespace is never published as a
- *     person. Pass `identity` on `resume` to keep it.
- *
- * A checkpoint names who it is for; it is not proof. A host that lets
- * checkpoints leave its trust boundary signs them or keeps them server-side —
- * see `Agent.resume`.
+ * Caller identity is read from the checkpoint's explicit origin facts.
+ * Names and identifier shapes never establish provenance or authentication.
+ * Migration: 14 requires the source marker written by its seed for a stored
+ * runIdentity. Older ambiguous pause state is refused rather than guessed.
  */
-import { isMintedRunId } from '../RunnerBase.js';
 /**
- * The identity the CALLER of the run whose state this is named, as a COPY, or
- * undefined when that run's identity was derived (session rung, per-run
- * default), is malformed, or the state carries none.
- *
- * @example
- * ```ts
- * // Agent.resume — a resuming call that names a DIFFERENT identity is refused:
- * const named = callerIdentityOf(checkpoint.sharedState, { named: last, minted });
- * ```
+ * A copy of the caller-named identity, only when the checkpoint explicitly
+ * records the caller rung. Derived namespaces are never promoted to a caller.
  */
-export function callerIdentityOf(state, evidence = {}) {
+export function callerIdentityOf(state) {
     if (state === null || typeof state !== 'object')
         return undefined;
     const seeded = state;
-    if (seeded.runIdentitySource !== undefined)
-        return undefined;
-    const identity = wellFormed(seeded.runIdentity);
-    if (identity === undefined)
-        return undefined;
-    if (evidence.named !== undefined && sameIdentity(evidence.named, identity))
-        return identity;
-    if (conversationOnly(identity)) {
-        const id = identity.conversationId;
-        if (evidence.minted?.has(id) === true)
-            return undefined;
-        if (readReceiptRunId(seeded) === id)
-            return undefined;
-        if (isMintedRunId(id))
-            return undefined;
-    }
-    return identity;
+    return seeded.runIdentitySource === 'caller' ? wellFormed(seeded.runIdentity) : undefined;
 }
 /**
  * The identity the paused run's memory namespace and credentials are restored
@@ -94,43 +31,29 @@ export function restoredIdentityOf(state) {
     const identity = wellFormed(seeded.runIdentity);
     if (identity === undefined)
         return 'malformed';
-    if (seeded.runIdentitySource !== undefined) {
-        const derived = seeded.runIdentitySource === 'session' || seeded.runIdentitySource === 'composition';
-        if (!derived || !conversationOnly(identity))
+    switch (seeded.runIdentitySource) {
+        case 'caller':
+            return identity;
+        case 'session':
+        case 'composition':
+        case 'run':
+            if (!conversationOnly(identity))
+                return 'malformed';
+            break;
+        default:
             return 'malformed';
     }
     return identity;
 }
 /**
- * The session the paused run ran under, as its own state records it: the
- * `runSessionId` seed writes on every session-bound run, else — for a
- * checkpoint written before that key existed — the session rung's
- * `runIdentity.conversationId`. `undefined` when neither says.
+ * The session actually recorded by seed. No conversation-id or run-id shape
+ * fallback: a checkpoint cannot manufacture the host's transport context.
  */
 export function pausedSessionOf(state) {
     if (state === null || typeof state !== 'object')
         return undefined;
     const seeded = state;
-    if (typeof seeded.runSessionId === 'string')
-        return seeded.runSessionId;
-    // `null` is this release's record of "a caller-named run with NO session".
-    if (seeded.runSessionId === null)
-        return undefined;
-    const identity = wellFormed(seeded.runIdentity);
-    if (identity === undefined)
-        return undefined;
-    if (seeded.runIdentitySource === 'session') {
-        return conversationOnly(identity) ? identity.conversationId : undefined;
-    }
-    // No marker at all on a caller-named identity: a checkpoint written BEFORE
-    // `runSessionId` existed (recheck NIT 3). Whether that run had a session is
-    // not recorded, and filing its resumed turn as sessionless would hand it to
-    // the next sessionless caller — so the session is recovered from the
-    // identity's `conversationId`, which is what `standingAgent` composed it from
-    // (`identityForRequest`). A run with no identity (the per-run default) had no
-    // session to recover.
-    const perRunDefault = conversationOnly(identity) && isMintedRunId(identity.conversationId);
-    return perRunDefault ? undefined : identity.conversationId;
+    return typeof seeded.runSessionId === 'string' ? seeded.runSessionId : undefined;
 }
 /**
  * Refuse, when a run BEGINS, an identity that is not one: not an object, a
@@ -188,12 +111,4 @@ function conversationOnly(identity) {
         identity.tenant === undefined &&
         identity.principal === undefined);
 }
-function readReceiptRunId(state) {
-    try {
-        return state.receipt?.basis?.runId;
-    }
-    catch {
-        return undefined;
-    }
-}
 //# sourceMappingURL=callerIdentity.js.map

package/dist/esm/core/agent/callerIdentity.js.map

@@ -1 +1 @@
-{"version":3,"file":"callerIdentity.js","sourceRoot":"","sources":["../../../../src/core/agent/callerIdentity.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"callerIdentity.js","sourceRoot":"","sources":["../../../../src/core/agent/callerIdentity.ts"],"names":[],"mappings":"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"}

package/dist/esm/core/agent/chartContract.d.ts

@@ -0,0 +1,327 @@
+/** One-job type contract owner; canonical exports remain with its facade. */
+import type { FlowChart, StructureRecorder, NativeMappingBinding } from 'footprintjs';
+import type { CachePolicy } from '../../cache/types.js';
+import type { MemoryDefinition } from '../../memory/define.types.js';
+import type { AnswerMountDeps, InputsMountDeps, ResultsMountDeps } from './honesty/mounts.js';
+import type { RouteBranch } from './stages/route.js';
+/**
+ * Stage handlers + slot subflows the chart composer needs. Mostly
+ * passed through verbatim from Agent.buildChart() — the chart shape
+ * is identical to what was inline before.
+ */
+export interface AgentChartDeps {
+    /** Memory READ/WRITE pipeline definitions (one per `.memory()`). */
+    readonly memories: readonly MemoryDefinition[];
+    /** Evidence bridge (#5): `causalEvidenceRecorder().collect`, threaded into
+     *  CAUSAL memories' write mounts so snapshots persist real evidence
+     *  (decisions/toolCalls/iterations/duration/tokens) instead of zeros.
+     *  Set by the Agent when any mounted memory is CAUSAL. */
+    readonly causalEvidenceSource?: (binding: NativeMappingBinding) => import('../../memory/causal/evidenceRecorder.js').RunEvidence;
+    /** Cache policy for the system-prompt slot, threaded into
+     *  CacheDecision's inputMapper so its decision rules can match. */
+    readonly systemPromptCachePolicy: CachePolicy;
+    /** Hard ReAct iteration cap, threaded into CacheDecision's
+     *  inputMapper for max-iteration policies. */
+    readonly maxIterations: number;
+    readonly seed: (scope: never) => void | Promise<void>;
+    readonly callLLM: (scope: never) => Promise<void>;
+    readonly routeDecider: (scope: never) => RouteBranch | Promise<RouteBranch>;
+    readonly toolCallsHandler: import('footprintjs').PausableHandler<never>;
+    /**
+     * The schema re-ask branch (7.26). Present ONLY when the agent was built
+     * with `.outputSchema(parser, { retries })` — and when present it is a
+     * THIRD branch of the Route decider carrying the same `{ loopTo }` the
+     * tool branch does, because a re-ask is one more ordinary turn.
+     *
+     * Conditional mount, for the reason every conditional mount here exists:
+     * an agent that did not opt in gets no branch, no stage, no scope key and
+     * no event — its chart and its commit log are the ones it always had.
+     */
+    readonly outputRetryStage?: (scope: never) => void;
+    readonly injectionEngineSubflow: FlowChart;
+    /** Relevance entry router (`entryByRelevance`) — a once-per-turn function stage
+     *  mounted before the InjectionEngine (off the ReAct loop). Present only when the
+     *  skill graph was built with a relevance scorer. */
+    readonly pickEntryStage?: (scope: never) => Promise<void>;
+    /**
+     * The turn-start routing CASCADE stage (SG-C) — subsumes PickEntry on
+     * graphs that run it (`classify` configured, or `continuity:
+     * 'conversation'`). Mounted in the SAME slot under the SAME id
+     * (`STAGE_IDS.PICK_ENTRY`) so recorded structures stay stable; never
+     * present together with `pickEntryStage` (Agent.buildChart picks exactly
+     * one). Absent → the chart is byte-identical to 9.16.
+     */
+    readonly routeTurnStage?: (scope: never) => Promise<void>;
+    /**
+     * The window-strategy stage (`.window()` / `.compaction()`). Present ONLY
+     * when the consumer configured a strategy — and when present it BECOMES the
+     * ReAct loop target, mounted immediately before the current one.
+     *
+     * It has to be the loop target rather than merely sit in the loop body:
+     * the loop is branch-sourced (`tool-calls → { loopTo }`), so anything ahead
+     * of the target runs once and is never seen again. Being the target also
+     * puts the window change BEFORE the injection engine and the slots, which
+     * is the point — the triggers, the three slots and the wire then all see
+     * the same window, and no component gets a different past than the model
+     * does.
+     *
+     * `strategyName` rides along so the chart itself says which policy is
+     * mounted; a reader of the graph should not have to guess.
+     */
+    readonly windowStage?: {
+        readonly strategyName: string;
+        readonly run: (scope: never) => Promise<void>;
+    };
+    /**
+     * The messages-slot DELIVERY stage (7.21). Present ONLY when the agent has
+     * something that could target the messages slot — a registered injection
+     * declaring `inject.messages`, or any `.memory()` whose recall might format
+     * as a non-system role. When absent the chart is the one it always was, so
+     * an agent with nothing to deliver is byte-identical to 7.20.
+     *
+     * Mounted between the InjectionEngine and the Context fan-out: after the
+     * engine has decided what is active, before anything reads the window. The
+     * placement is the design — a delivered message has to be part of the past
+     * that the slots project, the cache decision indexes, and the wire sends,
+     * or the recording and the request would disagree about the conversation.
+     */
+    readonly deliverStage?: (scope: never) => void;
+    readonly systemPromptSubflow: FlowChart;
+    readonly messagesSubflow: FlowChart;
+    readonly toolsSubflow: FlowChart;
+    /**
+     * Optional thinking-normalization sub-subflow (v2.14+). Mounted as a
+     * stage AFTER CallLLM, BEFORE Route, only when a `ThinkingHandler`
+     * resolved (declared by the provider or explicitly set
+     * via `.thinkingHandler()`). When undefined, the stage is NOT added —
+     * zero overhead for non-thinking agents (build-time conditional mount).
+     */
+    readonly thinkingSubflow?: FlowChart;
+    readonly updateSkillHistoryStage: (scope: never) => void;
+    /**
+     * Whether ≥1 Skill is registered. The `UpdateSkillHistory` stage (and
+     * therefore the cache's skill-churn rule) is mounted ONLY when true:
+     * with no skills the window would record "no skill" every iteration and
+     * `detectSkillChurn` could never fire, so the stage would be pure dead
+     * weight + a misleading box. Mirrors the `skills.length > 0` gate that
+     * auto-attaches `read_skill`, and the `thinkingSubflow` conditional mount.
+     */
+    readonly hasSkills: boolean;
+    /**
+     * Whether ≥1 registered skill declares `steps` (9.18.0). Gates the step
+     * pointer's mapper threading — engine in/out, the tools-slot arg, and (in
+     * the grouped chart) the `sf-llm-call` boundary — so an agent without
+     * stepped skills seeds and commits exactly the keys it always did. The
+     * threading lives HERE in the builders, not in the subflow (the SG-C
+     * blast-radius lesson): the alias discipline is
+     * `stepPointer` in (readonly input) → Evaluate writes `nextStepPointer`
+     * (the currentSkillId/nextSkillCursor precedent — the pointer changes
+     * every iteration, so the turn-constant `turnRoute` pattern would serve
+     * the tools slot a stale value) → mappers carry the alias back onto the
+     * parent's `stepPointer`.
+     */
+    readonly hasSteps?: boolean;
+    /**
+     * The mount kernel's plan (9.58.0) — present ONLY on an agent built with
+     * `.maps()`. Gates the `mapEngagement`/`nextMapEngagement` alias round
+     * trip through the injection-engine boundary (the stepPointer discipline
+     * verbatim). Absent → the keys are never threaded, so every other agent's
+     * mapper bytes are exactly what they were.
+     */
+    readonly engagementPlan?: import('../../maps/engagement/types.js').EngagementPlan;
+    /**
+     * The unfinished-steps nudge branch (9.18.0). Present ONLY on an agent
+     * with ≥1 stepped skill — and when present it is one more branch of the
+     * Route decider carrying the same `{ loopTo }` the tool branch does,
+     * because a nudge is one more ordinary turn (the SchemaRetry mechanism
+     * verbatim). Absent → no branch, no stage, no scope key, no event.
+     */
+    readonly stepNudgeStage?: (scope: never) => void;
+    /**
+     * The evidence recheck branch (9.35.0). Present ONLY on an agent built with
+     * `.namesAndNumbersFromEvidence({ posture: 'guard' | 'rails' })` — the
+     * `'assist'` posture records and never loops, so it mounts no branch. One
+     * more branch of the Route decider carrying the same `{ loopTo }` the tool
+     * branch does, because a correction is one more ordinary turn (the
+     * SchemaRetry mechanism verbatim). Absent → no branch, no stage, no event.
+     */
+    readonly evidenceRecheckStage?: (scope: never) => void;
+    readonly negativeRecheckStage?: (scope: never) => void;
+    /**
+     * The out-of-budget wrap-up branch (9.56.0). Present on any agent that can
+     * CALL a tool — a registered tool, or a `ToolProvider` that might list one —
+     * unless `wrapUpAtMaxIterations: false` turned it off. An agent with no tool
+     * surface can never run out of budget mid-action (a limit only cuts a turn
+     * short when tool calls were pending), so it mounts no branch and its chart
+     * is drawn exactly as it always was.
+     *
+     * One more branch of the Route decider carrying the same `{ loopTo }` the
+     * tool branch does, because a wrap-up is one more ordinary turn (the
+     * SchemaRetry mechanism verbatim). Absent → no branch, no stage, no scope
+     * key, no event.
+     */
+    readonly wrapUpStage?: (scope: never) => void;
+    /**
+     * The evidence gate is mounted (9.35.0), at ANY posture. In the GROUPED
+     * chart this gates bubbling `systemPromptInjections` out of `sf-llm-call`:
+     * the slot writes it INSIDE the subflow and the outer Route decider needs
+     * it to exempt values the app's own prompt (base prompt, skill body, a
+     * retrieved passage) supplied — without the mapper key the gate would flag
+     * the prompt's own identifiers in the default grouped shape (the
+     * `hasEscalation` blast-radius lesson, one field down). The flat chart
+     * shares one scope and needs no key; the flag is still threaded there so
+     * both builders read the same deps object.
+     */
+    readonly hasEvidenceGate?: boolean;
+    /**
+     * `.limitsTravelWithTheAnswer()` is configured on a PROSE answer (no output
+     * schema — a typed one sets `coverageLimitsAsData` instead). Swaps the
+     * final branch's first stage for the variant that folds the run's declared
+     * coverage into the answer before the turn payload is captured. Absent →
+     * the same stage function the chart has always mounted, byte for byte; the
+     * RECORDING half (events + `coverageDeclared`) is unconditional and does
+     * not depend on this flag.
+     */
+    readonly attachCoverageLimits?: boolean;
+    /**
+     * `.limitsTravelWithTheAnswer()` on an agent with an output schema — the
+     * answer is TYPED, so its limits travel as DATA and the block is never
+     * appended (JSON followed by prose is not JSON). Swaps the final branch's
+     * first stage for the variant that captures the model's answer unchanged
+     * and projects the Route decider's committed `answerCoverage` onto
+     * `turn_end`. The Agent sets this OR `attachCoverageLimits`, never both;
+     * absent → the stage the chart has always mounted.
+     */
+    readonly coverageLimitsAsData?: boolean;
+    /**
+     * `.scriptTravelsWithTheAnswer()` — the final stage carries this turn's
+     * recorded programs on `turn_end.scripts` and, on a prose answer (`typed`
+     * unset), appends them after the `---` separator (`stages/prepareFinal.ts` ·
+     * `prepareFinalFor`). Absent → the stage the chart has always mounted.
+     */
+    readonly scriptTravel?: import('./scripts/types.js').ResolvedScriptTravel & {
+        readonly typed?: true;
+    };
+    /** Opt-in terminal guard and one committed token; absent preserves the original final stage. */
+    readonly hasAnswerValidation?: boolean;
+    /** Output middleware owns delivery: publish only the final captured answer. */
+    readonly releaseOutputTokens?: true;
+    /** The evidence gate's `'rails'` posture: a refused answer is recorded flagged and ends the branch (`prepareFinalFor`). */
+    readonly evidenceRails?: true;
+    /**
+     * A tool's `displayName` (the app's words for a call), read through the
+     * agent's own tools — present only where a tool can declare one. The prose
+     * limits block names an item's declaring calls in those words
+     * (`stages/prepareFinal.ts` · `prepareFinalFor`). Absent → the stage the
+     * chart has always mounted.
+     */
+    readonly displayNameOfFor?: (scope: object) => (toolName: string) => string | undefined;
+    /**
+     * The time layer (`.time()`) is armed: under `attachCoverageLimits`, the
+     * final stage renders each `Period:` line in the run's clock zone
+     * (`stages/prepareFinal.ts` · `prepareFinalFor`). Absent → the stage the
+     * chart has always mounted.
+     */
+    readonly timeLayer?: true;
+    /**
+     * The time layer is armed (`.time()`). Gates ONE mount arg on the Tools
+     * branch's `inputMapper`: `timeWindows`, the turn's windows with the turn's
+     * clock (`time/windows.ts` · `readerWindowsOf`, off
+     * `parent.findingsLedger`) — the reader's (step T6b) and the app's control
+     * window (`time.window`) — value-conditional, so a turn with none crosses no
+     * key. The slot serves the reader's on each tool that declares a period and
+     * the control window on every request (`ToolsSlotConfig.timeWindows`, G14).
+     */
+    readonly timeWindows?: true;
+    /**
+     * The time layer is armed with the inputs layer (`.time()` over a tool that
+     * declares a period, step T8). Gates ONE mount arg on the Tools branch's
+     * `inputMapper`: `timeLimits`, the turn's result-check facts for the model
+     * (`semantics/coverage/timeLimitFacts.ts` · `timeLimitFactsOf`, audience `model`, off
+     * `parent.findingsLedger`) — value-conditional, so a turn whose reads match
+     * what was asked crosses no key. The slot renders and serves them in the
+     * one time line (`ToolsSlotConfig.timeLimits`); the renderer loads there,
+     * never on a plain agent's graph.
+     */
+    readonly timeLimits?: true;
+    /**
+     * An escalation brain is declared (9.19.0). In the GROUPED chart this
+     * gates threading `skillEscalated` across the `sf-llm-call` boundary —
+     * the flip is written by tool-calls on the OUTER scope and read by
+     * callLLM INSIDE the subflow, so without the mapper key the escalation
+     * would silently never serve a call in the default grouped shape (the
+     * SG-C blast-radius lesson: the threading lives in the builders). The
+     * flat chart shares one scope and needs no key; the flag is still
+     * accepted here so both builders take identical deps.
+     */
+    readonly hasEscalation?: boolean;
+    /** Findings is armed. The tools slot plants a stable optional schema;
+     * live call assembly serves the current offer and ledger in late DATA.
+     * This flag never makes the cache subflow suppress findings cache markers.
+     */
+    readonly hasFindingsLedger?: boolean;
+    /**
+     * The inputs layer is armed (honesty layer 2) — present ONLY when a tool
+     * the build can see declares `askOrAssume`, or the agent was built with
+     * `.inputsLayer()`. Mounts `sf-inputs` between the LLM call and Route
+     * (`honesty/mounts.ts` · `mountInputsLayer`, the ONE helper both builders
+     * call) and swaps the final branch's limits stage for the variant that also
+     * carries the assumed values, when `.limitsTravelWithTheAnswer()` is on.
+     * Absent — the default — and the chart is byte-identical.
+     */
+    readonly inputsLayer?: InputsMountDeps;
+    /**
+     * The results layer is armed (honesty layer 3, step 7b) — present ONLY when a
+     * tool the build can see declares a `ToolPeriod`, or the agent was built
+     * with `.resultsLayer()`. Mounts `sf-results` at the loop head, before the
+     * window strategy, and makes it the loop target (`honesty/mounts.ts` ·
+     * `mountResultsLayer`, the ONE helper both builders call). Absent — the
+     * default — and the chart is byte-identical.
+     */
+    readonly resultsLayer?: ResultsMountDeps;
+    /**
+     * The answer layer is armed (honesty layer 4, `.answerLayer()`). Starts the
+     * final branch with the layer's stage — the answer's standing, folded from
+     * the committed record, filed for PrepareFinal and announced once
+     * (`honesty/mounts.ts` · `startFinalBranch`, the ONE helper both builders
+     * call) — and swaps PrepareFinal's body for the variant that carries the
+     * standing on `turn_end` (and, under `standingLine`, appends its line to a
+     * prose answer). Absent — the default — and the branch is byte-identical.
+     */
+    readonly answerLayer?: AnswerMountDeps;
+    /**
+     * Tool choice by classifier is armed (`.toolChoice()`, 9.105.0). Gates
+     * THREE mount args on the Tools branch's `inputMapper` — `userMessage`
+     * (what the classifier reads), `priorToolChoices` (the parent's rows,
+     * under an alias because a mount input is frozen inside the subflow and
+     * the slot writes the fresh list under the base key) and `wrapUpAsked`
+     * (the wrap-up skip) — and ONE line on its `outputMapper`, carrying
+     * `toolChoices` back onto the parent key `callLLM` appends the outcome
+     * row to. In the grouped chart the same key crosses the `sf-llm-call`
+     * boundary both ways. Absent — the default — the mount maps exactly the
+     * keys it always did.
+     */
+    readonly hasToolChoice?: boolean;
+    /**
+     * The declared ontology is armed (`.ontology()`, 9.106.0). The flat chart
+     * needs nothing from it — `callLLM` reads the run constant `ontology` off
+     * the root scope; in the grouped chart `callLLM` lives INSIDE `sf-llm-call`
+     * and the constant is written by seed on the OUTER scope, so the boundary's
+     * `inputMapper` carries it across, under this gate and value-conditionally.
+     * Absent — the default — the boundary maps exactly the keys it always did.
+     */
+    readonly hasOntology?: boolean;
+    /**
+     * ReAct loop semantics. `'dynamic'` (default) re-runs the InjectionEngine +
+     * all 3 slots every iteration (loop → InjectionEngine). `'classic'`
+     * engineers context ONCE (InjectionEngine + system-prompt + tools up front)
+     * and loops only the Messages slot (loop → Messages). See AgentOptions.reactMode.
+     */
+    readonly reactMode?: 'classic' | 'dynamic';
+    /** Structure recorders threaded into both `flowChart()` calls (the
+     *  main chart and the PrepareFinal sub-chart). Each recorder
+     *  observes per-node build events (`onStageAdded` /
+     *  `onSubflowMounted` / etc.) for the Agent's chart. Undefined when
+     *  the consumer didn't attach any. */
+    readonly structureRecorders?: readonly StructureRecorder[];
+}

package/dist/esm/core/agent/chartContract.js

@@ -0,0 +1,3 @@
+/** One-job type contract owner; canonical exports remain with its facade. */
+export {};
+//# sourceMappingURL=chartContract.js.map

package/dist/esm/core/agent/chartContract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chartContract.js","sourceRoot":"","sources":["../../../../src/core/agent/chartContract.ts"],"names":[],"mappings":"AAAA,6EAA6E"}

package/dist/esm/core/agent/checkpointDomain.d.ts

@@ -0,0 +1,11 @@
+import type { FlowchartCheckpoint } from 'footprintjs';
+export declare function plainRecord(value: unknown): value is Record<string, unknown>;
+/** Read only an own data field; no accessor or inherited capture is consumed. */
+export declare function ownField(value: unknown, key: string): unknown;
+/**
+ * Select the exact CODE-owned tool mount on the documented native pause path.
+ * Root state is a separate view. Deeper tool-owned children are never searched.
+ * This reads its own fields only; the native resume decoder still owns the protocol.
+ * Reflection can execute Proxy traps; no isolation from caller-created Proxies is claimed.
+ */
+export declare function toolDomainStateOf(checkpoint: FlowchartCheckpoint, mountId: string): Record<string, unknown> | undefined;