agentfootprint 10.3.0 → 10.3.1

package/dist/types/time/windows.d.ts

@@ -0,0 +1,201 @@
+/**
+ * time/windows — the turn's windows, read from the record (time design
+ * § 5.6): the window the person settled in the time ask (`answered`), a
+ * `model` reader's one reading waiting for confirmation
+ * (`derived-from-reading`) and the clock's `control` window; the quotes still
+ * waiting on the person; and what the served sentence names
+ * (`readerWindowsOf`).
+ *
+ * Pattern: Walker over recorded rows — never over words, never the resolver.
+ * Role:    the record half of `bind.ts`, split out BY FILE for the synchronous
+ *          doors: the Tools mount's `inputMapper` (`agent/buildAgentChart.ts` ·
+ *          `timeWindowsArg`) and the evidence gate's lineage read it before
+ *          any `import()` can run, and a bundler places a whole file on the
+ *          synchronous graph — so this file imports only the leaves and the
+ *          row readers, never `convert.ts` or `resolve.ts` (the optional-family
+ *          law, `test/trace-toolpack/browserGraph.test.ts`). `bind.ts`
+ *          re-exports every public name.
+ * Emits:   N/A (pure).
+ *
+ * @example
+ * ```ts
+ * readerWindowsOf(ledger);
+ * // { now: '2026-10-09T15:40:00Z', windows: [{ source: 'answered', quote: 'yesterday', … }] }
+ * ```
+ */
+import type { WindowToConvert } from './convert.js';
+import type { DurationText } from './duration.js';
+import type { InstantText } from './instant.js';
+import { type TimeRange } from './range.js';
+import type { TimeRefusal } from './periodForm.js';
+import { type ClockRow, type TimeAnswerRow, type TimeReadingRow } from './rows.js';
+import type { ZoneName } from './zone.js';
+/**
+ * Who a window is: the window the person settled in the time ask
+ * (`answered`), a `model` reader's unconfirmed reading (`derived-from-reading`),
+ * or a UI control. `said` — a `rule` reading filed as the person's words — is
+ * no longer filed (the owner's decision "Always confirm", time design TQ29);
+ * it stays in the union so a record an earlier version filed still reads.
+ */
+export type WindowSource = 'said' | 'derived-from-reading' | 'answered' | 'control';
+/** One window of the turn — a mention that resolved to one window, or the `control` window. */
+export interface TurnWindow {
+    readonly source: WindowSource;
+    /** The `time-reading` row's mention index — absent on the `control` window. */
+    readonly mention?: number;
+    /** The person's words it was read from — absent on the `control` window. */
+    readonly quote?: string;
+    readonly range: TimeRange;
+    /** The look-back it was said as, when it was one. */
+    readonly lookback?: DurationText;
+    /** The zone the person meant, else the clock's. */
+    readonly zone: ZoneName;
+    /** On an `answered` window: whether the person picked the offered reading (`confirmed`) or wrote their own (`edited`). */
+    readonly answer?: TimeAnswerRow['how'];
+}
+/** The turn's windows, and how many mentions the turn holds in all (resolved or not). */
+export interface TurnWindows {
+    readonly windows: readonly TurnWindow[];
+    /** Every mention with a quote, plus the `control` window — the "exactly one" count. */
+    readonly mentions: number;
+    /**
+     * Per mention still OPEN for the person (they have not answered it), the
+     * ranges of the readings left — what a tool's facts can already rule out
+     * (§ 6.3: every reading outside a tool's `direction` → nothing is asked, the
+     * call is refused). EMPTY for a mention the library holds no reading of yet
+     * — a zone to name first (`open` on `zone`), or words it could not read
+     * (`by: 'none'`): nothing to rule out, and the person is still asked
+     * (`isOpenForPerson`). Absent when no mention is open.
+     */
+    readonly open?: readonly (readonly TimeRange[])[];
+}
+/**
+ * The look-back the library OFFERED for a reading, when the person's answer is
+ * exactly it (`last 2 hours` confirmed as offered) — the window then stays a
+ * look-back from now. `undefined` for any other answer (an edit, a range).
+ */
+export declare function offeredLookback(row: TimeReadingRow | undefined, range: TimeRange): DurationText | undefined;
+/**
+ * What a turn window hands the conversion — its range and, when it was said
+ * (and answered) as a look-back, that look-back. THE one input every door
+ * that writes a window into a tool's arguments builds (the fill, the time
+ * ask's answer, the served line), so the value served to the model and the
+ * value the tool is handed are one spelling (time follow-ups, packet "gaps":
+ * the served line spelled `15:59:59Z` where the ask's fill handed `16:00:00Z`).
+ */
+export declare function windowToConvert(window: {
+    readonly range: TimeRange;
+    readonly lookback?: DurationText;
+}): WindowToConvert;
+/**
+ * Whether a mention the person has not answered still waits on THEM — the
+ * one owner of "a time the person wrote that the library holds no settled
+ * window for" (the lazy ask, the served line's pending half and the window
+ * plan all ask it): a reading still `open` (readings to confirm, a zone to
+ * name), and words the library holds NO reading of (`by: 'none'` — words the
+ * reader could not read, or no candidate). The person said a time either way,
+ * so a tool's default never stands in for it (time follow-ups, packet "gaps":
+ * an unreadable phrase to a tool whose rule assumed its period ran that
+ * default silently). A `model` reading's one window is not open: it fills as
+ * a reading. A refused mention (its quote was not in the text) is not the
+ * person's words.
+ */
+export declare function isOpenForPerson(row: TimeReadingRow): boolean;
+/**
+ * This turn's windows, read from the record: per mention, the window the
+ * person settled in the time ask (`answered`, its latest `time-answer` row),
+ * else a `model` reader's one window waiting for confirmation
+ * (`derived-from-reading`); and the clock's `control` window. A `rule`
+ * reading the person has not answered, and words the library could not read,
+ * are counted and are OPEN ({@link isOpenForPerson}).
+ */
+export declare function turnWindowsOf(readings: readonly TimeReadingRow[], clock: ClockRow | undefined, answers?: readonly TimeAnswerRow[]): TurnWindows;
+/** The windows of the person's words this turn, with the turn's clock — what the served sentence names. */
+export interface ReaderWindows {
+    readonly now: InstantText;
+    /** Each settled mention's window (`answered`, or a `model` reader's), in mention order — never the `control` window. */
+    readonly windows: readonly TurnWindow[];
+    /**
+     * The window the person set in the app's time control this turn (the run's
+     * `time.window`, recorded on the `clock` row, `source: 'control'`) — served
+     * on its own sentence, so an app never writes its own prompt text for it.
+     * Absent when the run set none.
+     */
+    readonly control?: TurnWindow;
+    /**
+     * The quote of each mention the library holds only as a PROPOSAL — a `rule`
+     * reading the person has not answered yet (its choice still `open`: a zone
+     * to name, readings to confirm) — in mention order. The served sentence
+     * names them as not confirmed, so a model that would write its own window
+     * leaves the period out and the time ask confirms it (step T6b bench,
+     * `bench/time/`). Absent when none is pending.
+     */
+    readonly pending?: readonly string[];
+    /**
+     * The quotes in `pending` the library holds NO reading of yet: the words
+     * name a zone it cannot resolve (an abbreviation outside the app's map), so
+     * the time ask asks for the zone and pre-fills nothing (the choice `open`
+     * on `zone`, no candidates). The served line says so instead of promising a
+     * form that shows a reading (T6b paid run: `field-pst`). Absent when none.
+     */
+    readonly pendingZones?: readonly string[];
+    /**
+     * The quotes in `pending` the library could not READ at all (`by: 'none'`:
+     * words outside the reader's set, or no candidate): the time ask asks the
+     * person which time they meant, with nothing pre-filled. The served line
+     * says so instead of promising a reading. Absent when none.
+     */
+    readonly pendingUnread?: readonly string[];
+    /**
+     * A mention is pending AND a call of this turn already ran on a window the
+     * model wrote into it (a `call-window` row `how: 'model'` — § 7.3: it runs
+     * as sent, unconfirmed). The served line then names that limit for the
+     * answer instead of the move that would have asked the person. Absent
+     * otherwise.
+     */
+    readonly ranUnconfirmed?: true;
+    /**
+     * The person's windows a tool REFUSED this turn, before dispatch (a
+     * `call-window` row `how: 'refused'`): the quote, the tool and the reason
+     * code — a window of the person's the call carried (`person.mention`), or
+     * the turn's one open reading, refused in every reading (a row with no
+     * range). The served line turns each into the conclusion an answer states,
+     * so a refused window is never asked for again as though a call could read
+     * it. A window the model wrote is not the person's and is not named. Absent
+     * when none was refused.
+     */
+    readonly refused?: readonly RefusedWindow[];
+    /**
+     * The turn's clock zone is UNKNOWN (`zoneSource: 'unknown'`, G15): the
+     * control window is spelled in UTC and the served line names the person's
+     * zone as not known. Absent otherwise.
+     */
+    readonly zoneUnknown?: true;
+}
+/** One window of the person's a tool refused before dispatch — what the served line concludes. */
+export interface RefusedWindow {
+    readonly quote: string;
+    readonly toolName: string;
+    readonly refused: TimeRefusal;
+    /** On a `dst-gap`: the argument whose wall time the zone skips. */
+    readonly argument?: string;
+}
+/**
+ * The quotes of this turn's mentions still waiting on the person
+ * ({@link isOpenForPerson}), not answered in the time ask: a reading to
+ * confirm, a zone to name, or words the library could not read (asked with
+ * nothing pre-filled). A `model` reading's one window is served as a reading;
+ * a refused mention is not the person's words.
+ */
+export declare function pendingQuotesOf(readings: readonly TimeReadingRow[], answers?: readonly TimeAnswerRow[]): readonly string[];
+/**
+ * The latest turn's windows of the person's words, read off the ledger (its
+ * last `clock` row and that turn's `time-reading` and `time-answer` rows) —
+ * `undefined` when the turn has no clock, no settled mention, none pending
+ * and no `control` window. A `rule` reading is named as a window only once
+ * the person answered it in the time ask; before that its quote is
+ * `pending`. The `control` window is no reading: it rides `control`, never
+ * `windows`.
+ */
+export declare function readerWindowsOf(ledger: readonly unknown[] | undefined): ReaderWindows | undefined;
+//# sourceMappingURL=windows.d.ts.map

