clinkx 0.3.0 → 1.0.0

package/clinkx-workflows/dist/plan-review/runtime-policy.js

@@ -0,0 +1,186 @@
+import { isExcludedPlanPath } from "./context-policy.js";
+import { PLAN_SNAPSHOT_BEGIN, renderPlanSnapshotBlock } from "./expander.js";
+import { PlanReviewStageError } from "./stage-error.js";
+const PROVIDER_STAGE_IDS = ["reviewers", "cross_review", "chairman"];
+/**
+ * Count snapshot-block OPENINGS: the begin marker alone on its own line.
+ *
+ * Line-anchoring is load-bearing, not tidiness. All three shipped actor
+ * templates NAME this marker in their prose, inline and inside backticks, to
+ * tell the model where the plan is (`templates/plan-review/reviewer.txt:4`,
+ * `chairman.txt:17`, `cross-review.txt:10`). A raw substring count therefore
+ * scores an HONEST prompt at 2 — prose mention plus the real block — so a bare
+ * `=== 1` rule rejects every legitimate resumed retry. Only
+ * `renderPlanSnapshotBlock` puts the marker alone on a line, so line-anchoring
+ * counts real blocks and ignores prose that merely quotes the delimiter.
+ *
+ * `\r?` tolerates CRLF-normalized state. It is not an anti-evasion measure:
+ * this whole check is fail-closed integrity on HONEST state, not a boundary
+ * against someone who already owns the state directory (see below).
+ */
+const PLAN_SNAPSHOT_BEGIN_LINE_RE = new RegExp(`^${PLAN_SNAPSHOT_BEGIN.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}\r?$`, "gm");
+function countSnapshotBlockOpenings(haystack) {
+    return [...haystack.matchAll(PLAN_SNAPSHOT_BEGIN_LINE_RE)].length;
+}
+/**
+ * Bind the verified persisted bindings to the persisted normalized definition.
+ * Exact coverage is required: a missing, extra, renamed, or re-providered call
+ * is a corrupt execution contract and must fail pre-backend (D3 — no fallback,
+ * no seat substitution).
+ */
+export function validatePlanReviewCallBindings(definition, bindings) {
+    const byCall = new Map();
+    for (const entry of bindings) {
+        const key = `${entry.stage_id}.${entry.call_id}`;
+        if (byCall.has(key)) {
+            throw new PlanReviewStageError("execution_contract", `Persisted call bindings contain duplicate call ${key}`);
+        }
+        byCall.set(key, entry);
+    }
+    const expected = new Set();
+    for (const stageId of PROVIDER_STAGE_IDS) {
+        const stage = definition.stages.find((candidate) => candidate.id === stageId);
+        if (stage === undefined || stage.calls.length === 0) {
+            throw new PlanReviewStageError("execution_contract", `Plan-review definition has no provider calls in ${stageId}`);
+        }
+        for (const call of stage.calls) {
+            const key = `${stageId}.${call.id}`;
+            expected.add(key);
+            const entry = byCall.get(key);
+            if (entry === undefined) {
+                throw new PlanReviewStageError("execution_contract", `Persisted call bindings are missing call ${key}`);
+            }
+            if (entry.cli_name !== call.cli_name) {
+                throw new PlanReviewStageError("execution_contract", `Persisted call binding provider mismatch for ${key}: ${entry.cli_name} != ${call.cli_name}`);
+            }
+        }
+    }
+    for (const key of byCall.keys()) {
+        if (!expected.has(key)) {
+            throw new PlanReviewStageError("execution_contract", `Persisted call bindings reference unknown call ${key}`);
+        }
+    }
+    return byCall;
+}
+/**
+ * Validate persisted retry identity AND D9 before any provider/backend is created.
+ *
+ * ## Why the prompt is checked here and not left to the definition
+ *
+ * `WorkflowEngine.buildCallInput` replays a persisted prepared input verbatim —
+ * `structuredClone(resumedInput)` with only `cli_name` re-pinned. The expanded
+ * DEFINITION is not what reaches an actor on a resumed retry, so asserting D9
+ * against the definition proves nothing about that dispatch. The plan text now
+ * lives in the prompt bytes, which means the prompt is the D9 surface and this
+ * is the seam that must hold it: it already runs on the resume path, before any
+ * backend is created.
+ *
+ * A LEGITIMATE persisted input always passes, because `buildCallInput` appended
+ * the bound snapshot block at original dispatch and persisted that exact prompt.
+ * So this rejects only state that was tampered with, hand-written, or carried
+ * over from a different plan revision.
+ *
+ * ## What this check ESTABLISHES — and what it does not
+ *
+ * It establishes exactly two things: the verified snapshot block is the prompt's
+ * SUFFIX, and no other block opens before it. POSITION is what makes this exact.
+ * Mere presence is satisfied by a prompt carrying the verified block beside a
+ * second, different plan revision — the resumed dispatch replays the whole
+ * persisted prompt, so an actor would see both and could not know which binds.
+ * The suffix rule rejects a revision appended AFTER the verified block; the
+ * prefix scan rejects one spliced in BEFORE it.
+ *
+ * Both rules are stated against what `buildCallInput` actually composes —
+ * `renderedPrompt + renderPlanSnapshotBlock(text)` — so every honest persisted
+ * input passes BY CONSTRUCTION rather than by luck, including one rendered from
+ * the shipped templates, whose prose quotes the delimiter inline.
+ *
+ * It does NOT establish prompt EXCLUSIVITY, and must not be read as doing so.
+ * Raw plan text appended WITHOUT delimiters is not detectable here: there is no
+ * way to distinguish it from legitimate instruction prose, and pretending
+ * otherwise would republish precisely the kind of unbacked claim this file's
+ * surrounding work exists to delete. What bounds that residue is the trust
+ * model, not this function: plan review is TRUSTED-INPUT-ONLY, and an actor who
+ * can rewrite `state.json` to append a plan can equally rewrite it
+ * self-consistently. This is a fail-closed integrity check on honest state, not
+ * a boundary against an adversary who already owns the state directory.
+ *
+ * ## What is NOT checked, and why
+ *
+ * NOT `absolute_file_paths === []`. That is true of the expanded call
+ * DEFINITION, and there it is load-bearing. It is NOT true of a dispatched
+ * input: the engine composes `absolute_file_paths` from anonymized peer
+ * artifacts (cross-review, chairman) plus `absolute_file_paths_from:
+ * [context_files, context_bundle_files]` — the caller's repo evidence
+ * (`workflows/plan-review-receipts.yaml:124,147,196`). Requiring an empty list
+ * would reject every legitimate cross-review and chairman resume. The honest
+ * file-side invariant is the one the policy already defines: no attached path
+ * may be the original plan or any plan-workspace `PLAN.md`.
+ */
+export function validatePlanReviewPreparedInputPolicy(preparedInputs, bindingsByCall, input = {}) {
+    for (const [callKey, prepared] of preparedInputs) {
+        // Unbound calls are not actors. The only unbound call in a plan-review
+        // definition is `ranking_analysis`, the in-process deterministic reducer —
+        // the exact set the expander declines to inline a snapshot into. D9 governs
+        // what an ACTOR receives; nothing is spawned here.
+        const binding = bindingsByCall.get(callKey);
+        if (binding === undefined) {
+            continue;
+        }
+        if (prepared["cli_name"] !== binding.cli_name) {
+            throw new PlanReviewStageError("execution_contract", `Persisted prepared input provider mismatch for ${callKey}`);
+        }
+        // Fail closed. A caller that cannot supply the verified snapshot cannot
+        // establish D9 for this dispatch, and dispatching anyway would republish a
+        // claim nothing backs.
+        if (input.snapshotText === undefined || input.contextPolicy === undefined) {
+            throw new PlanReviewStageError("execution_contract", `Persisted prepared input for ${callKey} cannot be checked against the ` +
+                "verified plan snapshot and context policy (D9): both are required " +
+                "whenever a bound call replays a persisted prompt");
+        }
+        const prompt = prepared["prompt"];
+        const verifiedBlock = renderPlanSnapshotBlock(input.snapshotText);
+        // POSITIONAL, not merely present. `buildCallInput` composes an actor prompt
+        // as exactly `renderedPrompt + renderPlanSnapshotBlock(text)` and persists
+        // that string (`engine.ts:1906-1908`), so the verified block is the prompt's
+        // SUFFIX by construction — every honest persisted input satisfies this.
+        // Requiring the suffix (rather than `.includes`) is what rejects a second
+        // revision appended AFTER the verified one.
+        if (typeof prompt !== "string" || !prompt.endsWith(verifiedBlock)) {
+            throw new PlanReviewStageError("execution_contract", `Persisted prepared input for ${callKey} does not end with the verified plan ` +
+                "snapshot block (D9). A resumed retry dispatches its persisted prompt verbatim, " +
+                "so a prompt that does not close with the bound snapshot would review a plan " +
+                "this run never verified, or would carry text appended after it.", "schema_mismatch");
+        }
+        // The suffix check alone still admits a SECOND, different revision spliced
+        // in BEFORE the verified block: the actor would receive two candidate plans
+        // and no way to tell which binds. So no block may open anywhere but the
+        // suffix. Scanning only the prefix is deliberate — the verified block's own
+        // body is digest-verified plan text, and a plan that legitimately quotes the
+        // delimiter on its own line must not brick an honest run.
+        const prefix = prompt.slice(0, prompt.length - verifiedBlock.length);
+        const strayBlocks = countSnapshotBlockOpenings(prefix);
+        if (strayBlocks !== 0) {
+            throw new PlanReviewStageError("execution_contract", `Persisted prepared input for ${callKey} opens ${String(strayBlocks)} plan ` +
+                "snapshot block(s) before the verified one; exactly one block, at the end, " +
+                "is permitted (D9). A prompt with a second block would dispatch a plan " +
+                "revision beside the verified one.", "schema_mismatch");
+        }
+        const attached = prepared["absolute_file_paths"];
+        if (attached !== undefined) {
+            if (!Array.isArray(attached)) {
+                throw new PlanReviewStageError("execution_contract", `Persisted prepared input for ${callKey} has a non-array absolute_file_paths`, "schema_mismatch");
+            }
+            for (const path of attached) {
+                if (typeof path !== "string") {
+                    throw new PlanReviewStageError("execution_contract", `Persisted prepared input for ${callKey} has a non-string absolute_file_paths entry`, "schema_mismatch");
+                }
+                if (isExcludedPlanPath(input.contextPolicy, path)) {
+                    throw new PlanReviewStageError("execution_contract", `Persisted prepared input for ${callKey} attaches force-excluded plan path ${path} ` +
+                        "(D9/A-7): the verified snapshot is the only plan text an actor may receive.", "schema_mismatch");
+                }
+            }
+        }
+    }
+}
+//# sourceMappingURL=runtime-policy.js.map

