prismatica 0.2.0

package/dist/assurance/outcome.js

@@ -0,0 +1,165 @@
+/**
+ * The ONE assessment of "is there current, affirmative proof for THIS diff?".
+ *
+ * Before this module the question was re-derived in six places and answered
+ * differently in each: `gate.ts` read `state` and the patch-id but never the
+ * verdict, `accept.ts` read `state` alone, `atlas/next.ts` collapsed approve and
+ * request_changes into one `sealed-current`, `board/model.ts` derived
+ * "changes requested" from the DECISION record only, and `ship --verify` /
+ * `assurance/mainpush.ts` each rebuilt their own variant. A `request_changes`
+ * review therefore passed the gate — a signed Flow record asserting the
+ * opposite ("the change is not ready to accept") was contradicting the code.
+ *
+ * PURE by construction: no filesystem, no git, no config loading. Callers
+ * already read the records and (where they can) compute the patch-id; they hand
+ * both in and render whatever comes back. That is what stops a fifth surface
+ * from growing a sixth opinion.
+ *
+ * Fail closed everywhere. "Sealed" is not "approved": only an EXPLICIT
+ * `verdict: approve` progresses. A sealed review with no verdict at all —
+ * possible, since `ReviewSchema.verdict` is optional so records written before
+ * `seal` recorded one still parse — is treated exactly like a rejection. It is
+ * not evidence that anyone approved anything.
+ */
+import { decisionMessage, verifySignature } from '../keys.js';
+/**
+ * `patchId` is the diff being asked about.
+ *
+ * Any caller asking "is this proof current?" MUST compute it for real, from
+ * git. Passing the review's own `patchId` back in collapses the staleness test
+ * to a tautology — `review.patchId !== patchId` can never fire — which is
+ * precisely what let the board present post-seal code changes as reviewed work.
+ * A caller that genuinely cannot compute one passes `''` and fails closed: it
+ * can never equal a real patch-id, not even `computePatchId`'s `sha256:…`
+ * empty-diff form.
+ *
+ * `assurance/passport.ts` passes `review.patchId` deliberately, and it is the
+ * one place that may. It is not asking whether the proof is current; it is
+ * asking what diff the proof COVERS and whether that review approved. Its
+ * callers (`ship --verify`, `classifyMainPush`) then settle currency
+ * themselves, by recomputing the merged head's patch-id and comparing. Verdict
+ * and currency are separable questions — read the call site before copying the
+ * shape, because everywhere else the tautology is a fail-open.
+ */
+export function assessReview(review, patchId) {
+    if (!review) {
+        return 'none';
+    }
+    if (review.state !== 'sealed') {
+        return 'draft';
+    }
+    if (review.patchId !== patchId) {
+        return 'sealed-stale';
+    }
+    return review.verdict === 'approve' ? 'sealed-current-approved' : 'sealed-current-blocked';
+}
+/** Only `sealed-current-approved` may progress. Everything else fails closed. */
+export function reviewProgresses(standing) {
+    return standing === 'sealed-current-approved';
+}
+/** The reason line the gate, `accept` and the board all show. */
+export function describeReview(standing, review) {
+    switch (standing) {
+        case 'none':
+            return 'no review found — run review then seal';
+        case 'draft':
+            return 'review exists but is not sealed';
+        case 'sealed-stale':
+            return 'the code changed since the review was sealed — re-review';
+        case 'sealed-current-approved':
+            return `approved by ${review?.reviewer ?? 'the reviewer'}`;
+        case 'sealed-current-blocked':
+            return review?.verdict === 'request_changes'
+                ? `the reviewer requested changes (${review.reviewer}) — this diff is not approved`
+                : 'the sealed review records no explicit approve verdict — re-seal it';
+    }
+}
+/**
+ * `trustedKey` is `config.owner.publicKey`. A decision that does not verify
+ * against it is `signed-stale`: not the owner's, therefore not the owner's
+ * word about anything.
+ *
+ * IDENTIFY, then AUTHENTICATE, then classify. `contractId` is the change being
+ * assessed, and BOTH `decision.id` and `decision.contractId` must equal it
+ * before the signature is even looked at. Without that, a genuine owner
+ * approval of contract A — signed, verifiable, entirely honest — could be
+ * copied to `decisions/B.json` and passed the gate for contract B whenever the
+ * two diffs shared a patch-id (identical content on a shared baseline: a
+ * cherry-pick, a rebase, a re-framed change). The signature verifies over the
+ * decision's OWN `contractId`, so it verifies perfectly; only comparing the
+ * embedded ids to the contract in hand can tell the replay from the original.
+ * `decision.id` is checked as well as `contractId` because it is the one that
+ * must match the FILENAME the record was read from — this is where
+ * filename-to-record identity is enforced for every caller (`readDecision` is
+ * deliberately shape-free, so a record on disk always stays readable).
+ *
+ * The same replay against a REVIEW is not worth guarding: a review carries no
+ * signature, so anyone able to copy `reviews/A.md` to `reviews/B.md` can as
+ * easily write a fresh `approve` from nothing. The decision is the opposite
+ * case — the Ed25519 signature is the one artefact file-write access cannot
+ * forge, which makes replaying a real one the only way in.
+ *
+ * AUTHENTICATE BEFORE CLASSIFYING. Reading `decision.decision` before the
+ * signature let any file dropped at `decisions/<id>.md` be reported as "the
+ * owner rejected this diff" — the board and `next` then routed a change back
+ * to a builder on the word of a record nobody signed. It fails in the blocking
+ * direction, which is why it survived review, but a governance tool that
+ * attributes an unsigned rejection to the owner is asserting something it has
+ * not checked, and the surface that renders it also serves POST `/accept`.
+ *
+ * The signature is verified over `decision.patchId`, never the caller's
+ * `patchId`: that is the diff the owner actually signed over, and using it is
+ * what makes a STALE decision authenticable at all. The two were identical in
+ * the only branch that reached verification before, so nothing current changes
+ * standing — an honest rejection of an earlier diff is still `rejected-stale`.
+ *
+ * Currency is then a separate question, as everywhere else in this module. A
+ * rejection is classified against the diff too — a rejection of an OLD diff
+ * must not keep routing a reworked change back to the builder for ever, which
+ * is exactly the loop `next` was stuck in.
+ */
+export function assessDecision(decision, contractId, patchId, trustedKey) {
+    if (!decision) {
+        return 'none';
+    }
+    // A decision that is not about THIS contract is not the owner's word about
+    // it, however impeccably it is signed. No empty-string guard is needed: both
+    // fields are `min(1)`, so an empty `contractId` matches nothing and fails
+    // closed on its own.
+    if (decision.id !== contractId || decision.contractId !== contractId) {
+        return 'signed-stale';
+    }
+    const key = trustedKey?.trim();
+    if (!key || decision.publicKey.trim() !== key) {
+        return 'signed-stale';
+    }
+    const message = decisionMessage(decision.contractId, decision.patchId, decision.decision);
+    if (!verifySignature(message, decision.signature, key)) {
+        return 'signed-stale';
+    }
+    const bindsThisDiff = decision.patchId === patchId;
+    if (decision.decision === 'rejected') {
+        return bindsThisDiff ? 'rejected-current' : 'rejected-stale';
+    }
+    return bindsThisDiff ? 'signed-current' : 'signed-stale';
+}
+/** Only `signed-current` may progress. Everything else fails closed. */
+export function decisionProgresses(standing) {
+    return standing === 'signed-current';
+}
+/** The reason line the gate shows. */
+export function describeDecision(standing, decision) {
+    switch (standing) {
+        case 'none':
+            return 'no signed decision found — run accept';
+        case 'rejected-current':
+            return 'the owner rejected this diff';
+        case 'rejected-stale':
+            return 'the owner rejected an earlier diff — accept this one';
+        case 'signed-stale':
+            return 'no valid owner signature over this exact diff — re-accept';
+        case 'signed-current':
+            return `signed by ${decision?.by ?? 'the owner'}`;
+    }
+}
+//# sourceMappingURL=outcome.js.map