package/dist/types/time/windows.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"windows.d.ts","sourceRoot":"","sources":["../../../src/time/windows.ts"],"names":[],"mappings":"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"}

package/dist/types/time/wire.d.ts

@@ -0,0 +1,71 @@
+/**
+ * time/wire — the time layer's JSON that crosses a transport (time
+ * design § 7.5): `ctx.time`, the window a call asks for, handed to the tool.
+ *
+ * Pattern: one versioned shape, the same object in process and on the wire.
+ *          In process it is `ToolExecutionContext.time`; over MCP it travels
+ *          in the `tools/call` request's `_meta.agentfootprint.time`
+ *          (`mcp/mcpClient.ts` sends it, `mcp/mcpServe.ts` hands it
+ *          to the served tool); a transport with no metadata slot sends
+ *          nothing, and the tool declares its period from its own arguments.
+ *          A tool's `period` declaration itself travels in the listing's
+ *          `_meta.agentfootprint.period`, judged by `tools/declare.ts`.
+ * Role:    L0 leaf (the time layer). Imports `instant.ts`, `range.ts` and
+ *          `zone.ts` only.
+ * Emits:   N/A.
+ *
+ * @example
+ * ```ts
+ * timeContextOf({ asked: { from: '2026-10-09T08:00:00-07:00', to: '2026-10-09T08:41:00-07:00' } },
+ *   { now: '2026-10-09T15:40:00Z', zone: 'America/Los_Angeles' }, '2026-10-09T15:40:02.114Z');
+ * // { version: 1, asked: { from: …, to: …, edge: 'exclusive' }, zone: 'America/Los_Angeles',
+ * //   now: '2026-10-09T15:40:00Z', dispatchedAt: '2026-10-09T15:40:02.114Z' }
+ * ```
+ */
+import { type InstantText } from './instant.js';
+import { type TimeRange } from './range.js';
+import { type ZoneName } from './zone.js';
+/** The shape's version — a reader refuses one it does not know. */
+export declare const TIME_CONTEXT_VERSION = 1;
+/** The `_meta.agentfootprint` key the call's time travels under over MCP. */
+export declare const TIME_CONTEXT_META_KEY = "time";
+/**
+ * What a tool that declares a period is handed about the call's time
+ * (`ctx.time`). `asked` is the half-open range the call asks for — the
+ * person's window when the library filled or bound it, the sent value read
+ * back otherwise — so a tool can declare the `period.queried` its read covered
+ * without parsing its own argument. Absent when no form read the call back.
+ */
+export interface TimeContext {
+    readonly version: typeof TIME_CONTEXT_VERSION;
+    readonly asked?: TimeRange & {
+        readonly edge: 'exclusive';
+    };
+    /** The person's zone for this run (the clock's). */
+    readonly zone: ZoneName;
+    /**
+     * The person's zone is NOT known (the clock's `zoneSource: 'unknown'`, G15):
+     * `zone` is only the UTC spelling of the instants, never the person's — a
+     * tool must not read a wall time in it as theirs. Absent when the zone is known.
+     */
+    readonly zoneUnknown?: true;
+    /** The turn's frozen clock (§ 4). */
+    readonly now: InstantText;
+    /** The wall clock when the library handed the call to the tool — the `call` row's. */
+    readonly dispatchedAt: InstantText;
+}
+/** The context for one call, from its `call-window` row's `asked`, the turn's clock and the dispatch moment. */
+export declare function timeContextOf(window: {
+    readonly asked?: TimeRange;
+} | undefined, clock: {
+    readonly now: InstantText;
+    readonly zone: ZoneName;
+    readonly zoneSource?: string;
+}, dispatchedAt: InstantText): TimeContext;
+/**
+ * A received context read — the version this runtime knows, every field well
+ * formed — or `undefined`. What a served tool is handed from the wire; never
+ * repaired.
+ */
+export declare function readTimeContext(value: unknown): TimeContext | undefined;
+//# sourceMappingURL=wire.d.ts.map