package/clinkx-workflows/dist/plan-review/runtime-policy.js.map

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

package/clinkx-workflows/dist/plan-review/snapshot.d.ts

@@ -0,0 +1,81 @@
+/**
+ * A-6 — immutable plan snapshot discipline.
+ *
+ * The whole point is that `plan_file` is read EXACTLY ONCE, through one
+ * no-follow handle, and never again: every actor (and every resume) is served
+ * the runtime-owned canonical copy. That closes the path/digest TOCTOU — a
+ * swap of `plan_file` after admission cannot change what the reviewers saw,
+ * because nothing re-reads it.
+ */
+/** Run-relative location of the runtime-owned canonical plan snapshot. */
+export declare const PLAN_SNAPSHOT_RELPATH: string;
+export declare const MAX_PLAN_SNAPSHOT_BYTES = 524288;
+/** Run-relative location of the persisted normalized execution contract. */
+export declare const EXECUTION_CONTRACT_RELPATH: string;
+/** Hard cap for both initial serialization and resume reads. */
+export declare const MAX_EXECUTION_CONTRACT_BYTES = 262144;
+export interface ReadCanonicalPlanSnapshotInput {
+    readonly planFile: string;
+    readonly allowedRoots: readonly string[];
+    /** The caller's claimed checkpoint-text-v1 digest, re-verified here. */
+    readonly claimedDigest: string;
+}
+export interface MaterializePlanSnapshotInput extends ReadCanonicalPlanSnapshotInput {
+    readonly runDir: string;
+}
+export interface MaterializedPlanSnapshot {
+    readonly relPath: string;
+    readonly absolutePath: string;
+    /** SHA-256 of the snapshot file bytes (corruption check). */
+    readonly sha256: string;
+    /** checkpoint-text-v1 digest of the canonical bytes (identity). */
+    readonly planDigest: string;
+    readonly bytes: number;
+    /** The canonical snapshot TEXT — what the expander inlines (A-6/D9). */
+    readonly text: string;
+}
+/** The verified canonical plan, held in memory and not yet persisted. */
+export interface CanonicalPlanSnapshot {
+    readonly canonicalBytes: Buffer;
+    readonly planDigest: string;
+    readonly text: string;
+}
+/**
+ * Read `plan_file` EXACTLY ONCE (contained, no-follow, regular-file only),
+ * canonicalize it, and verify the caller's claimed digest — without writing
+ * anything.
+ *
+ * The read is split from the write because the expander now inlines the
+ * snapshot TEXT into every actor's prompt (D9), so the verified text must exist
+ * before the run's definition is composed, while the run directory that holds
+ * the persisted copy cannot exist until the state store creates it. Splitting
+ * keeps `plan_file` read once and keeps the digest verified BEFORE the text is
+ * used for anything.
+ *
+ * Failure classes map to the plan's post-state pre-seat stages:
+ * - containment / symlink / non-regular / unreadable / invalid text → `snapshot`
+ * - canonical digest ≠ claimed digest → `digest`
+ */
+export declare function readCanonicalPlanSnapshot(input: ReadCanonicalPlanSnapshotInput): Promise<CanonicalPlanSnapshot>;
+/** Copy already-verified canonical bytes into the runtime-owned run directory. */
+export declare function persistCanonicalPlanSnapshot(runDir: string, canonical: CanonicalPlanSnapshot): Promise<MaterializedPlanSnapshot>;
+/** Read + verify + persist in one step. The composition callers used before. */
+export declare function materializePlanSnapshot(input: MaterializePlanSnapshotInput): Promise<MaterializedPlanSnapshot>;
+/**
+ * Re-verify the persisted snapshot from run-owned storage alone. Used on resume:
+ * it re-reads the SNAPSHOT (never `plan_file`) through the contained no-follow
+ * reader and recomputes both the file hash and the checkpoint digest.
+ *
+ * Returns the verified snapshot rather than discarding the bytes it already
+ * read. Resume needs the canonical TEXT — it is the only thing a persisted
+ * prepared input's prompt can be checked against (D9), and the check must run
+ * before any provider exists. Returning it here keeps the snapshot read ONCE:
+ * re-reading it at the validation seam would reopen a D9-class TOCTOU between
+ * verification and use.
+ */
+export declare function verifyPersistedPlanSnapshot(runDir: string, relPath: string, expectedSha256: string, expectedPlanDigest: string): Promise<CanonicalPlanSnapshot>;
+/** Persist the normalized execution contract into runtime-owned storage. */
+export declare function writeExecutionContractSnapshot(runDir: string, contract: unknown): Promise<{
+    relPath: string;
+    sha256: string;
+}>;