package/dist/assurance/outcome.js.map

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

package/dist/assurance/passport.js

@@ -0,0 +1,98 @@
+/**
+ * What a passport is allowed to bind to — the one answer `ship --verify` and
+ * `assurance/mainpush.ts`'s direct-main push classifier both use.
+ *
+ * A passport claims a change works live. Binding it to a bare merged PR url is
+ * not enough: a branch name can be reused, so an OLDER merged PR could back a
+ * NEWER passport. The existing fix recomputed the seal maths against the merged
+ * PR's own head commit and compared it to the sealed review's `patchId` — sound
+ * for a change that HAS a review, and a dead end for one that does not.
+ *
+ * `light` tier deliberately requires no review (`gate.ts` asks for one only
+ * above `light`, and `config.tierRules` is the dial). Demanding a sealed review
+ * at verify time therefore made every light change unverifiable: the passport
+ * refused, and the only ways out were to fake a review or to inflate the tier —
+ * exactly the review ceremony the tier exists to avoid. The repair is not to
+ * skip the binding but to bind to the proof that tier actually has: the check,
+ * via the `checkedHead` its ledger entry now records. Same patch-id maths, same
+ * exact-commit guarantee, sourced from whichever proof the tier requires.
+ */
+import fs from 'node:fs';
+import * as git from '../git.js';
+import { latestCheckStanding } from '../ledger.js';
+import { readReview, reviewPath } from '../records/store.js';
+import { assessReview, describeReview, reviewProgresses } from './outcome.js';
+import { checkStillBinds } from './proofinputs.js';
+/**
+ * The patch-id the current proof for `contract` covers, or why there is none.
+ *
+ * Above `light` tier that is the sealed review's own `patchId` — and the review
+ * must have APPROVED, not merely been sealed, since a passport for a diff the
+ * reviewer rejected is precisely the claim this project exists to make
+ * impossible. At `light` tier it is the diff at the commit the passing check
+ * recorded, and that check must still BIND `boundCommit`.
+ *
+ * `boundCommit` is the commit the passport will bind to — the merged PR's own
+ * head, which both callers already hold and already recompute the seal maths
+ * against. It is REQUIRED, with no default, for the reason `runAmend` requires
+ * `interactive`/`confirm`: the obvious default (`HEAD`) is wrong for the caller
+ * that matters most. `ship --verify` and `classifyMainPush` run against
+ * `mainRoot` after the merge, where a lane check measured to HEAD spans all of
+ * main and can only ever fail — reintroducing, silently, the unverifiable
+ * light-tier change this module exists to fix.
+ *
+ * Why only the light branch tests currency: `review.ts` already requires
+ * `checkStillBinds` before it will write a review at all, so a sealed review's
+ * patch-id transitively carries "a passing check bound this commit". A ledger
+ * entry carries no such upstream binding, so the light branch must ask for
+ * itself. Without it, the patch-id comparison the callers make proves only that
+ * the CODE is the proven code — the contract's own terms, a Flow report, an
+ * intent could all have moved after the check without moving a patch-id that
+ * excludes `.prismatica/`, and the passport would present proof of a diff
+ * nobody checked under the terms it shipped under.
+ */
+export async function provenPatchId(home, contract, boundCommit) {
+    if (contract.tier !== 'light') {
+        const review = fs.existsSync(reviewPath(home, contract.id))
+            ? readReview(home, contract.id).data
+            : undefined;
+        if (!review || review.state !== 'sealed') {
+            return {
+                ok: false,
+                reason: `no sealed review found for "${contract.id}" to bind this passport to`,
+                command: `prismatica review ${contract.id}`,
+            };
+        }
+        // Staleness is settled by comparing THIS patch-id to the merged head's, so
+        // the assessment is asked only about the verdict — hence its own patch-id
+        // as the "current" argument.
+        const standing = assessReview(review, review.patchId);
+        if (!reviewProgresses(standing)) {
+            return {
+                ok: false,
+                reason: `the review for "${contract.id}" did not approve this change: ${describeReview(standing, review)}`,
+                command: `prismatica seal ${contract.id}`,
+            };
+        }
+        return { ok: true, patchId: review.patchId, source: `the sealed review by ${review.reviewer}` };
+    }
+    const standing = latestCheckStanding(home, contract.id);
+    if (standing.state !== 'pass') {
+        return {
+            ok: false,
+            reason: `"${contract.id}" is light tier, so its passport binds to its passing check — ${standing.detail}`,
+            command: `prismatica check ${contract.id}`,
+        };
+    }
+    const checkedHead = standing.entry.checkedHead;
+    if (!(await checkStillBinds(home, contract, checkedHead, boundCommit))) {
+        return {
+            ok: false,
+            reason: `the passing check for "${contract.id}" at ${checkedHead.slice(0, 12)} no longer binds ${boundCommit.slice(0, 12)} — something other than this change's own check output was committed between them`,
+            command: `prismatica check ${contract.id}`,
+        };
+    }
+    const patchId = await git.computePatchId(home, contract.baseline.commit, git.EXCLUDE_RECORDS, checkedHead);
+    return { ok: true, patchId, source: `the passing check at ${checkedHead.slice(0, 12)}` };
+}
+//# sourceMappingURL=passport.js.map

package/dist/assurance/passport.js.map

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