package/dist/types/time/wire.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wire.d.ts","sourceRoot":"","sources":["../../../src/time/wire.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAa,KAAK,WAAW,EAAE,MAAM,cAAc,CAAC;AAC3D,OAAO,EAAe,KAAK,SAAS,EAAE,MAAM,YAAY,CAAC;AACzD,OAAO,EAAc,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAC;AAEtD,mEAAmE;AACnE,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC,6EAA6E;AAC7E,eAAO,MAAM,qBAAqB,SAAS,CAAC;AAE5C;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,OAAO,EAAE,OAAO,oBAAoB,CAAC;IAC9C,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,GAAG;QAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;KAAE,CAAC;IAC5D,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB;;;;OAIG;IACH,QAAQ,CAAC,WAAW,CAAC,EAAE,IAAI,CAAC;IAC5B,qCAAqC;IACrC,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAC1B,sFAAsF;IACtF,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAC;CACpC;AAED,gHAAgH;AAChH,wBAAgB,aAAa,CAC3B,MAAM,EAAE;IAAE,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAE,GAAG,SAAS,EAClD,KAAK,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAA;CAAE,EAC3F,YAAY,EAAE,WAAW,GACxB,WAAW,CAYb;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,SAAS,CAkCvE"}

package/dist/types/time/zone.d.ts

