clinkx 0.3.0 → 1.0.0

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

@@ -0,0 +1,243 @@
+import { WorkflowError } from "../errors.js";
+import { CouncilPlanReviewExecutionContractSchema, } from "./execution-contract.js";
+const STAGE_IDS = [
+    "reviewers",
+    "cross_review",
+    "ranking_analysis",
+    "chairman",
+];
+/**
+ * Delimits the inlined snapshot. Long and fixed on purpose: the plan is
+ * untrusted text that may itself contain markdown fences, and an actor must be
+ * able to tell where the bound revision ends and its instructions resume.
+ */
+export const PLAN_SNAPSHOT_BEGIN = "-----BEGIN PLAN SNAPSHOT-----";
+export const PLAN_SNAPSHOT_END = "-----END PLAN SNAPSHOT-----";
+/**
+ * The exact snapshot block appended to every actor's prompt.
+ *
+ * Exported because it is the only thing a PERSISTED prepared input can be
+ * checked against on resume (D9). A resumed retry replays its persisted prompt
+ * verbatim — the expander never runs again for it — so the resume seam must
+ * re-derive these exact bytes and require them to be present. Two renderings
+ * would let the check pass against text no actor was ever sent.
+ *
+ * The result is appended by the ENGINE, after `renderCallPrompt` — never
+ * concatenated into a call's `prompt` template. See
+ * `NormalizedCall.plan_review_snapshot_text`: the plan is untrusted text that
+ * may contain `{{...}}`, and the renderer would rewrite or reject it.
+ */
+export function renderPlanSnapshotBlock(planSnapshotText) {
+    return `\n\n## Plan snapshot (the bound revision under review)\n${PLAN_SNAPSHOT_BEGIN}\n${planSnapshotText}\n${PLAN_SNAPSHOT_END}`;
+}
+const NON_SEMANTIC_REVIEW_FIELDS = new Set([
+    "schema_version",
+    "workspace_schema",
+    "digest_profile",
+    "repository_id",
+    "review_id",
+    "iteration",
+    "plan_id",
+    "revision",
+    "digest",
+    "seat_id",
+    "reviewer",
+    "cli_name",
+    "internal_call_id",
+    "cross_review_call_id",
+]);
+/** Remove plan/seat/provider bindings before a peer artifact is cross-reviewed. */
+export function projectPlanReviewSemanticBody(value) {
+    if (value == null || typeof value !== "object")
+        return value;
+    if (Array.isArray(value)) {
+        return value.map((item) => projectPlanReviewSemanticBody(item));
+    }
+    const projected = {};
+    for (const [key, child] of Object.entries(value)) {
+        if (!NON_SEMANTIC_REVIEW_FIELDS.has(key)) {
+            projected[key] = projectPlanReviewSemanticBody(child);
+        }
+    }
+    return projected;
+}
+function requireSeedStage(definition, id) {
+    const stage = definition.stages.find((candidate) => candidate.id === id);
+    if (stage === undefined) {
+        throw new WorkflowError(`Plan-review expander: missing stage "${id}"`);
+    }
+    if (stage.calls.length !== 1) {
+        throw new WorkflowError(`Plan-review expander: stage "${id}" must contain exactly one seed call`);
+    }
+    return stage;
+}
+function copyStage(stage, calls, policy) {
+    return {
+        id: stage.id,
+        ...(stage.description !== undefined ? { description: stage.description } : {}),
+        parallel: policy?.parallel ?? stage.parallel,
+        retry: stage.retry,
+        on_failure: policy?.on_failure ?? stage.on_failure,
+        calls,
+    };
+}
+/**
+ * A RUNTIME shape check on the snapshot — deliberately not "belt and braces".
+ *
+ * Neither package typechecks its tests (both tsconfigs are `include: ["src"]`,
+ * and vitest transpiles without checking), so the parameter's type alone is
+ * IDE-only theater: a test could hand this function a pathname forever and the
+ * gate would stay green. That is not hypothetical — four test sites did exactly
+ * that. The type documents the contract for a reader; this guard is what makes
+ * a violation FAIL under `npm test`.
+ */
+function assertVerifiedSnapshot(snapshot) {
+    if (snapshot === undefined)
+        return;
+    if (typeof snapshot !== "object" || snapshot === null ||
+        typeof snapshot.text !== "string" || snapshot.text.length === 0) {
+        throw new WorkflowError("Plan-review expander: planSnapshot must be a verified CanonicalPlanSnapshot " +
+            "with non-empty `text` (A-6/D9). A pathname or bare string is not a snapshot: " +
+            "the expander inlines the plan TEXT and never reads a file.");
+    }
+    if (!/^[0-9a-f]{64}$/.test(snapshot.planDigest)) {
+        throw new WorkflowError("Plan-review expander: planSnapshot.planDigest must be a 64-hex checkpoint-text-v1 " +
+            "digest — the snapshot must come from the verified read, never reconstructed.");
+    }
+}
+function reviewerPrompt(prompt, seat) {
+    return `${prompt}\n\n## Bound review seat\nseat_id: ${seat.seat_id}\nreviewer: ${seat.reviewer}\nstance: ${seat.stance}`;
+}
+/**
+ * Expand the isolated four-stage plan-review seed. Existing council expansion
+ * is intentionally not reused or mutated.
+ */
+export function expandCouncilPlanReview(definition, contractInput, 
+/**
+ * The verified canonical plan snapshot (A-6/D9), inlined into every actor's
+ * prompt. Inlining TEXT rather than naming a path is what keeps D9 true now
+ * that actors run adapter-default: a path is a mutable thing an actor could
+ * re-read (or re-write) after verification, whereas the prompt bytes are
+ * fixed at dispatch.
+ *
+ * This takes the verified `CanonicalPlanSnapshot` rather than a bare `string`
+ * ON PURPOSE. A bare string accepts a PATHNAME just as happily as plan text,
+ * and a pathname would inline the path — reintroducing exactly the mutable
+ * indirection D9 exists to remove — while every existing test still passed,
+ * because none asserted on the rendered prompt. The nominal type makes that
+ * mistake unrepresentable for a reader; `assertVerifiedSnapshot` below makes
+ * it fail for the test suite.
+ */
+planSnapshot) {
+    assertVerifiedSnapshot(planSnapshot);
+    if (definition.name !== "plan-review-receipts") {
+        throw new WorkflowError(`Plan-review expander cannot expand workflow "${definition.name}"`);
+    }
+    if (definition.stages.length !== STAGE_IDS.length ||
+        definition.stages.some((stage, index) => stage.id !== STAGE_IDS[index])) {
+        throw new WorkflowError(`Plan-review expander requires stages in order: ${STAGE_IDS.join(", ")}`);
+    }
+    const contract = CouncilPlanReviewExecutionContractSchema.parse(contractInput);
+    const reviewersSeed = requireSeedStage(definition, "reviewers");
+    const crossReviewSeed = requireSeedStage(definition, "cross_review");
+    const rankingSeed = requireSeedStage(definition, "ranking_analysis");
+    const chairmanSeed = requireSeedStage(definition, "chairman");
+    const reviewerBlueprint = reviewersSeed.calls[0];
+    const crossReviewBlueprint = crossReviewSeed.calls[0];
+    const rankingCall = rankingSeed.calls[0];
+    const chairmanBlueprint = chairmanSeed.calls[0];
+    if (rankingCall.reducer === undefined) {
+        throw new WorkflowError("Plan-review expander: ranking_analysis must use a deterministic reducer");
+    }
+    /**
+     * A-6/D9: the verified snapshot is the ONLY plan text an actor receives.
+     *
+     * `absolute_file_paths: []` is SET, not merged, and that is the load-bearing
+     * half of this function. A seed blueprint that named the original plan would
+     * otherwise be re-admitted here and hand actors a MUTABLE plan alongside the
+     * inlined snapshot — silently retracting the exact decision the inlining
+     * exists to preserve. Emptying the list is what makes the snapshot the only
+     * plan text, now that it no longer occupies the file slot itself.
+     *
+     * The snapshot is attached as `plan_review_snapshot_text` DATA and is
+     * deliberately NOT concatenated into `prompt`. `prompt` is a template the
+     * engine renders; a plan is untrusted text that may contain `{{...}}`, so
+     * splicing it in would let the renderer rewrite the verified bytes (D9
+     * violation) or throw on a legitimate plan. The engine appends the block
+     * after rendering, so the actor gets the snapshot verbatim. Both halves are
+     * set together here, keeping "this call is an actor" ONE decision made in ONE
+     * place.
+     *
+     * ## On-disk footprint: duplicated per actor, and that is NOT new
+     *
+     * State this honestly, because it is easy to get backwards. The snapshot text
+     * IS copied into every actor call, and the whole normalized definition IS
+     * persisted — `WorkflowStateStore.create` writes it to `workflow.snapshot.json`
+     * and `resume` reads it back hash-verified (`state.ts:696-700,803-808`). So at
+     * a 6-seat roster with a 512 KiB plan this is ~6.6 MB on disk. It is NOT the
+     * case that "the definition is not persisted".
+     *
+     * This is nonetheless not a regression: the previous design spliced the same
+     * snapshot bytes into each `call.prompt`, which lands in the same persisted
+     * definition. The footprint is BYTE-IDENTICAL — the bytes moved fields, not
+     * volume. That, and only that, is the justification for accepting it here.
+     */
+    const withSnapshotText = (call) => planSnapshot === undefined
+        ? call
+        : {
+            ...call,
+            absolute_file_paths: [],
+            plan_review_snapshot_text: planSnapshot.text,
+        };
+    const reviewerCalls = contract.seats.map((seat) => withSnapshotText({
+        ...reviewerBlueprint,
+        id: seat.internal_call_id,
+        cli_name: seat.cli_name,
+        prompt: reviewerPrompt(reviewerBlueprint.prompt, seat),
+    }));
+    const globalAliases = Object.fromEntries(contract.seats.map((seat, index) => [
+        `reviewers.${seat.internal_call_id}`,
+        `candidate_${String(index).padStart(3, "0")}`,
+    ]));
+    const crossReviewCalls = contract.seats.map((seat) => {
+        if (seat.cross_review_call_id === undefined) {
+            throw new WorkflowError(`Plan-review expander: seat "${seat.seat_id}" has no cross-review call mapping`);
+        }
+        return withSnapshotText({
+            ...crossReviewBlueprint,
+            id: seat.cross_review_call_id,
+            cli_name: seat.cli_name,
+            context_from: contract.seats
+                .filter((peer) => peer.seat_id !== seat.seat_id)
+                .map((peer) => `reviewers.${peer.internal_call_id}`),
+            anonymize_context: true,
+            plan_review_semantic_context: true,
+            plan_review_anonymous_aliases: Object.fromEntries(Object.entries(globalAliases).filter(([reference]) => reference !== `reviewers.${seat.internal_call_id}`)),
+        });
+    });
+    const chairmanSeat = contract.seats.find((seat) => seat.seat_id === contract.chairman_seat);
+    const chairmanCall = withSnapshotText({
+        ...chairmanBlueprint,
+        cli_name: chairmanSeat.cli_name,
+    });
+    return {
+        name: definition.name,
+        description: definition.description,
+        version: definition.version,
+        variables: definition.variables,
+        settings: definition.settings,
+        stages: [
+            copyStage(reviewersSeed, reviewerCalls, {
+                parallel: true,
+                on_failure: "continue",
+            }),
+            copyStage(crossReviewSeed, crossReviewCalls, {
+                parallel: true,
+                on_failure: "continue",
+            }),
+            copyStage(rankingSeed, [rankingCall]),
+            copyStage(chairmanSeed, [chairmanCall]),
+        ],
+    };
+}
+//# sourceMappingURL=expander.js.map

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

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

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

