agentfootprint 9.128.1 → 9.131.0

package/dist/esm/core/agent/stages/timeLayer.d.ts

@@ -0,0 +1,94 @@
+/**
+ * stages/timeLayer — the time layer's half of seed and ToolCalls, in the ONE
+ * module a plain agent never loads.
+ *
+ * Pattern: the stage bodies `.time()` adds — seed's clock stamp and reading
+ *          of the person's words, ToolCalls' dispatch moment (the `call` row,
+ *          the drift redraw, `ctx.time`) and a resume's `clock-on-resume`
+ *          row — moved out of the two stages verbatim, each taking the
+ *          stage's own scope and deps.
+ * Role:    core/ layer leaf of the time layer. seed (`stages/seed.ts`) and
+ *          ToolCalls (`stages/toolCalls.ts`) load it through `import()` only
+ *          when the agent armed `.time()` (`deps.timeClock`, `deps.timeReader`,
+ *          `deps.time`) — the optional-family law of docs-next's site budget
+ *          (`scripts/check-site-budget.mjs`; the `arguments/dispatch.ts`
+ *          precedent), so the resolver, the conversion forms and the drift
+ *          check are not on the graph `import { Agent }` loads.
+ * Emits:   N/A (rows go through the ledger's one writer).
+ *
+ * @example
+ * ```ts
+ * if (deps.time !== undefined) (await import('./timeLayer.js')).recordClockOnResume(scope, deps.time);
+ * ```
+ */
+import type { TypedScope } from 'footprintjs';
+import { type TimeContext } from '../../time/wire.js';
+import { type ZoneName } from '../../time/zone.js';
+import { type RuledToolLike } from '../arguments/declare.js';
+import type { AgentState } from '../types.js';
+import type { SeedStageDeps } from './seed.js';
+import type { ToolCallsHandlerDeps } from './toolCalls.js';
+/**
+ * The turn's clock stamp (the time layer) — filed LAST in seed, after the
+ * turn number is final (`anchorTurnNumber` may raise it), so the row names
+ * the turn every later row of this turn names. One row per run; the clock is
+ * a run constant from here on and is never written again this turn (a
+ * resume keeps it — `stages/toolCalls.ts` records a differing `time` as
+ * `clock-on-resume`). No accessor, or no draft → nothing is written.
+ */
+export declare function stampClock(scope: TypedScope<AgentState>, deps: SeedStageDeps): void;
+/**
+ * The person's words, read for time (the time layer's reader) — right after
+ * the turn's clock, which the reading resolves against. Reads ONLY this
+ * turn's entry, and only when a person wrote it: a message this library
+ * authored in a person's voice, a delivered injection and a composed run's
+ * message (another runner's output) are never read. A turn that already
+ * has its rows (a `resumeOnError` retry re-seeds the same turn) is read
+ * back, never re-read: a model-backed reader must not answer differently
+ * the second time. A sync reader keeps seed's shape; an async one makes it
+ * wait. A reader that throws fails the run.
+ */
+export declare function readTimeWords(scope: TypedScope<AgentState>, deps: SeedStageDeps): void | Promise<void>;
+/**
+ * The time layer at one dispatch: the `call` row (`core/time/rowsBuild.ts` ·
+ * `callRow`) — the wall clock read at the moment the library hands the call
+ * to the tool — and, for a call that sent a look-back, the clock at dispatch
+ * (§ 7.4, `core/time/drift.ts` · `driftAtDispatch`): past the tool's step the
+ * library's OWN look-back fill is re-sent as the asked range in the tool's
+ * absolute form (`args` comes back redrawn), and any other look-back runs as
+ * sent and is recorded shifted. Filed through the one writer; no event (the
+ * row is the record).
+ */
+export declare function timeAtDispatch(scope: TypedScope<AgentState>, call: {
+    readonly toolCallId: string;
+    readonly toolName: string;
+}, iteration: number, tool: RuledToolLike | undefined, args: Readonly<Record<string, unknown>>, appZone: ZoneName | undefined): {
+    readonly context: TimeContext | undefined;
+    readonly args: Readonly<Record<string, unknown>>;
+};
+/**
+ * `ctx.time` for one call (`core/time/wire.ts` · `TimeContext`, time design
+ * § 7.5) — present only when the inputs layer filed a `call-window` row for
+ * it this turn (its tool's period declares forms) and the turn has a clock:
+ * the range the call asks for, the person's zone, the frozen `now` and the
+ * dispatch moment just recorded. Read from the committed ledger, never
+ * recomputed.
+ */
+export declare function callTimeContext(scope: TypedScope<AgentState>, toolCallId: string, dispatchedAt: string): TimeContext | undefined;
+/**
+ * A resume's passed `time` against the paused turn's kept clock — one
+ * `clock-on-resume` row when they differ (`core/time/rowsBuild.ts` ·
+ * `clockOnResumeRow`), nothing when nothing was passed, nothing differs, or
+ * the paused turn has no clock (a checkpoint written by an agent without the
+ * layer: there is no frozen clock to keep, and a resume never starts one
+ * mid-turn).
+ *
+ * Called FIRST at both of this stage's entries, because a resume re-enters
+ * through either: the pausable `resume` door (a check-in, a middleware ask, a
+ * tool's own pause) or `execute` re-run from its top (the inputs layer's
+ * argument ask pauses through footprintjs's `interrupt()`). The passed value
+ * is TAKEN (`ToolCallsHandlerDeps.time` · `takePassedOnResume`), so the leg
+ * files it once whichever door it came through, and a fresh run — which
+ * passed none — files nothing.
+ */
+export declare function recordClockOnResume(scope: TypedScope<AgentState>, time: NonNullable<ToolCallsHandlerDeps['time']>): void;