@@ -0,0 +1,148 @@
+/**
+ * time/zone — IANA zone names and offset arithmetic, through `Intl`.
+ *
+ * Pattern: the platform's tz database behind two small questions — "what is
+ *          the offset of this zone at this instant?" and "which instant is
+ *          this wall time in this zone?" — with Temporal's four DST words for
+ *          the second. No dependency: `Intl.DateTimeFormat` carries the
+ *          database the runtime ships.
+ * Role:    L0 leaf (the time layer's one owner). Imports `instant.ts` only.
+ * Emits:   N/A.
+ *
+ * ## A zone is an IANA name, never an abbreviation
+ *
+ * `Intl` is more forgiving than this layer: it accepts `PST` (and reads it as
+ * `America/Los_Angeles`, whose October offset is -07:00, not PST's -08:00),
+ * `EST` (as `America/Panama`), and a bare offset such as `+05:30`. Each of
+ * those turns a person's words into a zone without saying so, so
+ * {@link isZoneName} refuses them: a name is accepted when it has an
+ * `Area/Location` shape (`America/Los_Angeles`, `Etc/GMT+5`) or is `UTC` /
+ * `GMT`, AND `Intl` knows it. An abbreviation reaches a zone only through a
+ * recorded map (a later step), never here.
+ *
+ * ## Cost — one `formatToParts` per (zone, instant), memoised
+ *
+ * Asking `Intl` is the whole cost of this module (a `formatToParts` is
+ * microseconds; everything else is arithmetic), and a resolution asks the
+ * same instants again: every candidate a DST probe validates is then spelled
+ * with its offset. So the formatter is built once per zone and the reading of
+ * each (zone, instant) is kept — the tz database cannot change inside a
+ * process — in a bounded memo cleared when full, like the formatter cache.
+ * `readWall` also skips the one probe it can prove redundant: when the offset
+ * a day before, at, and a day after the wall time agree, no change falls in
+ * that window, so the one candidate needs no check. What this buys is pinned
+ * as a COUNT by the performance case of test/time/resolve.test.ts, not a
+ * duration.
+ *
+ * ## DST — the four words
+ *
+ * | Wall time | `compatible` | `earlier` | `later` | `reject` |
+ * |-----------|--------------|-----------|---------|----------|
+ * | exists once | it | it | it | it |
+ * | exists twice (fall back, `01:30`) | the first | the first | the second | `undefined` |
+ * | never exists (spring forward, `02:30`) | shifted forward by the gap (`03:30`) | shifted back (`01:30`) | shifted forward | `undefined` |
+ *
+ * @example
+ * ```ts
+ * isZoneName('America/Los_Angeles'); // true
+ * isZoneName('PST');                 // false — an abbreviation
+ * offsetAt('America/Los_Angeles', Date.parse('2026-10-09T15:00:00Z')); // -420
+ * readWall({ year: 2026, month: 11, day: 1, hour: 1, minute: 30 }, 'America/Los_Angeles');
+ * // { kind: 'overlap', earlier: …08:30Z, later: …09:30Z }
+ * ```
+ */
+/** An IANA zone name, checked through `Intl`. Never an abbreviation, never a bare offset. */
+export type ZoneName = string;
+/** A wall-clock reading with no zone. `second` and `millisecond` default to 0. */
+export interface WallTime {
+    readonly year: number;
+    readonly month: number;
+    readonly day: number;
+    readonly hour: number;
+    readonly minute: number;
+    readonly second?: number;
+    readonly millisecond?: number;
+}
+/** Temporal's four words for a wall time a DST change doubles or skips. */
+export type Disambiguation = 'compatible' | 'earlier' | 'later' | 'reject';
+/** What a wall time names in a zone: one instant, two (fall back), or none (spring forward). */
+export type WallReading = {
+    readonly kind: 'unique';
+    readonly ms: number;
+} | {
+    readonly kind: 'overlap';
+    readonly earlier: number;
+    readonly later: number;
+} | {
+    readonly kind: 'gap';
+    readonly earlier: number;
+    readonly later: number;
+};
+/** Whether `value` is an IANA zone name this runtime's tz database knows — see the module header for what is refused. */
+export declare function isZoneName(value: unknown): value is ZoneName;
+/** The runtime's canonical spelling of a zone (`america/los_angeles` → `America/Los_Angeles`), or `undefined` when it is not a zone name. */
+export declare function canonicalZone(value: unknown): ZoneName | undefined;
+/** The wall time an instant shows in `zone` (milliseconds kept). Frozen: the reading is shared through the memo. */
+export declare function wallAt(zone: ZoneName, ms: number): WallTime;
+/**
+ * The offset of `zone` at the instant `ms`, in minutes east of UTC
+ * (`America/Los_Angeles` in October: -420). A historical local-mean-time
+ * offset can be a fraction of a minute.
+ */
+export declare function offsetAt(zone: ZoneName, ms: number): number;
+/** Whether a wall time's fields name a real calendar time (any zone aside). */
+export declare function isWallTime(value: unknown): value is WallTime;
+/**
+ * What `wall` names in `zone`: one instant, two (a fall-back overlap:
+ * `earlier`, `later`), or none (a spring-forward gap: `earlier` is the wall
+ * time read with the offset after the change, `later` with the offset before
+ * it — Temporal's two readings). Throws a `TypeError` on a wall time that is
+ * not a calendar time or a zone that is not a zone name.
+ */
+export declare function readWall(wall: WallTime, zone: ZoneName): WallReading;
+/**
+ * The instant `wall` names in `zone` under `disambiguation` (the module
+ * table), or `undefined` under `'reject'` when the wall time is doubled or
+ * skipped.
+ */
+export declare function wallToInstant(wall: WallTime, zone: ZoneName, disambiguation: Disambiguation): number | undefined;
+/**
+ * The tz database version this runtime's `Intl` carries — Node names it
+ * (`process.versions.tz`, e.g. `'2025b'`); any other runtime answers
+ * `'unknown'`. Recorded on every `time-reading` row: zone data changes
+ * between releases, so a reading is re-derivable only with it.
+ */
+export declare function tzdataVersion(): string;
+/**
+ * The ONE zone a place name names in this runtime's tz database, or
+ * `undefined` when it names none or more than one. `London` → `Europe/London`,
+ * `New York` → `America/New_York`; `India`, `Pacific`, `Eastern` → `undefined`
+ * (no zone ends in them — a region is not a place). Looked up two ways, both
+ * the tz database's own data: the zones whose last segment is the place, and
+ * `Area/Place` under each geographic area (which admits a renamed city's link,
+ * `Kyiv`). Every hit is compared by its canonical name, so a link and its
+ * target are one zone. Memoised; the runtime's database does not change.
+ *
+ * @example
+ * ```ts
+ * zoneOfPlace('London');   // 'Europe/London'
+ * zoneOfPlace('New York'); // 'America/New_York'
+ * zoneOfPlace('India');    // undefined — asked, never guessed
+ * ```
+ */
+export declare function zoneOfPlace(place: string): ZoneName | undefined;
+/**
+ * The IANA zone that is a fixed offset, for a whole-hour offset the tz
+ * database names (`Etc/GMT+8` is −08:00 — POSIX signs, inverted), else
+ * `undefined`. How a window read at a literal offset, or typed with one no
+ * other zone shows, names its zone without claiming a place's.
+ *
+ * @example
+ * ```ts
+ * fixedOffsetZone(-480); // 'Etc/GMT+8'
+ * fixedOffsetZone(0);    // 'UTC'
+ * fixedOffsetZone(330);  // undefined — no Etc zone for +05:30
+ * ```
+ */
+export declare function fixedOffsetZone(minutes: number): ZoneName | undefined;
+//# sourceMappingURL=zone.d.ts.map

