agentfootprint 10.3.0 → 10.3.1

package/dist/esm/time-travel/index.js

@@ -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, } from './epochs.js';
+export { keyedFold } from './keyedFold.js';
+export { buildReceipt, messageDigestInput, toolDigestInput, receiptHash, transformHashOf, TRANSFORM_HASH_PREFIX, FORCED_OUTPUT_TOOL_KEY, RECEIPT_BOUNDARY, RECEIPT_HASH_CHARS, UNSERIALIZABLE, } 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, } from './servedView.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/time-travel/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","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,GAGZ,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,SAAS,EAAuD,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,GAWf,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,GAOhB,MAAM,iBAAiB,CAAC"}

package/dist/esm/time-travel/keyedFold.js.map

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

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

@@ -0,0 +1,149 @@
+/**
+ * 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>;

package/dist/esm/time-travel/milestoneStops.js

@@ -0,0 +1,192 @@
+/**
+ * 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 { commitStops, filterStops } from 'foottrace';
+import { MILESTONE_KINDS, milestoneFor, milestoneFromTags, } from '../lib/conventions.js';
+/** Is this `meta` a {@link Milestone} — ours, not another strategy's? */
+function isMilestone(meta) {
+    if (meta === null || typeof meta !== 'object')
+        return false;
+    const { kind, label } = meta;
+    return typeof label === 'string' && MILESTONE_KINDS.includes(kind);
+}
+/**
+ * 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 function milestoneOf(stop) {
+    if (isMilestone(stop.meta))
+        return stop.meta;
+    return stop.runtimeStageId ? milestoneFor(stop.runtimeStageId) : 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 function milestoneStops(commitLog, executionTree) {
+    return filterStops(commitStops(commitLog, executionTree), (stop) => {
+        const milestone = milestoneAt(commitLog, stop);
+        return milestone ? { label: milestone.label, meta: milestone } : null;
+    });
+}
+/**
+ * The milestone a stop stands for — **the tag is the fact, the id is the
+ * fallback** (9.90.0; law 3 of footprintjs's declared-tags design).
+ *
+ * The stop's FIRST bundle (`stop.commitIdx` — where footprintjs stamps a
+ * stage's declared tags) is read first: when it carries tags, the answer is
+ * whatever `milestone:<kind>` / `milestone-label:<label>` they declare, and a
+ * bundle that is tagged but NOT as a milestone is not a stop, however
+ * recognisable its id — the chart said what this stage is. Only a bundle with
+ * no tags at all is classified from its id: a recording made before the charts
+ * declared their milestones. On a 9.90.0 recording that path runs ZERO times —
+ * every milestone stage is declared, slot branch mounts included (footprintjs
+ * 9.21.1 `SubflowMountOptions.tags`), and
+ * `test/time-travel/milestone-stops-equivalence.test.ts` counts the
+ * fallback on every fixture. Both readings come from the one table in
+ * `conventions.ts`, so they agree wherever both exist.
+ */
+function milestoneAt(log, stop) {
+    const raw = log[stop.commitIdx]?.tags;
+    // A stored row is `unknown[]`-shaped until narrowed: only STRINGS count as
+    // declared tags (the same narrowing footprintjs's `tagStops` does), so a
+    // damaged row falls back to the id like an untagged one instead of vanishing.
+    const tags = Array.isArray(raw) ? raw.filter((t) => typeof t === 'string') : [];
+    if (tags.length > 0)
+        return milestoneFromTags(tags, stop.label);
+    return milestoneFor(stop.runtimeStageId);
+}
+/**
+ * `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 const milestoneStopsStrategy = { stopsFor: milestoneStops };
+//# sourceMappingURL=milestoneStops.js.map

package/dist/esm/time-travel/milestoneStops.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"milestoneStops.js","sourceRoot":"","sources":["../../../src/time-travel/milestoneStops.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAGH,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AAErD,OAAO,EACL,eAAe,EACf,YAAY,EACZ,iBAAiB,GAElB,MAAM,uBAAuB,CAAC;AAE/B,yEAAyE;AACzE,SAAS,WAAW,CAAC,IAAa;IAChC,IAAI,IAAI,KAAK,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5D,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,IAA2C,CAAC;IACpE,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAK,eAAsC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAC7F,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,WAAW,CAAC,IAAmB;IAC7C,IAAI,WAAW,CAAC,IAAI,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,CAAC,IAAI,CAAC;IAC7C,OAAO,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;AACxE,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgFG;AACH,MAAM,UAAU,cAAc,CAC5B,SAAkC,EAClC,aAA6B;IAE7B,OAAO,WAAW,CAAY,WAAW,CAAC,SAAS,EAAE,aAAa,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE;QAC5E,MAAM,SAAS,GAAG,WAAW,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;QAC/C,OAAO,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;IACxE,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,SAAS,WAAW,CAAC,GAA4B,EAAE,IAAmB;IACpE,MAAM,GAAG,GAAG,GAAG,CAAC,IAAI,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC;IACtC,2EAA2E;IAC3E,yEAAyE;IACzE,8EAA8E;IAC9E,MAAM,IAAI,GAAG,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAC7F,IAAI,IAAI,CAAC,MAAM,GAAG,CAAC;QAAE,OAAO,iBAAiB,CAAC,IAAI,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;IAChE,OAAO,YAAY,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;AAC3C,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAkC,EAAE,QAAQ,EAAE,cAAc,EAAE,CAAC"}