agent-bober 0.17.0 → 0.18.0

package/dist/orchestrator/selfimprove/replay-store.js

@@ -0,0 +1,119 @@
+import { createHash } from "node:crypto";
+import Database from "better-sqlite3";
+import { ReplayCaseSchema, } from "./replay-types.js";
+// ── Deterministic id ──────────────────────────────────────────────────
+/**
+ * Derive a deterministic 16-char hex case id from the case signature.
+ * caseId = sha256(`${contractId}|${iteration}|${diffDigest}`).slice(0,16)
+ * MIRRORS factId at src/state/facts.ts:58-69.
+ *
+ * NOTE: tCaptured is intentionally EXCLUDED from the hash so the id stays
+ * stable across captures — only a change in diffDigest changes the id.
+ * Identical inputs always produce the same id — no wall-clock dependency.
+ */
+export function caseId(contractId, iteration, diffDigest) {
+    return createHash("sha256")
+        .update(`${contractId}|${iteration}|${diffDigest}`)
+        .digest("hex")
+        .slice(0, 16);
+}
+function rowToRecord(row) {
+    return {
+        caseId: row.case_id,
+        contractId: row.contract_id,
+        iteration: row.iteration,
+        baselineVerdict: row.baseline_verdict,
+        diffDigest: row.diff_digest,
+        evalDetailsJson: row.eval_details_json,
+        tCaptured: row.t_captured,
+    };
+}
+// ── ReplayStore ───────────────────────────────────────────────────────
+/**
+ * SQLite-backed replay case store.
+ *
+ * PURE: Never calls Date.now() or new Date() — every timestamp is a parameter.
+ * Hidden behind this interface so the driver (better-sqlite3) is swappable.
+ *
+ * bober: in-memory or file-backed via better-sqlite3 (synchronous); swap for
+ * node:sqlite when engines.node is raised to >=22.5.
+ */
+export class ReplayStore {
+    db;
+    constructor(dbPath) {
+        this.db = new Database(dbPath);
+        this.db.exec(`
+      CREATE TABLE IF NOT EXISTS replay_cases (
+        case_id TEXT PRIMARY KEY,
+        contract_id TEXT NOT NULL,
+        iteration INTEGER NOT NULL,
+        baseline_verdict TEXT NOT NULL,
+        diff_digest TEXT NOT NULL,
+        eval_details_json TEXT NOT NULL,
+        t_captured TEXT NOT NULL
+      );
+    `);
+    }
+    /**
+     * Insert or replace a replay case. Validates input with ReplayCaseSchema and
+     * derives the deterministic caseId. Returns the persisted ReplayCaseRecord.
+     */
+    putCase(input) {
+        const result = ReplayCaseSchema.safeParse(input);
+        if (!result.success) {
+            const issues = result.error.issues
+                .map((i) => `  - ${i.path.join(".")}: ${i.message}`)
+                .join("\n");
+            throw new Error(`Invalid replay case input:\n${issues}`);
+        }
+        const data = result.data;
+        const id = caseId(data.contractId, data.iteration, data.diffDigest);
+        this.db
+            .prepare(`INSERT OR REPLACE INTO replay_cases
+          (case_id, contract_id, iteration, baseline_verdict, diff_digest, eval_details_json, t_captured)
+         VALUES (?, ?, ?, ?, ?, ?, ?)`)
+            .run(id, data.contractId, data.iteration, data.baselineVerdict, data.diffDigest, data.evalDetailsJson, data.tCaptured);
+        return {
+            caseId: id,
+            contractId: data.contractId,
+            iteration: data.iteration,
+            baselineVerdict: data.baselineVerdict,
+            diffDigest: data.diffDigest,
+            evalDetailsJson: data.evalDetailsJson,
+            tCaptured: data.tCaptured,
+        };
+    }
+    /**
+     * Return a single replay case by its id.
+     * Returns null if not found.
+     */
+    getCase(id) {
+        const row = this.db
+            .prepare(`SELECT * FROM replay_cases WHERE case_id = ?`)
+            .get(id);
+        return row ? rowToRecord(row) : null;
+    }
+    /**
+     * Return all replay cases ordered by t_captured ascending.
+     */
+    listCases() {
+        const rows = this.db
+            .prepare(`SELECT * FROM replay_cases ORDER BY t_captured ASC`)
+            .all();
+        return rows.map(rowToRecord);
+    }
+    /**
+     * Return the baseline verdict for a case id, or null if not found.
+     */
+    getBaselineVerdict(id) {
+        const row = this.db
+            .prepare(`SELECT baseline_verdict FROM replay_cases WHERE case_id = ?`)
+            .get(id);
+        return row?.baseline_verdict ?? null;
+    }
+    /** Close the underlying database connection. */
+    close() {
+        this.db.close();
+    }
+}
+//# sourceMappingURL=replay-store.js.map