package/dist/types/time/zone.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zone.d.ts","sourceRoot":"","sources":["../../../src/time/zone.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoDG;AAIH,6FAA6F;AAC7F,MAAM,MAAM,QAAQ,GAAG,MAAM,CAAC;AAE9B,kFAAkF;AAClF,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,2EAA2E;AAC3E,MAAM,MAAM,cAAc,GAAG,YAAY,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,CAAC;AAE3E,gGAAgG;AAChG,MAAM,MAAM,WAAW,GACnB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC9E;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAiC/E,yHAAyH;AACzH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAG5D;AAED,6IAA6I;AAC7I,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,QAAQ,GAAG,SAAS,CAGlE;AAED,oHAAoH;AACpH,wBAAgB,MAAM,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,GAAG,QAAQ,CAE3D;AAmED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,CAE3D;AAED,+EAA+E;AAC/E,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,QAAQ,CAe5D;AAED;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,QAAQ,GAAG,WAAW,CAyBpE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,QAAQ,EACd,IAAI,EAAE,QAAQ,EACd,cAAc,EAAE,cAAc,GAC7B,MAAM,GAAG,SAAS,CAOpB;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,IAAI,MAAM,CAKtC;AAyCD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAiB/D;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS,CAOrE"}

package/dist/types/time-travel/epochs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"epochs.d.ts","sourceRoot":"","sources":["../../../src/time-travel/epochs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0CG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAG9C,OAAO,EAAa,KAAK,SAAS,EAAE,KAAK,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAEhF;oCACoC;AACpC,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAC7C;;uCAEmC;IACnC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAChD,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IACjC,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnD;AAED;8BAC8B;AAC9B,MAAM,WAAW,aAAa;IAC5B;;;;;;;;;;;;OAYG;IACH,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,4EAA4E;IAC5E,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC;0DACsD;IACtD,QAAQ,CAAC,GAAG,EAAE,SAAS,YAAY,EAAE,CAAC;IACtC,2DAA2D;IAC3D,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB;;0CAEsC;IACtC,QAAQ,CAAC,MAAM,EAAE,SAAS,YAAY,EAAE,CAAC;IACzC;mFAC+E;IAC/E,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,kDAAkD;IAClD,QAAQ,CAAC,SAAS,EAAE,cAAc,CAAC;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,SAAS,CAAC;IAC7B;;gEAE4D;IAC5D,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;CAC7B;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,OAAO,GAAG,aAAa,GAAG,SAAS,CAOtE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,cAAc,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,GAAG,MAAM,EAAE,CAO9F;AAoCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,aAAa,EAAE,CASxE;AAgED;;;;;;;GAOG;AACH,wBAAgB,OAAO,CAAC,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS,CAEjF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,UAAU,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAGxE;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAG3E;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAG7E"}