package/dist/esm/core/agent/stages/timeLayer.js

@@ -0,0 +1,193 @@
+/**
+ * stages/timeLayer — the time layer's half of seed and ToolCalls, in the ONE
+ * module a plain agent never loads.
+ *
+ * Pattern: the stage bodies `.time()` adds — seed's clock stamp and reading
+ *          of the person's words, ToolCalls' dispatch moment (the `call` row,
+ *          the drift redraw, `ctx.time`) and a resume's `clock-on-resume`
+ *          row — moved out of the two stages verbatim, each taking the
+ *          stage's own scope and deps.
+ * Role:    core/ layer leaf of the time layer. seed (`stages/seed.ts`) and
+ *          ToolCalls (`stages/toolCalls.ts`) load it through `import()` only
+ *          when the agent armed `.time()` (`deps.timeClock`, `deps.timeReader`,
+ *          `deps.time`) — the optional-family law of docs-next's site budget
+ *          (`scripts/check-site-budget.mjs`; the `arguments/dispatch.ts`
+ *          precedent), so the resolver, the conversion forms and the drift
+ *          check are not on the graph `import { Agent }` loads.
+ * Emits:   N/A (rows go through the ledger's one writer).
+ *
+ * @example
+ * ```ts
+ * if (deps.time !== undefined) (await import('./timeLayer.js')).recordClockOnResume(scope, deps.time);
+ * ```
+ */
+import { isSaidByPerson } from '../../../lib/saidByPerson.js';
+import { completeClock } from '../../time/clock.js';
+import { granularityMsOf } from '../../time/convert.js';
+import { driftAtDispatch } from '../../time/drift.js';
+import { checkReading } from '../../time/reader.js';
+import { callWindowOfCall, clockOf, readingsOf } from '../../time/rows.js';
+import { callRow, clockOnResumeRow, clockRow, timeReadingRows } from '../../time/rowsBuild.js';
+import { timeContextOf } from '../../time/wire.js';
+import { tzdataVersion } from '../../time/zone.js';
+import { isRefused, periodFactsOf, periodFormsOf, rulesOf, } from '../arguments/declare.js';
+import { recordFindings } from '../findings/ledger.js';
+// ─── seed ────────────────────────────────────────────────────────────────
+/**
+ * The turn's clock stamp (the time layer) — filed LAST in seed, after the
+ * turn number is final (`anchorTurnNumber` may raise it), so the row names
+ * the turn every later row of this turn names. One row per run; the clock is
+ * a run constant from here on and is never written again this turn (a
+ * resume keeps it — `stages/toolCalls.ts` records a differing `time` as
+ * `clock-on-resume`). No accessor, or no draft → nothing is written.
+ */
+export function stampClock(scope, deps) {
+    const draft = deps.timeClock?.();
+    if (draft === undefined)
+        return;
+    const clock = completeClock(draft, scope.turnStartMs);
+    recordFindings(scope, [
+        clockRow(clock, { turn: scope.turnNumber, iteration: scope.iteration }, draft.window),
+    ]);
+}
+/**
+ * The person's words, read for time (the time layer's reader) — right after
+ * the turn's clock, which the reading resolves against. Reads ONLY this
+ * turn's entry, and only when a person wrote it: a message this library
+ * authored in a person's voice, a delivered injection and a composed run's
+ * message (another runner's output) are never read. A turn that already
+ * has its rows (a `resumeOnError` retry re-seeds the same turn) is read
+ * back, never re-read: a model-backed reader must not answer differently
+ * the second time. A sync reader keeps seed's shape; an async one makes it
+ * wait. A reader that throws fails the run.
+ */
+export function readTimeWords(scope, deps) {
+    const armed = deps.timeReader;
+    if (armed === undefined)
+        return;
+    if (scope.$getArgs().messageFrom === 'composed')
+        return;
+    const ledger = scope.findingsLedger;
+    const turn = scope.turnNumber;
+    if (readingsOf(ledger, turn).length > 0)
+        return;
+    const clock = clockOf(ledger);
+    const history = scope.history;
+    const entry = history[history.length - 1];
+    if (clock === undefined || entry === undefined || !isSaidByPerson(entry))
+        return;
+    const text = entry.content;
+    const { reader, policy } = armed;
+    const file = (reading) => {
+        const mentions = checkReading(text, reading, reader.id);
+        recordFindings(scope, timeReadingRows({
+            mentions,
+            clock,
+            policy,
+            reader,
+            tzdata: tzdataVersion(),
+            at: { turn, iteration: scope.iteration },
+        }));
+    };
+    const reading = reader.read(text, { locale: reader.locale });
+    if (reading !== null && typeof reading.then === 'function') {
+        return Promise.resolve(reading).then(file);
+    }
+    file(reading);
+}
+// ─── ToolCalls ───────────────────────────────────────────────────────────
+/**
+ * The time layer at one dispatch: the `call` row (`core/time/rowsBuild.ts` ·
+ * `callRow`) — the wall clock read at the moment the library hands the call
+ * to the tool — and, for a call that sent a look-back, the clock at dispatch
+ * (§ 7.4, `core/time/drift.ts` · `driftAtDispatch`): past the tool's step the
+ * library's OWN look-back fill is re-sent as the asked range in the tool's
+ * absolute form (`args` comes back redrawn), and any other look-back runs as
+ * sent and is recorded shifted. Filed through the one writer; no event (the
+ * row is the record).
+ */
+export function timeAtDispatch(scope, call, iteration, tool, args, appZone) {
+    const atMs = Date.now();
+    const dispatchedAt = new Date(atMs).toISOString();
+    const ledger = scope.findingsLedger;
+    const turn = scope.turnNumber;
+    const window = callWindowOfCall(ledger, call.toolCallId, turn);
+    const clock = clockOf(ledger);
+    const rules = window !== undefined && clock !== undefined ? rulesOf(tool) : undefined;
+    const drift = rules !== undefined && !isRefused(rules) && clock !== undefined
+        ? driftAtDispatch(window, periodFormsOf(rules.period), {
+            now: clock.now,
+            dispatchedAt,
+            granularityMs: granularityMsOf(periodFactsOf(rules.period)),
+            zone: clock.zone,
+            ...(appZone !== undefined && { appZone }),
+        })
+        : undefined;
+    const row = callRow(call, { turn, iteration }, atMs, drift === undefined
+        ? undefined
+        : drift.outcome === 'redrawn'
+            ? { byMs: drift.byMs, outcome: 'redrawn', form: drift.form }
+            : { byMs: drift.byMs, outcome: 'shifted' });
+    recordFindings(scope, [row]);
+    const redrawn = drift?.outcome === 'redrawn' ? redrawnArgs(args, tool, window?.form, drift.values) : args;
+    return { context: callTimeContext(scope, call.toolCallId, row.dispatchedAt), args: redrawn };
+}
+/** `args` with the look-back form's argument dropped and the absolute form's values written — a fresh object. */
+function redrawnArgs(args, tool, lookbackForm, values) {
+    const rules = rulesOf(tool);
+    const forms = rules === undefined || isRefused(rules) ? [] : periodFormsOf(rules.period);
+    const lookback = lookbackForm === undefined ? undefined : forms[lookbackForm];
+    const next = { ...args };
+    if (lookback !== undefined && lookback.kind === 'lookback')
+        delete next[lookback.argument];
+    return { ...next, ...values };
+}
+/**
+ * `ctx.time` for one call (`core/time/wire.ts` · `TimeContext`, time design
+ * § 7.5) — present only when the inputs layer filed a `call-window` row for
+ * it this turn (its tool's period declares forms) and the turn has a clock:
+ * the range the call asks for, the person's zone, the frozen `now` and the
+ * dispatch moment just recorded. Read from the committed ledger, never
+ * recomputed.
+ */
+export function callTimeContext(scope, toolCallId, dispatchedAt) {
+    const ledger = scope.findingsLedger;
+    const window = callWindowOfCall(ledger, toolCallId, scope.turnNumber);
+    if (window === undefined)
+        return undefined;
+    const clock = clockOf(ledger);
+    if (clock === undefined)
+        return undefined;
+    return structuredClone(timeContextOf(window, clock, dispatchedAt));
+}
+/**
+ * A resume's passed `time` against the paused turn's kept clock — one
+ * `clock-on-resume` row when they differ (`core/time/rowsBuild.ts` ·
+ * `clockOnResumeRow`), nothing when nothing was passed, nothing differs, or
+ * the paused turn has no clock (a checkpoint written by an agent without the
+ * layer: there is no frozen clock to keep, and a resume never starts one
+ * mid-turn).
+ *
+ * Called FIRST at both of this stage's entries, because a resume re-enters
+ * through either: the pausable `resume` door (a check-in, a middleware ask, a
+ * tool's own pause) or `execute` re-run from its top (the inputs layer's
+ * argument ask pauses through footprintjs's `interrupt()`). The passed value
+ * is TAKEN (`ToolCallsHandlerDeps.time` · `takePassedOnResume`), so the leg
+ * files it once whichever door it came through, and a fresh run — which
+ * passed none — files nothing.
+ */
+export function recordClockOnResume(scope, time) {
+    const passed = time.takePassedOnResume();
+    if (passed === undefined)
+        return;
+    const kept = clockOf(scope.findingsLedger);
+    if (kept === undefined)
+        return;
+    const row = clockOnResumeRow(passed, kept, {
+        turn: scope.turnNumber,
+        iteration: scope.iteration,
+    });
+    if (row !== undefined)
+        recordFindings(scope, [row]);
+}
+//# sourceMappingURL=timeLayer.js.map