package/dist/orchestrator/selfimprove/replay-store.js.map

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

package/dist/orchestrator/selfimprove/replay-types.d.ts

@@ -0,0 +1,32 @@
+import { z } from "zod";
+/**
+ * Zod schema for a replay case input — mirrors FactSchema in src/state/facts.ts.
+ * All timestamps are ISO 8601 strings; the store never reads the clock.
+ */
+export declare const ReplayCaseSchema: z.ZodObject<{
+    contractId: z.ZodString;
+    iteration: z.ZodNumber;
+    baselineVerdict: z.ZodEnum<["pass", "fail"]>;
+    diffDigest: z.ZodString;
+    evalDetailsJson: z.ZodString;
+    tCaptured: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    contractId: string;
+    iteration: number;
+    baselineVerdict: "pass" | "fail";
+    diffDigest: string;
+    evalDetailsJson: string;
+    tCaptured: string;
+}, {
+    contractId: string;
+    iteration: number;
+    baselineVerdict: "pass" | "fail";
+    diffDigest: string;
+    evalDetailsJson: string;
+    tCaptured: string;
+}>;
+export type ReplayCaseInput = z.infer<typeof ReplayCaseSchema>;
+export interface ReplayCaseRecord extends ReplayCaseInput {
+    caseId: string;
+}
+//# sourceMappingURL=replay-types.d.ts.map

package/dist/orchestrator/selfimprove/replay-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-types.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/selfimprove/replay-types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAIxB;;;GAGG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;EAO3B,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAI/D,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACvD,MAAM,EAAE,MAAM,CAAC;CAChB"}

package/dist/orchestrator/selfimprove/replay-types.js

@@ -0,0 +1,15 @@
+import { z } from "zod";
+// ── Schema ────────────────────────────────────────────────────────────
+/**
+ * Zod schema for a replay case input — mirrors FactSchema in src/state/facts.ts.
+ * All timestamps are ISO 8601 strings; the store never reads the clock.
+ */
+export const ReplayCaseSchema = z.object({
+    contractId: z.string().min(1),
+    iteration: z.number().int(),
+    baselineVerdict: z.enum(["pass", "fail"]),
+    diffDigest: z.string().min(1),
+    evalDetailsJson: z.string(),
+    tCaptured: z.string().datetime(),
+});
+//# sourceMappingURL=replay-types.js.map

package/dist/orchestrator/selfimprove/replay-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"replay-types.js","sourceRoot":"","sources":["../../../src/orchestrator/selfimprove/replay-types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,yEAAyE;AAEzE;;;GAGG;AACH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAC,MAAM,CAAC;IACvC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IAC3B,eAAe,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC;IAC7B,eAAe,EAAE,CAAC,CAAC,MAAM,EAAE;IAC3B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;CACjC,CAAC,CAAC"}

package/dist/orchestrator/workflow/engine.d.ts

@@ -5,6 +5,8 @@ export type PipelineEngineName = "ts" | "skill" | "workflow";
 /** Interface every pipeline engine implementation must satisfy. */
 export interface PipelineEngine {
     readonly name: PipelineEngineName;
-    run(userPrompt: string, projectRoot: string, config: BoberConfig): Promise<PipelineResult>;
+    run(userPrompt: string, projectRoot: string, config: BoberConfig, opts?: {
+        runId?: string;
+    }): Promise<PipelineResult>;
 }
 //# sourceMappingURL=engine.d.ts.map

package/dist/orchestrator/workflow/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/workflow/engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAIrD,0FAA0F;AAC1F,MAAM,MAAM,kBAAkB,GAAG,IAAI,GAAG,OAAO,GAAG,UAAU,CAAC;AAE7D,mEAAmE;AACnE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,GAAG,CACD,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,cAAc,CAAC,CAAC;CAC5B"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/workflow/engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAIrD,0FAA0F;AAC1F,MAAM,MAAM,kBAAkB,GAAG,IAAI,GAAG,OAAO,GAAG,UAAU,CAAC;AAE7D,mEAAmE;AACnE,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAC;IAClC,GAAG,CACD,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,WAAW,EACnB,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GACxB,OAAO,CAAC,cAAc,CAAC,CAAC;CAC5B"}

package/dist/orchestrator/workflow/selector.d.ts