package/dist/types/time-travel/index.d.ts

@@ -0,0 +1,17 @@
+/**
+ * time-travel/ — the agent's stops on a reader's cursor, and what the model
+ * was handed at each of them.
+ *
+ * Role: Fold. See README.md for what a milestone stop is, what a receipt and a
+ * served view are, and how one strategy and one epoch owner serve both chart
+ * shapes.
+ */
+export { milestoneOf, milestoneStops, milestoneStopsStrategy } from './milestoneStops.js';
+export { epochAt, epochLocations, llmCallMountKeys, readAfterCall, readAtCall, readRunConstant, recordingOf, type EpochLocation, type RecordingLike, } from './epochs.js';
+export { keyedFold, type FoldBasis, type FoldSourceLike, type KeyedFold } from './keyedFold.js';
+export { buildReceipt, messageDigestInput, toolDigestInput, receiptHash, transformHashOf, TRANSFORM_HASH_PREFIX, FORCED_OUTPUT_TOOL_KEY, RECEIPT_BOUNDARY, RECEIPT_HASH_CHARS, UNSERIALIZABLE, type Receipt, type ReceiptAttentionOmission, type ReceiptCacheMarker, type ReceiptMessage, type ReceiptParams, type ReceiptPiece, type ReceiptRequestOnlyMessage, type RequestMeasurement, type RequestJsonSize, type StoredReceipt, } from '../core/agent/receipt/receipt.js';
+export { sha256Hex } from '../lib/sha256.js';
+export { stableJson } from '../lib/stableJson.js';
+export { RECEIPT_KEY } from '../lib/conventions.js';
+export { receiptAt, servedAt, servedViews, SERVED_GAPS, UNGAPPED_FIELDS, type ServedGap, type ServedGapCause, type ServedGapKind, type ServedPiece, type ServedRequestOnly, type ServedView, } from './servedView.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/types/time-travel/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/time-travel/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,WAAW,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,qBAAqB,CAAC;AAC1F,OAAO,EACL,OAAO,EACP,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,UAAU,EACV,eAAe,EACf,WAAW,EACX,KAAK,aAAa,EAClB,KAAK,aAAa,GACnB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,SAAS,EAAE,KAAK,SAAS,EAAE,KAAK,cAAc,EAAE,KAAK,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAChG,OAAO,EACL,YAAY,EACZ,kBAAkB,EAClB,eAAe,EACf,WAAW,EACX,eAAe,EACf,qBAAqB,EACrB,sBAAsB,EACtB,gBAAgB,EAChB,kBAAkB,EAClB,cAAc,EACd,KAAK,OAAO,EACZ,KAAK,wBAAwB,EAC7B,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,yBAAyB,EAC9B,KAAK,kBAAkB,EACvB,KAAK,eAAe,EACpB,KAAK,aAAa,GACnB,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAC7C,OAAO,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC;AAClD,OAAO,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AACpD,OAAO,EACL,SAAS,EACT,QAAQ,EACR,WAAW,EACX,WAAW,EACX,eAAe,EACf,KAAK,SAAS,EACd,KAAK,cAAc,EACnB,KAAK,aAAa,EAClB,KAAK,WAAW,EAChB,KAAK,iBAAiB,EACtB,KAAK,UAAU,GAChB,MAAM,iBAAiB,CAAC"}

package/dist/types/time-travel/keyedFold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyedFold.d.ts","sourceRoot":"","sources":["../../../src/time-travel/keyedFold.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgDG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAE9C;;;;;;;;;GASG;AACH,MAAM,MAAM,SAAS,GAAG,aAAa,GAAG,UAAU,CAAC;AAEnD;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,SAAS,YAAY,EAAE,CAAC;IAC7C,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IACtC,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjD;AAmCD;;;GAGG;AACH,MAAM,WAAW,SAAS;IACxB,yDAAyD;IACzD,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC;IAC1B,sCAAsC;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;;;;;;OAUG;IACH,OAAO,CAAC,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC5C;AAqGD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,SAAS,CAAC,MAAM,EAAE,cAAc,GAAG,SAAS,GAAG,SAAS,CAmGvE"}