package/dist/esm/core/agent/stages/timeLayer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeLayer.js","sourceRoot":"","sources":["../../../../../src/core/agent/stages/timeLayer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,OAAO,EAAE,eAAe,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,EAAE,YAAY,EAAoB,MAAM,sBAAsB,CAAC;AACtE,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAC;AAC3E,OAAO,EAAE,OAAO,EAAE,gBAAgB,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/F,OAAO,EAAE,aAAa,EAAoB,MAAM,oBAAoB,CAAC;AACrE,OAAO,EAAE,aAAa,EAAiB,MAAM,oBAAoB,CAAC;AAClE,OAAO,EACL,SAAS,EACT,aAAa,EACb,aAAa,EACb,OAAO,GAER,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAMvD,4EAA4E;AAE5E;;;;;;;GAOG;AACH,MAAM,UAAU,UAAU,CAAC,KAA6B,EAAE,IAAmB;IAC3E,MAAM,KAAK,GAAG,IAAI,CAAC,SAAS,EAAE,EAAE,CAAC;IACjC,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO;IAChC,MAAM,KAAK,GAAG,aAAa,CAAC,KAAK,EAAE,KAAK,CAAC,WAAqB,CAAC,CAAC;IAChE,cAAc,CAAC,KAAK,EAAE;QACpB,QAAQ,CACN,KAAK,EACL,EAAE,IAAI,EAAE,KAAK,CAAC,UAAoB,EAAE,SAAS,EAAE,KAAK,CAAC,SAAmB,EAAE,EAC1E,KAAK,CAAC,MAAM,CACb;KACF,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,aAAa,CAC3B,KAA6B,EAC7B,IAAmB;IAEnB,MAAM,KAAK,GAAG,IAAI,CAAC,UAAU,CAAC;IAC9B,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO;IAChC,IAAI,KAAK,CAAC,QAAQ,EAAc,CAAC,WAAW,KAAK,UAAU;QAAE,OAAO;IACpE,MAAM,MAAM,GAAG,KAAK,CAAC,cAA4C,CAAC;IAClE,MAAM,IAAI,GAAG,KAAK,CAAC,UAAoB,CAAC;IACxC,IAAI,UAAU,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO;IAChD,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9B,MAAM,OAAO,GAAG,KAAK,CAAC,OAAgC,CAAC;IACvD,MAAM,KAAK,GAAG,OAAO,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAC1C,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,cAAc,CAAC,KAAK,CAAC;QAAE,OAAO;IACjF,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC;IAC3B,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,KAAK,CAAC;IACjC,MAAM,IAAI,GAAG,CAAC,OAAoB,EAAQ,EAAE;QAC1C,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC;QACxD,cAAc,CACZ,KAAK,EACL,eAAe,CAAC;YACd,QAAQ;YACR,KAAK;YACL,MAAM;YACN,MAAM;YACN,MAAM,EAAE,aAAa,EAAE;YACvB,EAAE,EAAE,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,CAAC,SAAmB,EAAE;SACnD,CAAC,CACH,CAAC;IACJ,CAAC,CAAC;IACF,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAC7D,IAAI,OAAO,KAAK,IAAI,IAAI,OAAQ,OAA8B,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;QACnF,OAAO,OAAO,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC7C,CAAC;IACD,IAAI,CAAC,OAAsB,CAAC,CAAC;AAC/B,CAAC;AAED,4EAA4E;AAE5E;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAC5B,KAA6B,EAC7B,IAAgE,EAChE,SAAiB,EACjB,IAA+B,EAC/B,IAAuC,EACvC,OAA6B;IAE7B,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IACxB,MAAM,YAAY,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,CAAC;IAClD,MAAM,MAAM,GAAG,KAAK,CAAC,cAA4C,CAAC;IAClE,MAAM,IAAI,GAAG,KAAK,CAAC,UAAoB,CAAC;IACxC,MAAM,MAAM,GAAG,gBAAgB,CAAC,MAAM,EAAE,IAAI,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC;IAC/D,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9B,MAAM,KAAK,GAAG,MAAM,KAAK,SAAS,IAAI,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACtF,MAAM,KAAK,GACT,KAAK,KAAK,SAAS,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,KAAK,SAAS;QAC7D,CAAC,CAAC,eAAe,CAAC,MAAM,EAAE,aAAa,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE;YACnD,GAAG,EAAE,KAAK,CAAC,GAAG;YACd,YAAY;YACZ,aAAa,EAAE,eAAe,CAAC,aAAa,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;YAC3D,IAAI,EAAE,KAAK,CAAC,IAAI;YAChB,GAAG,CAAC,OAAO,KAAK,SAAS,IAAI,EAAE,OAAO,EAAE,CAAC;SAC1C,CAAC;QACJ,CAAC,CAAC,SAAS,CAAC;IAChB,MAAM,GAAG,GAAG,OAAO,CACjB,IAAI,EACJ,EAAE,IAAI,EAAE,SAAS,EAAE,EACnB,IAAI,EACJ,KAAK,KAAK,SAAS;QACjB,CAAC,CAAC,SAAS;QACX,CAAC,CAAC,KAAK,CAAC,OAAO,KAAK,SAAS;YAC7B,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE;YAC5D,CAAC,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,CAC7C,CAAC;IACF,cAAc,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7B,MAAM,OAAO,GACX,KAAK,EAAE,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAC5F,OAAO,EAAE,OAAO,EAAE,eAAe,CAAC,KAAK,EAAE,IAAI,CAAC,UAAU,EAAE,GAAG,CAAC,YAAY,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAC/F,CAAC;AAED,iHAAiH;AACjH,SAAS,WAAW,CAClB,IAAuC,EACvC,IAA+B,EAC/B,YAAgC,EAChC,MAAyC;IAEzC,MAAM,KAAK,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC5B,MAAM,KAAK,GAAG,KAAK,KAAK,SAAS,IAAI,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,aAAa,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;IACzF,MAAM,QAAQ,GAAG,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IAC9E,MAAM,IAAI,GAA4B,EAAE,GAAG,IAAI,EAAE,CAAC;IAClD,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,IAAI,KAAK,UAAU;QAAE,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAC3F,OAAO,EAAE,GAAG,IAAI,EAAE,GAAG,MAAM,EAAE,CAAC;AAChC,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAC7B,KAA6B,EAC7B,UAAkB,EAClB,YAAoB;IAEpB,MAAM,MAAM,GAAG,KAAK,CAAC,cAA4C,CAAC;IAClE,MAAM,MAAM,GAAG,gBAAgB,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,CAAC,UAAoB,CAAC,CAAC;IAChF,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC3C,MAAM,KAAK,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC9B,IAAI,KAAK,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC1C,OAAO,eAAe,CAAC,aAAa,CAAC,MAAM,EAAE,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC;AACrE,CAAC;AAED;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAA6B,EAC7B,IAA+C;IAE/C,MAAM,MAAM,GAAG,IAAI,CAAC,kBAAkB,EAAE,CAAC;IACzC,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO;IACjC,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,CAAC,cAA4C,CAAC,CAAC;IACzE,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO;IAC/B,MAAM,GAAG,GAAG,gBAAgB,CAAC,MAAM,EAAE,IAAI,EAAE;QACzC,IAAI,EAAE,KAAK,CAAC,UAAoB;QAChC,SAAS,EAAE,KAAK,CAAC,SAAmB;KACrC,CAAC,CAAC;IACH,IAAI,GAAG,KAAK,SAAS;QAAE,cAAc,CAAC,KAAK,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;AACtD,CAAC"}