package/clinkx-workflows/dist/plan-review/snapshot.js

@@ -0,0 +1,170 @@
+/**
+ * A-6 — immutable plan snapshot discipline.
+ *
+ * The whole point is that `plan_file` is read EXACTLY ONCE, through one
+ * no-follow handle, and never again: every actor (and every resume) is served
+ * the runtime-owned canonical copy. That closes the path/digest TOCTOU — a
+ * swap of `plan_file` after admission cannot change what the reviewers saw,
+ * because nothing re-reads it.
+ */
+import { createHash } from "node:crypto";
+import { mkdir, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { ContainedFilePolicyError, readContainedAbsoluteFile, readContainedRelativeFile, } from "../contained-file.js";
+import { CheckpointTextError, computeCheckpointDigest } from "./digest.js";
+import { PlanReviewStageError } from "./stage-error.js";
+/** Run-relative location of the runtime-owned canonical plan snapshot. */
+export const PLAN_SNAPSHOT_RELPATH = join("plan-review", "plan.snapshot.md");
+export const MAX_PLAN_SNAPSHOT_BYTES = 524_288;
+/** Run-relative location of the persisted normalized execution contract. */
+export const EXECUTION_CONTRACT_RELPATH = join("plan-review", "execution-contract.json");
+/** Hard cap for both initial serialization and resume reads. */
+export const MAX_EXECUTION_CONTRACT_BYTES = 262_144;
+function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+/**
+ * The generic containment error names allowed roots without saying WHICH roots,
+ * which reads as `CLINKX_ALLOWED_ROOTS` — but plan_file is bound to the
+ * workflows workspace root alone. Name the root that actually applies.
+ *
+ * Only allowed-roots rejections get the hint; a symlink/non-regular rejection
+ * from the same error class is not a roots problem. Gated on the STRUCTURED
+ * `reason` discriminator rather than message wording: substring-matching the
+ * message coupled this hint to prose that is free to be reworded, and would
+ * false-positive on any path whose own name happens to contain the phrase.
+ */
+function planRootHint(err) {
+    if (err.reason !== "outside_allowed_roots")
+        return "";
+    return (" — plan_file must live under the workflows workspace root" +
+        " (CLINKX_WORKFLOWS_WORKSPACE_ROOT, defaulting to the server's process.cwd())." +
+        " CLINKX_ALLOWED_ROOTS is NOT consulted for plan_file and cannot widen plan-source admission.");
+}
+/**
+ * Read `plan_file` EXACTLY ONCE (contained, no-follow, regular-file only),
+ * canonicalize it, and verify the caller's claimed digest — without writing
+ * anything.
+ *
+ * The read is split from the write because the expander now inlines the
+ * snapshot TEXT into every actor's prompt (D9), so the verified text must exist
+ * before the run's definition is composed, while the run directory that holds
+ * the persisted copy cannot exist until the state store creates it. Splitting
+ * keeps `plan_file` read once and keeps the digest verified BEFORE the text is
+ * used for anything.
+ *
+ * Failure classes map to the plan's post-state pre-seat stages:
+ * - containment / symlink / non-regular / unreadable / invalid text → `snapshot`
+ * - canonical digest ≠ claimed digest → `digest`
+ */
+export async function readCanonicalPlanSnapshot(input) {
+    let raw;
+    try {
+        const read = await readContainedAbsoluteFile(input.allowedRoots, input.planFile, { wantBytes: true, requireRegular: true, maxBytes: MAX_PLAN_SNAPSHOT_BYTES });
+        raw = read.bytes;
+    }
+    catch (err) {
+        if (err instanceof ContainedFilePolicyError) {
+            throw new PlanReviewStageError("snapshot", `${err.message}${planRootHint(err)}`, "invalid_output");
+        }
+        throw new PlanReviewStageError("snapshot", `plan_file could not be read: ${err instanceof Error ? err.message : String(err)}`, "no_artifact");
+    }
+    let canonical;
+    let planDigest;
+    try {
+        const computed = computeCheckpointDigest(raw);
+        canonical = computed.canonicalBytes;
+        planDigest = computed.digest;
+    }
+    catch (err) {
+        if (err instanceof CheckpointTextError) {
+            throw new PlanReviewStageError("snapshot", `plan_file is not valid checkpoint-text-v1 input: ${err.message}`, "invalid_output");
+        }
+        throw err;
+    }
+    // checkpoint-text-v1 appends a final LF when absent. Bound the canonical
+    // bytes that are persisted and resumed, not merely the raw source bytes.
+    if (canonical.byteLength > MAX_PLAN_SNAPSHOT_BYTES) {
+        throw new PlanReviewStageError("snapshot", `canonical plan snapshot exceeds ${String(MAX_PLAN_SNAPSHOT_BYTES)} bytes`, "invalid_output");
+    }
+    if (planDigest !== input.claimedDigest) {
+        throw new PlanReviewStageError("digest", `plan_file digest ${planDigest} does not match the bound plan_review.digest ${input.claimedDigest}`, "schema_mismatch");
+    }
+    return { canonicalBytes: canonical, planDigest, text: canonical.toString("utf-8") };
+}
+/** Copy already-verified canonical bytes into the runtime-owned run directory. */
+export async function persistCanonicalPlanSnapshot(runDir, canonical) {
+    const absolutePath = join(runDir, PLAN_SNAPSHOT_RELPATH);
+    await mkdir(dirname(absolutePath), { recursive: true });
+    // `wx` — the snapshot is written exactly once per run and never overwritten.
+    await writeFile(absolutePath, canonical.canonicalBytes, { flag: "wx" });
+    return {
+        relPath: PLAN_SNAPSHOT_RELPATH,
+        absolutePath,
+        sha256: sha256Hex(canonical.canonicalBytes),
+        planDigest: canonical.planDigest,
+        bytes: canonical.canonicalBytes.byteLength,
+        text: canonical.text,
+    };
+}
+/** Read + verify + persist in one step. The composition callers used before. */
+export async function materializePlanSnapshot(input) {
+    return await persistCanonicalPlanSnapshot(input.runDir, await readCanonicalPlanSnapshot(input));
+}
+/**
+ * Re-verify the persisted snapshot from run-owned storage alone. Used on resume:
+ * it re-reads the SNAPSHOT (never `plan_file`) through the contained no-follow
+ * reader and recomputes both the file hash and the checkpoint digest.
+ *
+ * Returns the verified snapshot rather than discarding the bytes it already
+ * read. Resume needs the canonical TEXT — it is the only thing a persisted
+ * prepared input's prompt can be checked against (D9), and the check must run
+ * before any provider exists. Returning it here keeps the snapshot read ONCE:
+ * re-reading it at the validation seam would reopen a D9-class TOCTOU between
+ * verification and use.
+ */
+export async function verifyPersistedPlanSnapshot(runDir, relPath, expectedSha256, expectedPlanDigest) {
+    let bytes;
+    try {
+        const read = await readContainedRelativeFile(runDir, relPath, {
+            wantBytes: true,
+            requireRegular: true,
+            maxBytes: MAX_PLAN_SNAPSHOT_BYTES,
+        });
+        bytes = read.bytes;
+    }
+    catch (err) {
+        throw new PlanReviewStageError("snapshot", `Persisted plan snapshot at ${relPath} is unreadable: ${err instanceof Error ? err.message : String(err)}`, err instanceof ContainedFilePolicyError ? "invalid_output" : "no_artifact");
+    }
+    if (sha256Hex(bytes) !== expectedSha256) {
+        throw new PlanReviewStageError("snapshot", `Persisted plan snapshot at ${relPath} failed its hash check`, "schema_mismatch");
+    }
+    // Recompute the checkpoint digest from the persisted bytes rather than trust
+    // the recorded value: the snapshot must still BE the bound plan revision.
+    let canonicalBytes;
+    let planDigest;
+    try {
+        const computed = computeCheckpointDigest(bytes);
+        canonicalBytes = computed.canonicalBytes;
+        planDigest = computed.digest;
+    }
+    catch (err) {
+        throw new PlanReviewStageError("snapshot", `Persisted plan snapshot at ${relPath} is not canonical checkpoint text: ${err instanceof Error ? err.message : String(err)}`, "invalid_output");
+    }
+    if (planDigest !== expectedPlanDigest) {
+        throw new PlanReviewStageError("digest", `Persisted plan snapshot digest ${planDigest} does not match the bound digest ${expectedPlanDigest}`, "schema_mismatch");
+    }
+    return { canonicalBytes, planDigest, text: canonicalBytes.toString("utf-8") };
+}
+/** Persist the normalized execution contract into runtime-owned storage. */
+export async function writeExecutionContractSnapshot(runDir, contract) {
+    const absolutePath = join(runDir, EXECUTION_CONTRACT_RELPATH);
+    const bytes = Buffer.from(`${JSON.stringify(contract, null, 2)}\n`, "utf-8");
+    if (bytes.byteLength > MAX_EXECUTION_CONTRACT_BYTES) {
+        throw new PlanReviewStageError("execution_contract", `serialized execution contract exceeds ${String(MAX_EXECUTION_CONTRACT_BYTES)} bytes`, "invalid_output");
+    }
+    await mkdir(dirname(absolutePath), { recursive: true });
+    await writeFile(absolutePath, bytes, { flag: "wx" });
+    return { relPath: EXECUTION_CONTRACT_RELPATH, sha256: sha256Hex(bytes) };
+}
+//# sourceMappingURL=snapshot.js.map

package/clinkx-workflows/dist/plan-review/snapshot.js.map

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

package/clinkx-workflows/dist/plan-review/stage-error.d.ts

@@ -0,0 +1,19 @@
+import type { z } from "zod";
+import type { PlanReviewErrorReasonSchema } from "./contract.js";
+import type { CouncilPlanReviewErrorSchema } from "./publication.js";
+export type PlanReviewErrorStage = z.infer<typeof CouncilPlanReviewErrorSchema>["stage"];
+export type PlanReviewErrorReason = z.infer<typeof PlanReviewErrorReasonSchema>;
+/**
+ * A post-state, pre-seat plan-review failure.
+ *
+ * `stage` — NOT `reason` — is what disambiguates which check failed, because the
+ * seat `error.reason` enum has no dedicated snapshot/digest member (see the
+ * plan's §Error surface). Carrying the stage on the throw is what lets the
+ * caller record `RunState.status=failed` and later surface a bounded
+ * `council-plan-review-error-v1` inline; it is never a result sidecar.
+ */
+export declare class PlanReviewStageError extends Error {
+    readonly stage: PlanReviewErrorStage;
+    readonly reason: PlanReviewErrorReason;
+    constructor(stage: PlanReviewErrorStage, message: string, reason?: PlanReviewErrorReason);
+}

package/clinkx-workflows/dist/plan-review/stage-error.js

@@ -0,0 +1,20 @@
+/**
+ * A post-state, pre-seat plan-review failure.
+ *
+ * `stage` — NOT `reason` — is what disambiguates which check failed, because the
+ * seat `error.reason` enum has no dedicated snapshot/digest member (see the
+ * plan's §Error surface). Carrying the stage on the throw is what lets the
+ * caller record `RunState.status=failed` and later surface a bounded
+ * `council-plan-review-error-v1` inline; it is never a result sidecar.
+ */
+export class PlanReviewStageError extends Error {
+    stage;
+    reason;
+    constructor(stage, message, reason = "internal_error") {
+        super(message);
+        this.name = "PlanReviewStageError";
+        this.stage = stage;
+        this.reason = reason;
+    }
+}
+//# sourceMappingURL=stage-error.js.map

package/clinkx-workflows/dist/plan-review/stage-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stage-error.js","sourceRoot":"","sources":["../../src/plan-review/stage-error.ts"],"names":[],"mappings":"AAUA;;;;;;;;GAQG;AACH,MAAM,OAAO,oBAAqB,SAAQ,KAAK;IACpC,KAAK,CAAuB;IAC5B,MAAM,CAAwB;IAEvC,YACE,KAA2B,EAC3B,OAAe,EACf,SAAgC,gBAAgB;QAEhD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAC;QACnC,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;CACF"}

package/clinkx-workflows/dist/post-processors/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Post-processor registry for deterministic transforms applied to a validated
+ * call output BEFORE it is persisted as an artifact.
+ *
+ * A call opts in via `post_processor: <name>` in its workflow definition. The
+ * engine looks the name up here after JSON validation; if found, the returned
+ * value replaces `validated` before the artifact is written. Unknown names fail
+ * fast: the loader's static validation (`validatePostProcessors`) throws at
+ * workflow load time, and the engine also throws as defense-in-depth if an
+ * unregistered name ever reaches execution.
+ */
+/** Inputs available to a post-processor. */
+export type PostProcessorContext = {
+    allowlist: Set<string>;
+    schemaId: string;
+};
+/** A post-processor transforms a validated artifact value deterministically. */
+export type PostProcessorFn = (validated: unknown, ctx: PostProcessorContext) => unknown;
+export declare function getPostProcessor(id: string): PostProcessorFn | undefined;
+export declare function registerPostProcessor(id: string, fn: PostProcessorFn): void;

package/clinkx-workflows/dist/post-processors/index.js

@@ -0,0 +1,21 @@
+/**
+ * Post-processor registry for deterministic transforms applied to a validated
+ * call output BEFORE it is persisted as an artifact.
+ *
+ * A call opts in via `post_processor: <name>` in its workflow definition. The
+ * engine looks the name up here after JSON validation; if found, the returned
+ * value replaces `validated` before the artifact is written. Unknown names fail
+ * fast: the loader's static validation (`validatePostProcessors`) throws at
+ * workflow load time, and the engine also throws as defense-in-depth if an
+ * unregistered name ever reaches execution.
+ */
+import { citationCheck } from "../citation-check.js";
+const registry = new Map();
+registry.set("citation_check", citationCheck);
+export function getPostProcessor(id) {
+    return registry.get(id);
+}
+export function registerPostProcessor(id, fn) {
+    registry.set(id, fn);
+}
+//# sourceMappingURL=index.js.map

package/clinkx-workflows/dist/post-processors/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/post-processors/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAWrD,MAAM,QAAQ,GAAG,IAAI,GAAG,EAA2B,CAAC;AACpD,QAAQ,CAAC,GAAG,CAAC,gBAAgB,EAAE,aAAa,CAAC,CAAC;AAE9C,MAAM,UAAU,gBAAgB,CAAC,EAAU;IACzC,OAAO,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AAC1B,CAAC;AAED,MAAM,UAAU,qBAAqB,CAAC,EAAU,EAAE,EAAmB;IACnE,QAAQ,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC;AACvB,CAAC"}

package/clinkx-workflows/dist/prompt-budget.d.ts

@@ -26,6 +26,13 @@ export interface PromptBudgetInput {
     readonly reserveBytes?: number | undefined;
     readonly maxBytes?: number | undefined;
 }
+/**
+ * Reserve margin for child-side prompt assembly overhead, applied to every
+ * dispatched call whose caller supplies no explicit `reserveBytes` (nothing
+ * currently does). Exported so a pre-dispatch guard can DERIVE the same reserve
+ * the engine will actually bill rather than re-literal it and drift.
+ */
+export declare const DEFAULT_RESERVE_BYTES = 100000;
 export declare function estimatePromptBudget(input: PromptBudgetInput): PromptBudgetEstimate;
 export declare function createPathContributor(label: string, path: string, kind: "context" | "file" | "image"): PromptBudgetContributor;
 export declare function enforcePromptBudget(estimate: PromptBudgetEstimate): void;

package/clinkx-workflows/dist/prompt-budget.js

@@ -8,7 +8,13 @@
 import { statSync } from "node:fs";
 import { getMaxPromptBytes } from "./config.js";
 import { WorkflowError } from "./errors.js";
-const DEFAULT_RESERVE_BYTES = 100_000;
+/**
+ * Reserve margin for child-side prompt assembly overhead, applied to every
+ * dispatched call whose caller supplies no explicit `reserveBytes` (nothing
+ * currently does). Exported so a pre-dispatch guard can DERIVE the same reserve
+ * the engine will actually bill rather than re-literal it and drift.
+ */
+export const DEFAULT_RESERVE_BYTES = 100_000;
 export function estimatePromptBudget(input) {
     const contributors = [
         {

package/clinkx-workflows/dist/prompt-budget.js.map

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

package/clinkx-workflows/dist/reducers/index.js

@@ -3,9 +3,11 @@
  *
  * Reducers run in place of LLM calls when a call specifies a `reducer` ID.
  */
+import { planReviewRankingReducer } from "../plan-review/ranking-reducer.js";
 import { councilRankingReducer } from "../ranking-reducer.js";
 const registry = new Map();
 registry.set("council_ranking_v1", councilRankingReducer);
+registry.set("plan_review_ranking_v1", planReviewRankingReducer);
 export function getReducer(id) {
     return registry.get(id);
 }

package/clinkx-workflows/dist/reducers/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/reducers/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAI9D,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAqB,CAAC;AAC9C,QAAQ,CAAC,GAAG,CAAC,oBAAoB,EAAE,qBAAqB,CAAC,CAAC;AAE1D,MAAM,UAAU,UAAU,CAAC,EAAU;IACnC,OAAO,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AAC1B,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/reducers/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAGH,OAAO,EAAE,wBAAwB,EAAE,MAAM,mCAAmC,CAAC;AAC7E,OAAO,EAAE,qBAAqB,EAAE,MAAM,uBAAuB,CAAC;AAI9D,MAAM,QAAQ,GAAG,IAAI,GAAG,EAAqB,CAAC;AAC9C,QAAQ,CAAC,GAAG,CAAC,oBAAoB,EAAE,qBAAqB,CAAC,CAAC;AAC1D,QAAQ,CAAC,GAAG,CAAC,wBAAwB,EAAE,wBAAwB,CAAC,CAAC;AAEjE,MAAM,UAAU,UAAU,CAAC,EAAU;IACnC,OAAO,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;AAC1B,CAAC"}

package/clinkx-workflows/dist/run-lock-heartbeat.d.ts

@@ -0,0 +1,2 @@
+/** Reader/producer floor for run.lock heartbeat staleness (10 s cadence × 6). */
+export declare const RUN_LOCK_HEARTBEAT_STALE_FLOOR_MS = 60000;

package/clinkx-workflows/dist/run-lock-heartbeat.js

@@ -0,0 +1,3 @@
+/** Reader/producer floor for run.lock heartbeat staleness (10 s cadence × 6). */
+export const RUN_LOCK_HEARTBEAT_STALE_FLOOR_MS = 60_000;
+//# sourceMappingURL=run-lock-heartbeat.js.map

package/clinkx-workflows/dist/run-lock-heartbeat.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-lock-heartbeat.js","sourceRoot":"","sources":["../src/run-lock-heartbeat.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,MAAM,CAAC,MAAM,iCAAiC,GAAG,MAAM,CAAC"}