package/dist/types/time-travel/milestoneStops.d.ts

@@ -0,0 +1,150 @@
+/**
+ * milestoneStops — the agent's own scrub stops, derived from its commit log.
+ *
+ * Role:  Fold. It reads a finished run's commit log and answers one question —
+ *        "which positions in this run is a reader allowed to stop at?" It
+ *        executes nothing, records nothing, and stores nothing beside the log.
+ * Reads: a recorded commit log (plus the execution tree when the caller has
+ *        it), and `conventions.ts` · `milestoneFor` for the domain vocabulary.
+ * Emits: N/A.
+ *
+ * WHY THIS FILE EXISTS. footprintjs ships the reader's cursor (`timeTravel`)
+ * and one stop grammar — `commitStops`, one stop per executed stage — because
+ * that is the only grammar the substrate itself knows. It does NOT know what an
+ * LLM turn is. agentfootprint does: `milestoneFor` has classified a local stage
+ * id into an iteration / slot / llm-turn / tool-call / decision since 9.x, and
+ * until 9.87 every consumer that wanted a milestone slider mapped that
+ * classifier onto commits by hand. This is that mapping, once, on the strategy
+ * seam the port opened — so the agent SUPPLIES the stops for its own runs and
+ * every reader gets the same axis.
+ *
+ * WHAT IT IS (9.89.0). A FILTER over the port's own axis. footprintjs 9.18
+ * shipped `filterStops(stops, keep)` — the bookend guard, the re-partition and
+ * a `meta` slot on the stop — because two consumers had each re-derived all
+ * three by hand against 9.17, this file among them. The hand-rolled copies are
+ * gone: the one owner of the `[start, …stages, end]` contract is the library
+ * that returns it, and this strategy is one expression over it. The axis is
+ * byte-for-byte the 9.88.0 axis (`test/time-travel/milestone-stops-equivalence.test.ts` pins
+ * that against a verbatim copy of the 9.88.0 implementation); what is new is that the milestone now RIDES on the
+ * stop as `meta`, and that a start which absorbed pre-milestone stages says so
+ * with `prologue: true`.
+ *
+ * WHAT IT IS NOT. Not a second cursor. A strategy only says where the one
+ * cursor may rest; `timeTravel` still owns the position, the folds and the
+ * marks. And not a re-walk: a milestone that was never committed gets no stop,
+ * because a cursor that stops where no evidence exists is telling a story
+ * rather than reading one.
+ */
+import type { StageSnapshot } from 'footprintjs/advanced';
+import type { CommitBundle, Stop, TimeTravelStrategy } from 'foottrace';
+import { type Milestone } from '../lib/conventions.js';
+/**
+ * The milestone a stop stands for, or `null` when it stands for none (the
+ * `'start'` / `'end'` bookends).
+ *
+ * A stop that {@link milestoneStops} made carries its milestone as
+ * `stop.meta`, and that is what is read — the classification the strategy
+ * made when it put the stop on the axis, not a second run of the classifier.
+ * A stop from ANOTHER strategy — the port's own `commitStops`, or a consumer's
+ * filter that kept the stop without a milestone meta — has none, so the answer
+ * falls back to where it always came from: `milestoneFor` over the stop's
+ * `runtimeStageId`. Same classifier, same answer; a `meta` of some other
+ * vocabulary is not mistaken for ours.
+ *
+ * @example
+ * ```ts
+ * const stop = cursor.at()!;
+ * milestoneOf(stop)?.kind;   // 'llm-turn'
+ * ```
+ */
+export declare function milestoneOf(stop: Stop<unknown>): Milestone | null;
+/**
+ * Derive one stop per committed MILESTONE from a recorded commit log.
+ *
+ * The rule, in one sentence: take footprintjs's own per-stage axis, keep the
+ * stages `milestoneFor` classifies, and give the survivors the log back.
+ *
+ * **Composed, never re-derived.** The hard parts of the per-stage axis are
+ * already solved upstream and are not repeated here: one stop per
+ * `runtimeStageId` at its FIRST commit (a subflow mount commits twice, a
+ * parallel fork child commits twice and siblings interleave — every repeat is
+ * an empty bundle), the authoritative mount set read off the execution tree,
+ * the `'start'` / `'end'` bookends, and the id-less leading commit that carries
+ * a subflow's `inputMapper` seed. And since 9.89.0 the COMPOSITION itself is
+ * the port's too: `filterStops` checks the `[start, …stages, end]` shape,
+ * keeps what `keep` keeps, and re-partitions the log. A second implementation
+ * of any of that would be a second chance to disagree with the library about
+ * what a stage is.
+ *
+ * **The survivors re-partition the log.** A stage that classifies `null` is not
+ * a stop, but its commits still happened, so they are folded into the stop that
+ * PRECEDES them: every kept stop's `lastCommitIdx` is extended to just before
+ * the next kept stop begins. Nothing is orphaned, and `stateAt(stop)` remains
+ * exactly "the state that existed when the next milestone's stage started".
+ * Commits before the FIRST milestone belong to `'start'` for the same reason —
+ * so on a drilled cursor `'start'` reads as "what this subflow began with,
+ * after its plumbing ran".
+ *
+ * **What that costs `'start'`, and the flag that says so.** On footprintjs's
+ * own axis `'start'` is the fold base: the state before ANY stage ran. Here it
+ * absorbs every stage that ran before the first milestone, so `stateAt(start)`
+ * is the state the first milestone READ, not the run's raw base — a real agent
+ * seeds a couple of dozen keys in `seed` before anything a reader would scrub
+ * to. That is the right answer for this axis (the stops must still partition
+ * the log), and since 9.18 the port marks it: the returned start carries
+ * `prologue: true` whenever it absorbed a stage, so a renderer that means
+ * "before anything ran" checks `kind === 'start' && !prologue` instead of
+ * assuming it from the kind.
+ *
+ * **The milestone rides on the stop.** Every kept stop carries its
+ * classification as `meta` — `Stop<Milestone>` — so a reader asks
+ * `stop.meta?.kind` (or {@link milestoneOf}, which reads the same slot) rather
+ * than re-running the classifier over the id. The bookends carry none.
+ *
+ * **A log with no milestones in it at all.** A non-empty log the classifier
+ * recognises nothing in — a non-agent chart handed this strategy — yields the
+ * two bookends and nothing between them: `'start'` folds the whole log,
+ * `'end'` folds the whole log, and `jumpTo` any stage id refuses with
+ * `reason: 'miss'`. An axis with nowhere meaningful to stand, which is the
+ * truthful shape for a run that has no milestones — not an error, and not the
+ * empty `[]` that says the log itself was empty.
+ *
+ * **It does not know which log it was given.** The classifier reads the LOCAL
+ * segment of a stage id, so `sf-llm-call#3` on a run's outer log and
+ * `sf-llm-call/call-llm#7` on that mount's drilled inner history are both
+ * classified without the strategy being told which one it is holding. That is
+ * what lets one strategy serve `reactMode: 'dynamic'` (the `call-llm` bundle is
+ * in the outer log → an llm-turn stop on the outer cursor) and
+ * `'dynamic-grouped'` (the outer log holds `sf-llm-call` mounts → iteration
+ * stops; `drill()` gives the inner cursor, where the same strategy finds the
+ * llm-turn, tool-call and decision stops).
+ *
+ * @param commitLog     the run's `commitLog`, or a subflow's own `history`.
+ * @param executionTree the run's `executionTree`, when the caller has it — it
+ *   is what makes a mount stop say `kind: 'mount'` rather than being guessed
+ *   from bundle shape.
+ *
+ * @example
+ * ```ts
+ * import { timeTravel } from 'foottrace';
+ * import { milestoneStopsStrategy } from 'agentfootprint';
+ *
+ * const cursor = timeTravel(agent.getSnapshot()!, { strategy: milestoneStopsStrategy });
+ * cursor.stops.map((s) => [s.label, s.meta?.kind]);
+ * // measured on a two-turn `dynamic` run — 42 commits, 15 stops:
+ * // [['Run start', undefined], ['Iteration', 'iteration'],
+ * //  ['System prompt', 'slot'], ['Messages', 'slot'], ['Tools', 'slot'],
+ * //  ['LLM turn', 'llm-turn'], ['Route', 'decision'], ['Tool call', 'tool-call'],
+ * //  … the second turn …, ['Run end', undefined]]
+ * cursor.stops[0].prologue; // true — `seed` and the plumbing ran before the first Iteration
+ * ```
+ */
+export declare function milestoneStops(commitLog: readonly CommitBundle[], executionTree?: StageSnapshot): Stop<Milestone>[];
+/**
+ * `milestoneStops` as a footprintjs `TimeTravelStrategy` — what you hand
+ * `timeTravel(snapshot, { strategy })`. Typed over {@link Milestone}, so the
+ * cursor's stops are `Stop<Milestone>` and `cursor.at()?.meta?.kind` is typed;
+ * it is still assignable wherever a bare `TimeTravelStrategy` is expected.
+ */
+export declare const milestoneStopsStrategy: TimeTravelStrategy<Milestone>;
+//# sourceMappingURL=milestoneStops.d.ts.map

package/dist/types/time-travel/milestoneStops.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"milestoneStops.d.ts","sourceRoot":"","sources":["../../../src/time-travel/milestoneStops.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAE1D,OAAO,KAAK,EAAE,YAAY,EAAE,IAAI,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AACxE,OAAO,EAIL,KAAK,SAAS,EACf,MAAM,uBAAuB,CAAC;AAS/B;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,GAAG,SAAS,GAAG,IAAI,CAGjE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgFG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,SAAS,YAAY,EAAE,EAClC,aAAa,CAAC,EAAE,aAAa,GAC5B,IAAI,CAAC,SAAS,CAAC,EAAE,CAKnB;AA6BD;;;;;GAKG;AACH,eAAO,MAAM,sBAAsB,EAAE,kBAAkB,CAAC,SAAS,CAAgC,CAAC"}