package/dist/esm/core/agent/stages/timeLineage.d.ts

@@ -0,0 +1,31 @@
+/**
+ * stages/timeLineage — this turn's time spellings by lineage, as the evidence
+ * gate reads them (time design § 9.5, step T7), in a module a plain agent
+ * never loads.
+ *
+ * Pattern: Walker over the committed ledger — the turn's recorded windows
+ *          (`core/time/forms.ts` · `turnFormsWindowsOf`), the values the
+ *          library filled from a window (`./route.ts` · `isWindowFillRow`) and
+ *          the served time line.
+ * Role:    the Route decider loads it through `import()` under `.time()` only
+ *          (`./route.ts` · `loadTimeLineage`): `forms.ts` re-resolves a
+ *          confirmed reading (`resolve.ts`), so it stays off the graph
+ *          `import { Agent }` loads (the optional-family law,
+ *          `test/lib/trace-toolpack/browserGraph.test.ts`).
+ * Emits:   N/A.
+ *
+ * @example
+ * ```ts
+ * const { said, derived } = timeLineageOf(scope); // said → the exempt corpus; derived → a time-derived row
+ * ```
+ */
+import { type TimeLineage } from './route.js';
+/**
+ * This turn's time spellings, split by lineage (time design § 9.5, step T7):
+ * per recorded window (`core/time/forms.ts` · `turnFormsWindowsOf`), the
+ * spellings `timeFormsOf` files as the person's and as the library's; plus,
+ * as the library's, every value it filled from a window into a call
+ * (`isWindowFillRow`) and the served time line (`timeLine` — library text,
+ * never evidence, so an answer that echoes it is not the person's).
+ */
+export declare const timeLineageOf: TimeLineage;