@@ -1,5 +1,6 @@
 import type { BoberConfig } from "../../config/schema.js";
 import type { PipelineEngine, PipelineEngineName } from "./engine.js";
+import type { Team } from "../../teams/types.js";
 /**
  * Pure resolver — returns the engine name without instantiating an engine.
  *
@@ -23,4 +24,21 @@ export declare function resolveEngineName(config: BoberConfig): PipelineEngineNa
  *   - 'skill' remains on TsPipelineEngine (no skill engine this sprint — non-goal).
  */
 export declare function selectPipelineEngine(config: BoberConfig): PipelineEngine;
+/**
+ * Pure resolver — returns the engine name for a team, using team.pipelineShape
+ * as the requested engine, then applying the SAME downgrade pipeline as
+ * resolveEngineName (ineligible or mode='careful' → 'ts').
+ *
+ * The downgrade log line is byte-identical to resolveEngineName's (selector.ts:29-31).
+ */
+export declare function resolveEngineNameForTeam(team: Team, config: BoberConfig): PipelineEngineName;
+/**
+ * Resolve a Team's pipelineShape to a PipelineEngine instance.
+ *
+ * Applies the same downgrade rules as selectPipelineEngine (via resolveEngineNameForTeam),
+ * and uses the same exhaustive switch over PipelineEngineName. The programming team's
+ * pipelineShape === resolveEngineName(config) by construction (registry.ts:68), so this
+ * is byte-for-byte identical to selectPipelineEngine(config) for the programming team.
+ */
+export declare function selectPipelineEngineForTeam(team: Team, config: BoberConfig): PipelineEngine;
 //# sourceMappingURL=selector.d.ts.map

package/dist/orchestrator/workflow/selector.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"selector.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/workflow/selector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE1D,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAOtE;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,GAAG,kBAAkB,CAezE;AAID;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,WAAW,GAAG,cAAc,CAaxE"}
+{"version":3,"file":"selector.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/workflow/selector.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE1D,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAItE,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,sBAAsB,CAAC;AAIjD;;;;;;;;;;;GAWG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,WAAW,GAAG,kBAAkB,CAezE;AAID;;;;;;;;GAQG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,WAAW,GAAG,cAAc,CAaxE;AAID;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CACtC,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,WAAW,GAClB,kBAAkB,CAepB;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,WAAW,GAClB,cAAc,CAYhB"}

package/dist/orchestrator/workflow/selector.js

@@ -51,4 +51,45 @@ export function selectPipelineEngine(config) {
             return new WorkflowEngine();
     }
 }
+// ── Team-aware selection ───────────────────────────────────────────
+/**
+ * Pure resolver — returns the engine name for a team, using team.pipelineShape
+ * as the requested engine, then applying the SAME downgrade pipeline as
+ * resolveEngineName (ineligible or mode='careful' → 'ts').
+ *
+ * The downgrade log line is byte-identical to resolveEngineName's (selector.ts:29-31).
+ */
+export function resolveEngineNameForTeam(team, config) {
+    const requested = team.pipelineShape;
+    if (requested === "workflow") {
+        const eligible = isWorkflowEligible(config);
+        const careful = config.pipeline?.mode === "careful";
+        if (!eligible || careful) {
+            logger.info(`Workflow engine requested but ${!eligible ? "ineligible" : "mode='careful'"}; downgrading to 'ts'.`);
+            return "ts";
+        }
+    }
+    return requested;
+}
+/**
+ * Resolve a Team's pipelineShape to a PipelineEngine instance.
+ *
+ * Applies the same downgrade rules as selectPipelineEngine (via resolveEngineNameForTeam),
+ * and uses the same exhaustive switch over PipelineEngineName. The programming team's
+ * pipelineShape === resolveEngineName(config) by construction (registry.ts:68), so this
+ * is byte-for-byte identical to selectPipelineEngine(config) for the programming team.
+ */
+export function selectPipelineEngineForTeam(team, config) {
+    const name = resolveEngineNameForTeam(team, config);
+    switch (name) {
+        case "ts":
+            return new TsPipelineEngine();
+        case "skill":
+            // Skill engine deferred (non-goal); falls through to TS.
+            return new TsPipelineEngine();
+        case "workflow":
+            // Reachable only when resolveEngineNameForTeam returns 'workflow' (eligible + not careful).
+            return new WorkflowEngine();
+    }
+}
 //# sourceMappingURL=selector.js.map

package/dist/orchestrator/workflow/selector.js.map