@@ -0,0 +1,126 @@
+/**
+ * C-2/C-3 — the deterministic plan-review projector.
+ *
+ * This module answers exactly one question: given what a run DURABLY persisted,
+ * what `council-plan-review-result-v1` envelope does that run project? It never
+ * decides approval, never repairs a receipt, and never invents a seat.
+ *
+ * The split is load-bearing:
+ *
+ *   - {@link projectCouncilPlanReviewResult} is PURE. It takes observations and
+ *     returns an envelope. No filesystem, no clock, no adapter registry. Every
+ *     projection rule (roster order, trusted identity, complete-vs-partial, the
+ *     1 MiB ceiling) is testable without touching disk.
+ *   - {@link projectPlanReviewRun} is the bounded I/O adapter. It is the ONLY
+ *     part that reads, and it reads exclusively through the shared C-1
+ *     no-follow contained reader with a byte ceiling.
+ *
+ * Three invariants the shape enforces rather than documents:
+ *
+ * 1. IDENTITY IS NEVER MODEL-SOURCED. A seat's `seat_id`/`reviewer`/`cli_name`
+ *    and every receipt binding come from the normalized execution contract and
+ *    the persisted mappings. The model contributes only the six semantic fields
+ *    that `PlanReviewReviewerBodySchema` admits; because that schema is
+ *    non-strict, an echoed `seat_id`/`digest` is dropped before assembly and
+ *    cannot reach a candidate.
+ * 2. UNREADABLE IS NOT UNTRUE, AND NEITHER IS FABRICATED. Containment, symlink,
+ *    size, parse, schema, duplicate, and absence failures all project the seat
+ *    as `missing`/`failed` with a reason. There is no code path from "the
+ *    artifact was bad" to "here is a receipt".
+ * 3. DISPATCH IS NOT VALIDITY. `attemptsConsumed >= 1` is the durable witness
+ *    that a reviewer was ever dispatched, and it decides ONLY publication
+ *    eligibility ({@link isPlanReviewPublicationEligible}). It is structurally
+ *    unavailable to the projection core, which never sees a `CallStateEntry`.
+ */
+import { type CouncilPlanReviewResult } from "./contract.js";
+import { type CouncilPlanReviewExecutionContract } from "./execution-contract.js";
+import { type PlanReviewErrorReason } from "./stage-error.js";
+import type { RunState } from "../state-schema.js";
+/**
+ * What a run persisted about one seat. `body` is the RAW parsed artifact — the
+ * core, not the reader, decides whether it is a usable candidate, so a reader
+ * bug cannot promote junk to `completed`.
+ */
+export type PlanReviewSeatOutcome = {
+    readonly kind: "artifact";
+    readonly body: unknown;
+} | {
+    readonly kind: "failed";
+    readonly reason: PlanReviewErrorReason;
+    readonly detail?: string | undefined;
+} | {
+    readonly kind: "missing";
+    readonly reason: PlanReviewErrorReason;
+    readonly detail?: string | undefined;
+};
+export interface PlanReviewSeatObservation {
+    readonly seat_id: string;
+    readonly outcome: PlanReviewSeatOutcome;
+}
+export type PlanReviewChairmanObservation = {
+    readonly kind: "artifact";
+    readonly body: unknown;
+} | {
+    readonly kind: "failed";
+} | {
+    readonly kind: "skipped";
+};
+export interface PlanReviewProjectionInput {
+    /** The normalized, digest-bound roster and bindings. The sole identity source. */
+    readonly contract: CouncilPlanReviewExecutionContract;
+    /**
+     * The identity the caller believes it is projecting. Asserted, not trusted:
+     * the core recomputes the P0-4 digest from `contract` and refuses to stamp an
+     * envelope whose digest the contract does not actually produce.
+     */
+    readonly execution_contract_digest: string;
+    readonly seats: readonly PlanReviewSeatObservation[];
+    readonly chairman: PlanReviewChairmanObservation;
+}
+/**
+ * Project the envelope from observations alone.
+ *
+ * Deterministic by construction: output depends only on `input`, and seat order
+ * is the contract's roster order — never observation arrival order. An
+ * observation for a seat outside the roster cannot appear in the output because
+ * the roster, not the observation list, drives iteration.
+ *
+ * @throws PlanReviewStageError on a digest that is not the contract identity, or
+ *   an envelope that fails its own compiled contract (including the 1 MiB
+ *   ceiling). Oversize is an explicit error — never truncation.
+ */
+export declare function projectCouncilPlanReviewResult(input: PlanReviewProjectionInput): CouncilPlanReviewResult;
+/**
+ * Whether this run ever dispatched a reviewer, and therefore owes a result
+ * sidecar (C-5 eligibility).
+ *
+ * Reads ONLY the durable `attemptsConsumed` witness, never the call's current
+ * state: a run that dispatched three seats and then had every one of them fail,
+ * time out, or be cancelled still owes an envelope reporting exactly that. The
+ * inverse — treating this witness as evidence a candidate exists — is precisely
+ * the fabrication this module forbids, which is why the projection core takes
+ * observations and cannot see a `CallStateEntry` at all.
+ */
+export declare function isPlanReviewPublicationEligible(state: RunState): boolean;
+export interface PlanReviewProjectionSource {
+    /** The run directory. Every read is contained to it. */
+    readonly runDir: string;
+    /** Final persisted state. The adapter reads it; it never writes. */
+    readonly state: RunState;
+    /** The restored, hash-verified contract (see `resume.ts`). */
+    readonly contract: CouncilPlanReviewExecutionContract;
+    /** The digest recomputed from that contract. */
+    readonly execution_contract_digest: string;
+}
+/**
+ * Project a run's envelope from its persisted state and artifacts.
+ *
+ * The contract is threaded in already-restored (`resume.ts` owns decode +
+ * hash-verify + recompute) but is NOT taken on faith: it must be the identity
+ * the run persisted, and its roster must agree with the persisted mappings.
+ * Otherwise this would happily project a run under a contract it never ran.
+ *
+ * @throws PlanReviewStageError when the persisted subtree is absent/corrupt, the
+ *   contract is not the persisted identity, or the projection itself fails.
+ */
+export declare function projectPlanReviewRun(source: PlanReviewProjectionSource): Promise<CouncilPlanReviewResult>;