package/dist/esm/core/agent/stages/timeLineage.js

@@ -0,0 +1,57 @@
+/**
+ * stages/timeLineage — this turn's time spellings by lineage, as the evidence
+ * gate reads them (time design § 9.5, step T7), in a module a plain agent
+ * never loads.
+ *
+ * Pattern: Walker over the committed ledger — the turn's recorded windows
+ *          (`core/time/forms.ts` · `turnFormsWindowsOf`), the values the
+ *          library filled from a window (`./route.ts` · `isWindowFillRow`) and
+ *          the served time line.
+ * Role:    the Route decider loads it through `import()` under `.time()` only
+ *          (`./route.ts` · `loadTimeLineage`): `forms.ts` re-resolves a
+ *          confirmed reading (`resolve.ts`), so it stays off the graph
+ *          `import { Agent }` loads (the optional-family law,
+ *          `test/lib/trace-toolpack/browserGraph.test.ts`).
+ * Emits:   N/A.
+ *
+ * @example
+ * ```ts
+ * const { said, derived } = timeLineageOf(scope); // said → the exempt corpus; derived → a time-derived row
+ * ```
+ */
+import { timeFormsOf, turnFormsWindowsOf } from '../../time/forms.js';
+import { HIDDEN_VALUE } from '../arguments/rows.js';
+import { isWindowFillRow } from './route.js';
+// FOLD · the one owner of this turn's time spellings by lineage, as the evidence gate reads them
+// consumers read this and never re-derive it: judgeEvidence (the exempt corpus's `timeSaid`, checkAnswer's `derived`)
+// detached: yes — fresh arrays per call, read from the committed ledger and the served time line.
+/**
+ * This turn's time spellings, split by lineage (time design § 9.5, step T7):
+ * per recorded window (`core/time/forms.ts` · `turnFormsWindowsOf`), the
+ * spellings `timeFormsOf` files as the person's and as the library's; plus,
+ * as the library's, every value it filled from a window into a call
+ * (`isWindowFillRow`) and the served time line (`timeLine` — library text,
+ * never evidence, so an answer that echoes it is not the person's).
+ */
+export const timeLineageOf = (scope) => {
+    const ledger = [...(scope.findingsLedger ?? [])];
+    const said = [];
+    const derived = [];
+    for (const window of turnFormsWindowsOf(ledger)) {
+        const forms = timeFormsOf({ window });
+        said.push(...forms.said);
+        derived.push(...forms.derived);
+    }
+    const turn = scope.turnNumber;
+    for (const row of ledger) {
+        if (row.kind !== 'argument' || row.turn !== turn || !isWindowFillRow(row, ledger))
+            continue;
+        if (row.value !== undefined && row.value !== HIDDEN_VALUE)
+            derived.push(row.value);
+    }
+    const line = scope.timeLine;
+    if (line !== undefined)
+        derived.push(line.text);
+    return { said, derived };
+};
+//# sourceMappingURL=timeLineage.js.map