@@ -1 +1 @@
-{"version":3,"file":"selector.js","sourceRoot":"","sources":["../../../src/orchestrator/workflow/selector.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAE/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAEtD,sEAAsE;AAEtE;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAmB;IACnD,MAAM,SAAS,GAAuB,MAAM,CAAC,QAAQ,EAAE,MAAM,IAAI,IAAI,CAAC;IAEtE,IAAI,SAAS,KAAK,UAAU,EAAE,CAAC;QAC7B,MAAM,QAAQ,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;QAC5C,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,EAAE,IAAI,KAAK,SAAS,CAAC;QACpD,IAAI,CAAC,QAAQ,IAAI,OAAO,EAAE,CAAC;YACzB,MAAM,CAAC,IAAI,CACT,iCAAiC,CAAC,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,gBAAgB,wBAAwB,CACrG,CAAC;YACF,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,sEAAsE;AAEtE;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAmB;IACtD,MAAM,IAAI,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;IACvC,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,IAAI;YACP,OAAO,IAAI,gBAAgB,EAAE,CAAC;QAChC,KAAK,OAAO;YACV,qEAAqE;YACrE,OAAO,IAAI,gBAAgB,EAAE,CAAC;QAChC,KAAK,UAAU;YACb,qFAAqF;YACrF,mFAAmF;YACnF,OAAO,IAAI,cAAc,EAAE,CAAC;IAChC,CAAC;AACH,CAAC"}
+{"version":3,"file":"selector.js","sourceRoot":"","sources":["../../../src/orchestrator/workflow/selector.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAE/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAGtD,sEAAsE;AAEtE;;;;;;;;;;;GAWG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAmB;IACnD,MAAM,SAAS,GAAuB,MAAM,CAAC,QAAQ,EAAE,MAAM,IAAI,IAAI,CAAC;IAEtE,IAAI,SAAS,KAAK,UAAU,EAAE,CAAC;QAC7B,MAAM,QAAQ,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;QAC5C,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,EAAE,IAAI,KAAK,SAAS,CAAC;QACpD,IAAI,CAAC,QAAQ,IAAI,OAAO,EAAE,CAAC;YACzB,MAAM,CAAC,IAAI,CACT,iCAAiC,CAAC,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,gBAAgB,wBAAwB,CACrG,CAAC;YACF,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,sEAAsE;AAEtE;;;;;;;;GAQG;AACH,MAAM,UAAU,oBAAoB,CAAC,MAAmB;IACtD,MAAM,IAAI,GAAG,iBAAiB,CAAC,MAAM,CAAC,CAAC;IACvC,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,IAAI;YACP,OAAO,IAAI,gBAAgB,EAAE,CAAC;QAChC,KAAK,OAAO;YACV,qEAAqE;YACrE,OAAO,IAAI,gBAAgB,EAAE,CAAC;QAChC,KAAK,UAAU;YACb,qFAAqF;YACrF,mFAAmF;YACnF,OAAO,IAAI,cAAc,EAAE,CAAC;IAChC,CAAC;AACH,CAAC;AAED,sEAAsE;AAEtE;;;;;;GAMG;AACH,MAAM,UAAU,wBAAwB,CACtC,IAAU,EACV,MAAmB;IAEnB,MAAM,SAAS,GAAG,IAAI,CAAC,aAAa,CAAC;IAErC,IAAI,SAAS,KAAK,UAAU,EAAE,CAAC;QAC7B,MAAM,QAAQ,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;QAC5C,MAAM,OAAO,GAAG,MAAM,CAAC,QAAQ,EAAE,IAAI,KAAK,SAAS,CAAC;QACpD,IAAI,CAAC,QAAQ,IAAI,OAAO,EAAE,CAAC;YACzB,MAAM,CAAC,IAAI,CACT,iCAAiC,CAAC,QAAQ,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,gBAAgB,wBAAwB,CACrG,CAAC;YACF,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,OAAO,SAAS,CAAC;AACnB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,2BAA2B,CACzC,IAAU,EACV,MAAmB;IAEnB,MAAM,IAAI,GAAG,wBAAwB,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IACpD,QAAQ,IAAI,EAAE,CAAC;QACb,KAAK,IAAI;YACP,OAAO,IAAI,gBAAgB,EAAE,CAAC;QAChC,KAAK,OAAO;YACV,yDAAyD;YACzD,OAAO,IAAI,gBAAgB,EAAE,CAAC;QAChC,KAAK,UAAU;YACb,4FAA4F;YAC5F,OAAO,IAAI,cAAc,EAAE,CAAC;IAChC,CAAC;AACH,CAAC"}

package/dist/orchestrator/workflow/ts-engine.d.ts

@@ -8,6 +8,8 @@ import type { PipelineEngine, PipelineEngineName } from "./engine.js";
  */
 export declare class TsPipelineEngine implements PipelineEngine {
     readonly name: PipelineEngineName;
-    run(userPrompt: string, projectRoot: string, config: BoberConfig): Promise<PipelineResult>;
+    run(userPrompt: string, projectRoot: string, config: BoberConfig, opts?: {
+        runId?: string;
+    }): Promise<PipelineResult>;
 }
 //# sourceMappingURL=ts-engine.d.ts.map

package/dist/orchestrator/workflow/ts-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ts-engine.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/workflow/ts-engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAItE;;;;GAIG;AACH,qBAAa,gBAAiB,YAAW,cAAc;IACrD,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAQ;IAEzC,GAAG,CACD,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,cAAc,CAAC;CAG3B"}
+{"version":3,"file":"ts-engine.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/workflow/ts-engine.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAE1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAItE;;;;GAIG;AACH,qBAAa,gBAAiB,YAAW,cAAc;IACrD,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAQ;IAEzC,GAAG,CACD,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,WAAW,EACnB,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GACxB,OAAO,CAAC,cAAc,CAAC;CAG3B"}

package/dist/orchestrator/workflow/ts-engine.js

@@ -7,8 +7,8 @@ import { runTsPipeline } from "../pipeline.js";
  */
 export class TsPipelineEngine {
     name = "ts";
-    run(userPrompt, projectRoot, config) {
-        return runTsPipeline(userPrompt, projectRoot, config);
+    run(userPrompt, projectRoot, config, opts) {
+        return runTsPipeline(userPrompt, projectRoot, config, opts);
     }
 }
 //# sourceMappingURL=ts-engine.js.map

package/dist/orchestrator/workflow/ts-engine.js.map

@@ -1 +1 @@
-{"version":3,"file":"ts-engine.js","sourceRoot":"","sources":["../../../src/orchestrator/workflow/ts-engine.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAI/C,sEAAsE;AAEtE;;;;GAIG;AACH,MAAM,OAAO,gBAAgB;IAClB,IAAI,GAAuB,IAAI,CAAC;IAEzC,GAAG,CACD,UAAkB,EAClB,WAAmB,EACnB,MAAmB;QAEnB,OAAO,aAAa,CAAC,UAAU,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC;IACxD,CAAC;CACF"}
+{"version":3,"file":"ts-engine.js","sourceRoot":"","sources":["../../../src/orchestrator/workflow/ts-engine.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC;AAI/C,sEAAsE;AAEtE;;;;GAIG;AACH,MAAM,OAAO,gBAAgB;IAClB,IAAI,GAAuB,IAAI,CAAC;IAEzC,GAAG,CACD,UAAkB,EAClB,WAAmB,EACnB,MAAmB,EACnB,IAAyB;QAEzB,OAAO,aAAa,CAAC,UAAU,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;IAC9D,CAAC;CACF"}

package/dist/orchestrator/workflow/workflow-engine.d.ts

@@ -25,7 +25,9 @@ export declare class WorkflowEngine implements PipelineEngine {
      * spawning real LLM agents.
      */
     constructor(tsEngineFactory?: () => PipelineEngine);
-    run(userPrompt: string, projectRoot: string, config: BoberConfig): Promise<PipelineResult>;
+    run(userPrompt: string, projectRoot: string, config: BoberConfig, opts?: {
+        runId?: string;
+    }): Promise<PipelineResult>;
     private invoke;
 }
 //# sourceMappingURL=workflow-engine.d.ts.map

package/dist/orchestrator/workflow/workflow-engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workflow-engine.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/workflow/workflow-engine.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAWtE;;;;;;;;;;;;;;GAcG;AACH,qBAAa,cAAe,YAAW,cAAc;IASjD,OAAO,CAAC,QAAQ,CAAC,eAAe;IARlC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAc;IAE/C;;;;OAIG;gBAEgB,eAAe,GAAE,MAAM,cAChB;IAGpB,GAAG,CACP,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,cAAc,CAAC;YAwCZ,MAAM;CAKrB"}
+{"version":3,"file":"workflow-engine.d.ts","sourceRoot":"","sources":["../../../src/orchestrator/workflow/workflow-engine.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gBAAgB,CAAC;AAErD,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAWtE;;;;;;;;;;;;;;GAcG;AACH,qBAAa,cAAe,YAAW,cAAc;IASjD,OAAO,CAAC,QAAQ,CAAC,eAAe;IARlC,QAAQ,CAAC,IAAI,EAAE,kBAAkB,CAAc;IAE/C;;;;OAIG;gBAEgB,eAAe,GAAE,MAAM,cAChB;IAGpB,GAAG,CACP,UAAU,EAAE,MAAM,EAClB,WAAW,EAAE,MAAM,EACnB,MAAM,EAAE,WAAW,EACnB,IAAI,CAAC,EAAE;QAAE,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GACxB,OAAO,CAAC,cAAc,CAAC;YAwCZ,MAAM;CAKrB"}

package/dist/orchestrator/workflow/workflow-engine.js

@@ -33,11 +33,11 @@ export class WorkflowEngine {
     constructor(tsEngineFactory = () => new TsPipelineEngine()) {
         this.tsEngineFactory = tsEngineFactory;
     }
-    async run(userPrompt, projectRoot, config) {
+    async run(userPrompt, projectRoot, config, opts) {
         // ── STEP 1: Eligibility check FIRST (avoids MissingKnobError on downgrade path) ──
         if (!isWorkflowEligible(config)) {
             logger.info("workflow runtime unavailable — re-dispatching TS engine");
-            return this.tsEngineFactory().run(userPrompt, projectRoot, config);
+            return this.tsEngineFactory().run(userPrompt, projectRoot, config, opts);
         }
         // ── STEP 2: Reconstruct cursor (read-only — writes nothing) ────────────────
         // specId is derived from config or empty — invoke is dormant so this is
@@ -54,7 +54,7 @@ export class WorkflowEngine {
         catch (e) {
             if (e instanceof WorkflowUnavailableError) {
                 logger.info("workflow runtime unavailable — re-dispatching TS engine");
-                return this.tsEngineFactory().run(userPrompt, projectRoot, config);
+                return this.tsEngineFactory().run(userPrompt, projectRoot, config, opts);
             }
             throw e;
         }

package/dist/orchestrator/workflow/workflow-engine.js.map

@@ -1 +1 @@
-{"version":3,"file":"workflow-engine.js","sourceRoot":"","sources":["../../../src/orchestrator/workflow/workflow-engine.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAItE,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAE/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAGvD,uEAAuE;AAEvE;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,cAAc;IASN;IARV,IAAI,GAAuB,UAAU,CAAC;IAE/C;;;;OAIG;IACH,YACmB,kBAAwC,GAAG,EAAE,CAC5D,IAAI,gBAAgB,EAAE;QADP,oBAAe,GAAf,eAAe,CACR;IACvB,CAAC;IAEJ,KAAK,CAAC,GAAG,CACP,UAAkB,EAClB,WAAmB,EACnB,MAAmB;QAEnB,oFAAoF;QACpF,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAC;YAChC,MAAM,CAAC,IAAI,CACT,yDAAyD,CAC1D,CAAC;YACF,OAAO,IAAI,CAAC,eAAe,EAAE,CAAC,GAAG,CAAC,UAAU,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC;QACrE,CAAC;QAED,8EAA8E;QAC9E,wEAAwE;QACxE,6EAA6E;QAC7E,MAAM,MAAM,GAAI,MAAM,CAAC,OAA2C,EAAE,MAAM,IAAI,EAAE,CAAC;QACjF,MAAM,MAAM,GAAG,MAAM,IAAI,yBAAyB,EAAE,CAAC,WAAW,CAC9D,WAAW,EACX,MAAM,CACP,CAAC;QAEF,+EAA+E;QAC/E,MAAM,IAAI,GAAG,IAAI,kBAAkB,EAAE,CAAC,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC;QAE5E,8EAA8E;QAC9E,IAAI,CAAC;YACH,MAAM,MAAM,GAAsB,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAC1D,OAAO,MAAM,IAAI,gBAAgB,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QACzE,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,YAAY,wBAAwB,EAAE,CAAC;gBAC1C,MAAM,CAAC,IAAI,CACT,yDAAyD,CAC1D,CAAC;gBACF,OAAO,IAAI,CAAC,eAAe,EAAE,CAAC,GAAG,CAAC,UAAU,EAAE,WAAW,EAAE,MAAM,CAAC,CAAC;YACrE,CAAC;YACD,MAAM,CAAC,CAAC;QACV,CAAC;IACH,CAAC;IAED,8EAA8E;IAC9E,EAAE;IACF,gFAAgF;IAChF,gFAAgF;IACxE,KAAK,CAAC,MAAM,CAAC,KAAmB;QACtC,MAAM,IAAI,wBAAwB,CAChC,+DAA+D,CAChE,CAAC;IACJ,CAAC;CACF"}
+{"version":3,"file":"workflow-engine.js","sourceRoot":"","sources":["../../../src/orchestrator/workflow/workflow-engine.ts"],"names":[],"mappings":"AAAA,sEAAsE;AAItE,OAAO,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAE/C,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAE,yBAAyB,EAAE,MAAM,oBAAoB,CAAC;AAC/D,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC;AACvD,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAChD,OAAO,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAClD,OAAO,EAAE,wBAAwB,EAAE,MAAM,aAAa,CAAC;AAGvD,uEAAuE;AAEvE;;;;;;;;;;;;;;GAcG;AACH,MAAM,OAAO,cAAc;IASN;IARV,IAAI,GAAuB,UAAU,CAAC;IAE/C;;;;OAIG;IACH,YACmB,kBAAwC,GAAG,EAAE,CAC5D,IAAI,gBAAgB,EAAE;QADP,oBAAe,GAAf,eAAe,CACR;IACvB,CAAC;IAEJ,KAAK,CAAC,GAAG,CACP,UAAkB,EAClB,WAAmB,EACnB,MAAmB,EACnB,IAAyB;QAEzB,oFAAoF;QACpF,IAAI,CAAC,kBAAkB,CAAC,MAAM,CAAC,EAAE,CAAC;YAChC,MAAM,CAAC,IAAI,CACT,yDAAyD,CAC1D,CAAC;YACF,OAAO,IAAI,CAAC,eAAe,EAAE,CAAC,GAAG,CAAC,UAAU,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;QAC3E,CAAC;QAED,8EAA8E;QAC9E,wEAAwE;QACxE,6EAA6E;QAC7E,MAAM,MAAM,GAAI,MAAM,CAAC,OAA2C,EAAE,MAAM,IAAI,EAAE,CAAC;QACjF,MAAM,MAAM,GAAG,MAAM,IAAI,yBAAyB,EAAE,CAAC,WAAW,CAC9D,WAAW,EACX,MAAM,CACP,CAAC;QAEF,+EAA+E;QAC/E,MAAM,IAAI,GAAG,IAAI,kBAAkB,EAAE,CAAC,KAAK,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC;QAE5E,8EAA8E;QAC9E,IAAI,CAAC;YACH,MAAM,MAAM,GAAsB,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;YAC1D,OAAO,MAAM,IAAI,gBAAgB,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC;QACzE,CAAC;QAAC,OAAO,CAAC,EAAE,CAAC;YACX,IAAI,CAAC,YAAY,wBAAwB,EAAE,CAAC;gBAC1C,MAAM,CAAC,IAAI,CACT,yDAAyD,CAC1D,CAAC;gBACF,OAAO,IAAI,CAAC,eAAe,EAAE,CAAC,GAAG,CAAC,UAAU,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,CAAC,CAAC;YAC3E,CAAC;YACD,MAAM,CAAC,CAAC;QACV,CAAC;IACH,CAAC;IAED,8EAA8E;IAC9E,EAAE;IACF,gFAAgF;IAChF,gFAAgF;IACxE,KAAK,CAAC,MAAM,CAAC,KAAmB;QACtC,MAAM,IAAI,wBAAwB,CAChC,+DAA+D,CAChE,CAAC;IACJ,CAAC;CACF"}

package/dist/state/facts.d.ts

@@ -0,0 +1,110 @@
+import { z } from "zod";
+export { writeFact } from "../orchestrator/memory/reconcile.js";
+export type { ReconcileAction } from "../orchestrator/memory/reconcile.js";
+/**
+ * Zod schema for a fact input — mirrors LessonEntrySchema in memory.ts.
+ * All timestamps are ISO 8601 strings; the store never reads the clock.
+ */
+export declare const FactSchema: z.ZodObject<{
+    scope: z.ZodString;
+    subject: z.ZodString;
+    predicate: z.ZodString;
+    value: z.ZodString;
+    confidence: z.ZodDefault<z.ZodNumber>;
+    sourceRunId: z.ZodDefault<z.ZodNullable<z.ZodString>>;
+    tValid: z.ZodString;
+    tCreated: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    value: string;
+    scope: string;
+    subject: string;
+    predicate: string;
+    confidence: number;
+    sourceRunId: string | null;
+    tValid: string;
+    tCreated: string;
+}, {
+    value: string;
+    scope: string;
+    subject: string;
+    predicate: string;
+    tValid: string;
+    tCreated: string;
+    confidence?: number | undefined;
+    sourceRunId?: string | null | undefined;
+}>;
+export type FactInput = z.infer<typeof FactSchema>;
+export interface FactRecord {
+    id: string;
+    scope: string;
+    subject: string;
+    predicate: string;
+    value: string;
+    confidence: number;
+    sourceRunId: string | null;
+    tValid: string;
+    tInvalid: string | null;
+    tCreated: string;
+    tInvalidated: string | null;
+}
+/**
+ * Derive a deterministic 16-char hex fact id from the fact signature.
+ * Mirrors lessonIdFromSignature in src/orchestrator/memory/distill.ts:88-99.
+ * Identical inputs always produce the same id — no wall-clock dependency.
+ */
+export declare function factId(scope: string, subject: string, predicate: string, value: string, tCreated: string): string;
+/**
+ * Resolve the absolute path to facts.db for the given project root and namespace.
+ * Uses the same memoryDir mapping rule as memory.ts (no duplication).
+ */
+export declare function factsDbPath(projectRoot: string, namespace?: string): string;
+/**
+ * Ensure the directory that will hold the DB file exists.
+ * Must be called by the CLI handler before constructing a file-backed FactStore.
+ * Not needed for ':memory:' paths.
+ */
+export declare function ensureFactsDir(projectRoot: string, namespace?: string): Promise<void>;
+/**
+ * Bi-temporal SQLite-backed fact store.
+ *
+ * PURE: Never calls Date.now() or new Date() — every timestamp is a parameter.
+ * Hidden behind this interface so the driver (better-sqlite3) is swappable.
+ *
+ * bober: in-memory or file-backed via better-sqlite3 (synchronous); swap for
+ * node:sqlite when engines.node is raised to >=22.5.
+ */
+export declare class FactStore {
+    private db;
+    constructor(dbPath: string);
+    /**
+     * Insert a new fact. Validates input with FactSchema and derives the
+     * deterministic id. Returns the persisted FactRecord.
+     */
+    insertFact(input: FactInput): FactRecord;
+    /**
+     * Return all active (non-invalidated) facts matching the given scope.
+     * Optionally filtered by subject and/or predicate.
+     * Active = t_invalidated IS NULL.
+     */
+    getActiveFacts(scope: string, subject?: string, predicate?: string): FactRecord[];
+    /**
+     * Return a single fact by its id regardless of invalidation status.
+     * Returns null if not found.
+     */
+    getFact(id: string): FactRecord | null;
+    /**
+     * Soft-delete a fact by setting t_invalidated.
+     * Returns true if the fact was invalidated, false if it was already invalidated or not found.
+     * Never deletes rows.
+     */
+    invalidateFact(id: string, tInvalidated: string): boolean;
+    /**
+     * Supersede a fact: set BOTH t_invalidated (record-time) AND t_invalid (world-time end).
+     * Used by reconcile on UPDATE to carry both bi-temporal closure fields.
+     * Returns true if the row was updated; false if not found or already invalidated.
+     */
+    supersedeFact(id: string, tInvalidated: string, tInvalid: string): boolean;
+    /** Close the underlying database connection. */
+    close(): void;
+}
+//# sourceMappingURL=facts.d.ts.map

package/dist/state/facts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"facts.d.ts","sourceRoot":"","sources":["../../src/state/facts.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAQxB,OAAO,EAAE,SAAS,EAAE,MAAM,qCAAqC,CAAC;AAChE,YAAY,EAAE,eAAe,EAAE,MAAM,qCAAqC,CAAC;AAI3E;;;GAGG;AACH,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;;;;EASrB,CAAC;AAEH,MAAM,MAAM,SAAS,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAInD,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;CAC7B;AAID;;;;GAIG;AACH,wBAAgB,MAAM,CACpB,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,EACb,QAAQ,EAAE,MAAM,GACf,MAAM,CAKR;AAID;;;GAGG;AACH,wBAAgB,WAAW,CAAC,WAAW,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,MAAM,CAE3E;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAEf;AAoCD;;;;;;;;GAQG;AACH,qBAAa,SAAS;IACpB,OAAO,CAAC,EAAE,CAAe;gBAEb,MAAM,EAAE,MAAM;IAqB1B;;;OAGG;IACH,UAAU,CAAC,KAAK,EAAE,SAAS,GAAG,UAAU;IA4CxC;;;;OAIG;IACH,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,GAAG,UAAU,EAAE;IAqCjF;;;OAGG;IACH,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAOtC;;;;OAIG;IACH,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO;IAWzD;;;;OAIG;IACH,aAAa,CAAC,EAAE,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;IAW1E,gDAAgD;IAChD,KAAK,IAAI,IAAI;CAGd"}