package/dist/esm/core/agent/stages/timeLineage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"timeLineage.js","sourceRoot":"","sources":["../../../../../src/core/agent/stages/timeLineage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACtE,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,EAAE,eAAe,EAAoB,MAAM,YAAY,CAAC;AAE/D,iGAAiG;AACjG,sHAAsH;AACtH,kGAAkG;AAClG;;;;;;;GAOG;AACH,MAAM,CAAC,MAAM,aAAa,GAAgB,CAAC,KAAK,EAAE,EAAE;IAClD,MAAM,MAAM,GAAG,CAAC,GAAG,CAAE,KAAK,CAAC,cAA6C,IAAI,EAAE,CAAC,CAAC,CAAC;IACjF,MAAM,IAAI,GAAa,EAAE,CAAC;IAC1B,MAAM,OAAO,GAAa,EAAE,CAAC;IAC7B,KAAK,MAAM,MAAM,IAAI,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAC;QAChD,MAAM,KAAK,GAAG,WAAW,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC;QACtC,IAAI,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;QACzB,OAAO,CAAC,IAAI,CAAC,GAAG,KAAK,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC;IACD,MAAM,IAAI,GAAG,KAAK,CAAC,UAAoB,CAAC;IACxC,KAAK,MAAM,GAAG,IAAI,MAAM,EAAE,CAAC;QACzB,IAAI,GAAG,CAAC,IAAI,KAAK,UAAU,IAAI,GAAG,CAAC,IAAI,KAAK,IAAI,IAAI,CAAC,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC;YAAE,SAAS;QAC5F,IAAI,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,GAAG,CAAC,KAAK,KAAK,YAAY;YAAE,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;IACrF,CAAC;IACD,MAAM,IAAI,GAAG,KAAK,CAAC,QAAiD,CAAC;IACrE,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAChD,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC;AAC3B,CAAC,CAAC"}

package/dist/esm/core/agent/stages/toolCalls.d.ts

@@ -69,6 +69,10 @@ import type { MemoryIdentity } from '../../../memory/identity/types.js';
 import type { ToolSessionTier } from '../../toolSessions.js';
 import type { ToolMiddleware } from '../middleware/types.js';
 import type { Classifier } from '../../../classify/types.js';
+import type { ReadRunTime } from '../../time/clock.js';
+import type { ZoneName } from '../../time/zone.js';
+import type { TimePolicy } from '../../time/resolveRecord.js';
+import type { TimeAskMessages } from '../../time/ask.js';
 import type { ResolvedEvidenceGate } from '../evidence/types.js';
 import { type ToolArgValidationMode } from '../toolArgsValidation.js';
 import { type StepPlanFor } from '../../../lib/injection-engine/skillSteps.js';
@@ -515,6 +519,34 @@ export interface ToolCallsHandlerDeps {
      * @internal
      */
     readonly answeredAsk?: () => AnsweredAsk | undefined;
+    /**
+     * THE TIME LAYER (`.time()`) — present only then. Each dispatched call files
+     * one `call` row with `dispatchedAt` (the wall clock, just before the tool
+     * runs: a tool evaluates a look-back against its own clock at dispatch,
+     * which after a pause is later than the turn's `now`). `takePassedOnResume`
+     * hands over the `time` the current resume passed, as read, ONCE (a second
+     * call answers `undefined`) — the first ToolCalls pass of the resumed leg
+     * compares it with the turn's kept clock and files `clock-on-resume` when
+     * they differ; the kept clock is never replaced. A call whose tool's period
+     * declares forms is handed `ctx.time` (read off its `call-window` row), and
+     * the batch ask judges a period answer against the tool's facts at the
+     * turn's clock (`appZone`: the app's `.time({ zone })`).
+     *
+     * @internal
+     */
+    readonly time?: {
+        readonly takePassedOnResume: () => ReadRunTime | undefined;
+        readonly appZone?: ZoneName;
+        /**
+         * Present exactly under `.time({ reader })` (step T6b): the batch ask asks
+         * a period left out while the turn's one mention is open as THAT
+         * mention's window — the lazy word-driven ask (`./argumentAsk.ts` · `windowPlanOf`).
+         */
+        readonly reader?: {
+            readonly policy: TimePolicy;
+            readonly messages?: Partial<TimeAskMessages>;
+        };
+    };
     /**
      * Put one artifact fact on the record for the run it BELONGS to — the door
      * a `ctx.artifacts` fact takes when it lands after that run ended (a tool's

package/dist/esm/core/agent/stages/toolCalls.js

@@ -83,6 +83,7 @@ import { isResultMessage, knownResults } from '../findings/offer.js';
 import { basisRowFrom, foldLedger, recordFindings, standingRowsFrom, } from '../findings/ledger.js';
 import { contingentRowsOf, groundedArgumentValues, hasSetAsideStanding, } from '../findings/contingent.js';
 import { withUnsettledRows } from '../findings/unsettled.js';
+import { sourceClockRow, sourceClocksOf } from '../../time/rows.js';
 import { evidenceFromHistory, exemptFromRun, } from '../evidence/evidenceIndex.js';
 import { noteRepeatedCall, repeatedCallLedgers } from '../repeatedCall.js';
 import { formatToolArgIssues, validateToolArgs, } from '../toolArgsValidation.js';
@@ -719,6 +720,27 @@ function towersFor(scope, findings, gate) {
         standingOf,
     };
 }
+/**
+ * File the `source-clock` row for one call's dataset whose declared time axis
+ * names `zone` (step T8) — once per call and zone this turn, through the one
+ * writer; no event (the row is the record).
+ */
+function recordSourceClock(scope, call, zone) {
+    const ledger = scope.findingsLedger;
+    const turn = scope.turnNumber;
+    const filed = sourceClocksOf(ledger, turn).some((r) => r.toolCallId === call.toolCallId && r.zone === zone);
+    if (filed)
+        return;
+    recordFindings(scope, [
+        sourceClockRow(call, { turn, iteration: scope.iteration }, zone),
+    ]);
+}
+/** The run a capability binding was made in — `undefined` when there is no binding. */
+const madeInRun = (bindRun) => bindRun?.runContext?.runId;
+// The time layer's half of dispatch — the `call` row, the drift redraw,
+// `ctx.time` and the `clock-on-resume` row — lives in `./timeLayer.ts`,
+// loaded through `import()` only when `.time()` armed the agent (`deps.time`),
+// under the same optional-family law.
 export function buildToolCallsHandler(deps) {
     const { registryByName, externalToolProvider, providerToolCache, servedTools, toolClaimants, permissionChecker, } = deps;
     const toolArgValidation = deps.toolArgValidation ?? 'enforce';
@@ -1710,6 +1732,16 @@ export function buildToolCallsHandler(deps) {
                         ...(meta.timeAxis !== undefined && { timeAxis: meta.timeAxis }),
                         tool: toolName,
                     });
+                    // Under `.time()` (step T8): a dataset whose declared axis names a
+                    // zone is a wall-clock source — one `source-clock` row per call and
+                    // zone, for the limits block's `Clocks` lines. Only in the run the
+                    // binding was made in (a late mint's run has ended).
+                    const zone = meta.timeAxis?.zone;
+                    if (deps.time !== undefined &&
+                        zone !== undefined &&
+                        (madeInRun(bindRun) === undefined || madeInRun(bindRun) === deps.currentRun?.().runId)) {
+                        recordSourceClock(scope, { toolCallId, toolName }, zone);
+                    }
                     return;
                 }
                 case 'resolved':
@@ -2458,11 +2490,20 @@ export function buildToolCallsHandler(deps) {
             }
         }
         try {
+            // The time layer's dispatch moment — a resumed call is dispatched NOW,
+            // so its `dispatchedAt` is the resume's, not the pause's.
+            const dispatched = deps.time !== undefined
+                ? (await import('./timeLayer.js')).timeAtDispatch(scope, { toolCallId, toolName }, iteration, tool, args, deps.time.appZone)
+                : undefined;
+            const callTime = dispatched?.context;
+            if (dispatched !== undefined)
+                args = dispatched.args;
             // `let`, not `const`: the semantic projection below replaces the value
             // on the non-envelope path exactly as the batch loop does.
             let result = await tool.execute(args, {
                 toolCallId,
                 iteration,
+                ...(callTime !== undefined && { time: callTime }),
                 ...(env.signal && { signal: env.signal }),
                 credentials: reportingCredentials(credentials, scope, toolName),
                 hasCredentials,
@@ -2617,6 +2658,13 @@ export function buildToolCallsHandler(deps) {
             const durable = deps.awaitDurable?.();
             if (durable)
                 await durable;
+            // The time layer: a resume whose pause was the inputs layer's argument
+            // ask re-runs THIS function from its top — the kept clock is recorded
+            // against the resume's `time` here, first, exactly as the resume door
+            // does (TQ21). A fresh run passed no resume `time`: nothing is filed.
+            if (deps.time !== undefined) {
+                (await import('./timeLayer.js')).recordClockOnResume(scope, deps.time);
+            }
             // Materialize ONCE — `scope.llmLatestToolCalls` is a live TypedScope
             // deep-Proxy view; spreading yields the raw (plain, structured-clone-
             // safe) elements. This array is embedded into the assistant history
@@ -2660,6 +2708,12 @@ export function buildToolCallsHandler(deps) {
                     toolOf: (toolName) => resolveTool(toolName).tool,
                     runId: () => deps.currentRun?.().runId,
                     ...(deps.argumentAskContext !== undefined && { hostContext: deps.argumentAskContext }),
+                    ...(deps.time !== undefined && {
+                        time: {
+                            ...(deps.time.appZone !== undefined && { appZone: deps.time.appZone }),
+                            ...(deps.time.reader !== undefined && { reader: deps.time.reader }),
+                        },
+                    }),
                 });
                 resolutions = asked.resolutions;
                 if (asked.answered)
@@ -3469,6 +3523,15 @@ export function buildToolCallsHandler(deps) {
                                 throw new Error(resolved.refusal ?? unknownToolResult(tc.name, dispatchRoster(scope)));
                             }
                             noteOffWire(scope, resolved, { toolName: tc.name, toolCallId: tc.id, iteration });
+                            // The time layer's dispatch moment — just before the tool runs.
+                            // A look-back the clock drifted past is redrawn here (§ 7.4) — `callArgs`
+                            // carries what the tool ran with, so the note and the results layer read it.
+                            const dispatched = deps.time !== undefined
+                                ? (await import('./timeLayer.js')).timeAtDispatch(scope, { toolCallId: tc.id, toolName: tc.name }, iteration, tool, callArgs, deps.time.appZone)
+                                : undefined;
+                            const callTime = dispatched?.context;
+                            if (dispatched !== undefined)
+                                callArgs = dispatched.args;
                             // Set BEFORE the await: a tool that throws has still run, and a
                             // tool that does not exist has not. This flag is the entire
                             // precondition of the after-tool moment below.
@@ -3476,6 +3539,7 @@ export function buildToolCallsHandler(deps) {
                             result = await tool.execute(callArgs, {
                                 toolCallId: tc.id,
                                 iteration,
+                                ...(callTime !== undefined && { time: callTime }),
                                 ...(env.signal && { signal: env.signal }),
                                 credentials: reportingCredentials(credentials, scope, tc.name),
                                 hasCredentials,
@@ -4268,6 +4332,12 @@ export function buildToolCallsHandler(deps) {
             const durable = deps.awaitDurable?.();
             if (durable)
                 await durable;
+            // The time layer: the paused turn's clock is KEPT — its words were
+            // resolved against it. A resume that passed a different `time` is
+            // recorded here, first, and never applied (TQ21).
+            if (deps.time !== undefined) {
+                (await import('./timeLayer.js')).recordClockOnResume(scope, deps.time);
+            }
             // Consumer-supplied resume input becomes the paused tool's result.
             // The subflow's pre-pause scope is restored automatically by
             // footprintjs 4.17.0 via `checkpoint.subflowStates`, so