@codyswann/lisa 4.54.13 → 4.55.0

package/scripts/generate-two-channel-couplings.ts

@@ -39,6 +39,14 @@
  *   - a ratification matching no live coupling, because a permission left
  *     behind after its subject is gone is inherited for free by the next path
  *     that happens to match;
+ *   - a ledgered coupling with no recorded STALENESS decision (#3687) — the
+ *     one field a new coupling cannot be added without, because its detection
+ *     is derived and therefore free while the decision costs a sentence;
+ *   - a staleness decision the tree refuses to support, in either direction:
+ *     a claimed handshake nothing shows, or an exemption on a coupling that
+ *     already has one;
+ *   - a staleness decision matching no live coupling, for the same reason a
+ *     stale ratification fails;
  *   - `--check` against a stale ledger;
  *   - and any run that measured nothing.
  *
@@ -82,6 +90,13 @@ import {
   isReusable,
   scanWorkflow,
 } from "../src/core/two-channel-delivery-scan.js";
+import {
+  artifactStalenessSignals,
+  STALENESS_DECISIONS,
+  STALENESS_DETECTIONS,
+  type StalenessRecord,
+  type StalenessSignal,
+} from "../src/core/two-channel-staleness.js";
 
 /** Where the fast channel's bodies live in this repository. */
 const WORKFLOWS_DIR = path.join(".github", "workflows");
@@ -228,52 +243,21 @@ export function buildDeliveryInventory(
   );
 }
 
-/**
- * The only part of a report these two functions read.
- *
- * Narrower than the full report on purpose: they need a key and a verdict per
- * entry and nothing else, and a parameter that asked for the whole measurement
- * would force every caller — including a test — to build one it does not use.
- */
-interface CouplingKeySource {
-  readonly entries: readonly {
-    readonly key: string;
-    readonly verdict: string;
-  }[];
-}
-
-/** One coupling's answer to "can this notice a STALE artifact?" (#3687). */
-export interface StalenessClassification {
-  /**
-   * What the coupling CAN detect today — an observation, not a decision.
-   *
-   * `version-handshake` asks the artifact for a contract version and compares
-   * it. `capability-probe` asks for one subcommand or flag and infers age from
-   * whether it answers, which sees staleness at exactly one point and is blind
-   * above that floor — the CodySwannGT/lisa#3477 defect. `existence-only`
-   * cannot see age at all.
-   */
-  readonly detects: "version-handshake" | "capability-probe" | "existence-only";
-  /**
-   * Why the current level is acceptable. Required unless a handshake exists.
-   *
-   * This is the DECISION half, kept separate from `detects` on purpose: a
-   * coupling that cannot see age and is fine that way (an advisory read, an
-   * artifact carrying no verdict-bearing logic) is a different fact from one
-   * that cannot see age and should. Collapsing them into a single
-   * "not-needed" token would lose exactly the distinction the sweep exists to
-   * record, and would let an unexamined default wear the same word as a
-   * considered exemption.
-   */
-  readonly reason?: string;
-}
-
 /** The ledger's hand-authored half plus its derived half. */
 interface Ledger {
   readonly ratified: Readonly<Record<string, string>>;
-  readonly staleness: Readonly<Record<string, StalenessClassification>>;
+  /**
+   * The staleness decision recorded for each ledgered coupling.
+   *
+   * Hand-authored, and required. The DETECTION beside each coupling below is
+   * derived from the tree on every run; this is the half a person has to
+   * answer, which is what stops entry 24 from inheriting "nobody looked".
+   */
+  readonly staleness: Readonly<Record<string, StalenessRecord>>;
   readonly inspected: TwoChannelReport["inspected"];
   readonly counts: TwoChannelReport["counts"];
+  readonly detectionCounts: TwoChannelReport["detectionCounts"];
+  readonly decisionCounts: TwoChannelReport["decisionCounts"];
   readonly couplings: readonly {
     readonly key: string;
     readonly workflow: string;
@@ -282,172 +266,47 @@ interface Ledger {
     readonly verdict: string;
     readonly remedy: string;
     readonly guarded: boolean;
+    readonly handling: readonly string[];
+    readonly detection: string;
+    readonly stalenessSignals: readonly string[];
+    readonly decision: string | null;
+    readonly reason: string | null;
     readonly lanes: readonly string[];
     readonly detail: string;
   }[];
 }
 
 /**
- * Read the ratifications already recorded, so regenerating never drops them.
+ * The ledger as it currently stands, or an empty one when there is none.
  * @param ledgerPath - Absolute path to the ledger
- * @returns The ratification reasons, keyed `<workflow>::<path>`
+ * @returns Whatever the file holds, unvalidated
  */
-function readRatified(ledgerPath: string): Readonly<Record<string, string>> {
+function readLedger(ledgerPath: string): Partial<Ledger> {
   if (!existsSync(ledgerPath)) return {};
-  const parsed = JSON.parse(readFileSync(ledgerPath, "utf8")) as
-    | Partial<Ledger>
-    | undefined;
-  return parsed?.ratified ?? {};
-}
-
-/**
- * Read the staleness classifications already recorded (#3687).
- *
- * Exactly the shape `readRatified` uses, and for the same reason: the ledger is
- * a DERIVED artifact regenerated in-commit, so a hand-authored field survives
- * only if the generator reads the previous version before rewriting it. This is
- * the established local precedent for persisting a human decision inside a
- * generated file, which is why the classification lives here rather than in a
- * new sidecar nobody would remember to update.
- * @param ledgerPath - Absolute path to the ledger
- * @returns The classifications, keyed `<workflow>::<path>`
- */
-function readStaleness(
-  ledgerPath: string
-): Readonly<Record<string, StalenessClassification>> {
-  if (!existsSync(ledgerPath)) return {};
-  const parsed = JSON.parse(readFileSync(ledgerPath, "utf8")) as
-    | Partial<Ledger>
-    | undefined;
-  return parsed?.staleness ?? {};
-}
-
-/**
- * The verdict for a coupling the package channel already covers.
- *
- * Those are omitted from the ledger, so every question this file asks about a
- * live coupling has to exclude them — named once so the three sites cannot
- * disagree about which verdict that is.
- */
-const PACKAGE_BACKED = "package-backed";
-
-/** The `detects` value meaning the coupling asks for a contract version. */
-const VERSION_HANDSHAKE = "version-handshake";
-
-/** The `detects` value meaning it infers age from one subcommand or flag. */
-const CAPABILITY_PROBE = "capability-probe";
-
-/** The `detects` value meaning it can see presence and nothing else. */
-const EXISTENCE_ONLY = "existence-only";
-
-/** The `detects` values a classification may carry. */
-const DETECTS = new Set([VERSION_HANDSHAKE, CAPABILITY_PROBE, EXISTENCE_ONLY]);
-
-/**
- * The floor a stated reason must clear to be a reason rather than a label.
- *
- * A floor, not a proof — no check tells a real argument from filler. What it
- * buys is that "n/a", "ok" and an empty string cannot stand in for the decision
- * this field exists to record.
- */
-const MIN_REASON_CHARACTERS = 40;
-
-/**
- * Every problem with the staleness half, as operator-readable paragraphs.
- *
- * THREE refusals, and the first is the one that makes this a standing property
- * rather than a one-time sweep: a coupling with no classification fails, so
- * entry 25 cannot silently inherit "nobody looked". A sweep decays the moment
- * somebody adds an entry; a required field does not.
- * @param report - The measurement
- * @param staleness - The recorded classifications
- * @returns Problem paragraphs, empty when the staleness half is sound
- */
-export function stalenessProblems(
-  report: CouplingKeySource,
-  staleness: Readonly<Record<string, StalenessClassification>>
-): readonly string[] {
-  const live = new Set(
-    report.entries
-      .filter(entry => entry.verdict !== PACKAGE_BACKED)
-      .map(entry => entry.key)
+  return (
+    (JSON.parse(readFileSync(ledgerPath, "utf8")) as Partial<Ledger> | null) ??
+    {}
   );
-  const missing = [...live]
-    .filter(key => staleness[key] === undefined)
-    .map(
-      key =>
-        `\nUNCLASSIFIED COUPLING ${key}\n  No staleness classification. Every ` +
-        `coupling must record whether it can detect a STALE artifact, not only ` +
-        `an absent one — absence skips and posts nothing, while present-and-old ` +
-        `posts a verdict from superseded logic that every reader believes. Add ` +
-        `a "staleness" entry with "detects" (version-handshake | ` +
-        `capability-probe | existence-only) and, unless it is a handshake, a ` +
-        `"reason" saying why that is acceptable here.`
-    );
-  const orphaned = Object.keys(staleness)
-    .filter(key => !live.has(key))
-    .map(
-      key =>
-        `\nSTALE CLASSIFICATION ${key}\n  Nothing reads this path any more, so ` +
-        `the classification is an unexamined judgement the next matching path ` +
-        `would inherit. Delete it from ${LEDGER_PATH}.`
-    );
-  const malformed = Object.entries(staleness)
-    .filter(([key]) => live.has(key))
-    .flatMap(([key, value]) => describeMalformed(key, value));
-  return [...missing, ...orphaned, ...malformed];
 }
 
 /**
- * Why one recorded classification is not usable, if it is not.
- * @param key - The coupling key
- * @param value - The recorded classification
- * @returns Problem paragraphs for this entry
+ * Read the ratifications already recorded, so regenerating never drops them.
+ * @param ledgerPath - Absolute path to the ledger
+ * @returns The ratification reasons, keyed `<workflow>::<path>`
  */
-function describeMalformed(
-  key: string,
-  value: StalenessClassification
-): readonly string[] {
-  if (!DETECTS.has(value?.detects)) {
-    return [
-      `\nMALFORMED CLASSIFICATION ${key}\n  "detects" is ` +
-        `${JSON.stringify(value?.detects)}; expected one of ` +
-        `${[...DETECTS].join(", ")}.`,
-    ];
-  }
-  if (value.detects === VERSION_HANDSHAKE) return [];
-  const reason = typeof value.reason === "string" ? value.reason.trim() : "";
-  return reason.length >= MIN_REASON_CHARACTERS
-    ? []
-    : [
-        `\nUNREASONED CLASSIFICATION ${key}\n  "detects" is ` +
-          `"${value.detects}", which cannot see how old the artifact is, and no ` +
-          `"reason" of at least ${MIN_REASON_CHARACTERS} characters says why ` +
-          `that is acceptable here. A recorded decision and an unexamined ` +
-          `default must not look the same.`,
-      ];
+function readRatified(ledgerPath: string): Readonly<Record<string, string>> {
+  return readLedger(ledgerPath).ratified ?? {};
 }
 
 /**
- * The one-line fleet coverage sentence (#3687).
- * @param report - The measurement
- * @param staleness - The recorded classifications
- * @returns A sentence naming how much of the fleet can see age
+ * Read the staleness decisions already recorded.
+ * @param ledgerPath - Absolute path to the ledger
+ * @returns The decisions, keyed `<workflow>::<path>`
  */
-export function stalenessCoverage(
-  report: CouplingKeySource,
-  staleness: Readonly<Record<string, StalenessClassification>>
-): string {
-  const live = report.entries.filter(entry => entry.verdict !== PACKAGE_BACKED);
-  const tally = (kind: string): number =>
-    live.filter(entry => staleness[entry.key]?.detects === kind).length;
-  const handshake = tally(VERSION_HANDSHAKE);
-  return (
-    `  staleness detection: ${handshake} of ${live.length} coupling(s) can see ` +
-    `how old the artifact is (${VERSION_HANDSHAKE}); ${tally(CAPABILITY_PROBE)} ` +
-    `detect it at one floor only (${CAPABILITY_PROBE}); ${tally(EXISTENCE_ONLY)} ` +
-    `detect absence only (${EXISTENCE_ONLY}).`
-  );
+function readClassified(
+  ledgerPath: string
+): Readonly<Record<string, StalenessRecord>> {
+  return readLedger(ledgerPath).staleness ?? {};
 }
 
 /**
@@ -464,15 +323,17 @@ export function stalenessCoverage(
 function toLedger(
   report: TwoChannelReport,
   ratified: Readonly<Record<string, string>>,
-  staleness: Readonly<Record<string, StalenessClassification>>
+  classified: Readonly<Record<string, StalenessRecord>>
 ): Ledger {
   return {
     ratified,
-    staleness,
+    staleness: classified,
     inspected: report.inspected,
     counts: report.counts,
+    detectionCounts: report.detectionCounts,
+    decisionCounts: report.decisionCounts,
     couplings: report.entries
-      .filter(entry => entry.verdict !== PACKAGE_BACKED)
+      .filter(entry => entry.verdict !== "package-backed")
       .map(entry => ({
         key: entry.key,
         workflow: entry.workflow,
@@ -481,6 +342,11 @@ function toLedger(
         verdict: entry.verdict,
         remedy: entry.remedy,
         guarded: entry.guarded,
+        handling: entry.handling,
+        detection: entry.detection,
+        stalenessSignals: entry.staleness,
+        decision: entry.decision,
+        reason: entry.reason,
         lanes: entry.lanes,
         detail: entry.detail,
       })),
@@ -495,12 +361,27 @@ function toLedger(
 export function measure(root: string): {
   readonly report: TwoChannelReport;
   readonly ratified: Readonly<Record<string, string>>;
-  readonly staleness: Readonly<Record<string, StalenessClassification>>;
+  readonly classified: Readonly<Record<string, StalenessRecord>>;
 } {
   const workflowsDir = path.join(root, WORKFLOWS_DIR);
   const inventory = buildDeliveryInventory(root);
   const lanesFor = (callerPath: string): readonly string[] =>
     inventory.get(callerPath) ?? [];
+  const artifactSignalsFor = (
+    callerPath: string
+  ): readonly StalenessSignal[] | null => {
+    const lanes = lanesFor(callerPath);
+    // No lane ships this path, so there is no artifact to ask. Returning [] —
+    // "it carries no version tokens" — would be the same bytes as a measured
+    // negative, which is the exact collapse this ledger exists to refuse.
+    if (lanes.length === 0) return null;
+    const signals = lanes.flatMap(lane =>
+      artifactStalenessSignals(
+        readFileSync(path.join(root, lane, callerPath), "utf8")
+      )
+    );
+    return [...new Set(signals)];
+  };
   const names = existsSync(workflowsDir)
     ? readdirSync(workflowsDir)
         .filter(name => name.endsWith(".yml") || name.endsWith(".yaml"))
@@ -519,6 +400,7 @@ export function measure(root: string): {
       workflow: entry.name,
       text: entry.text,
       lanesFor,
+      artifactSignalsFor,
     }),
   }));
   const couplings: readonly CouplingInput[] = scanned.flatMap(
@@ -534,9 +416,10 @@ export function measure(root: string): {
         inventory: inventory.size,
       },
       ratified: readRatified(path.join(root, LEDGER_PATH)),
+      classified: readClassified(path.join(root, LEDGER_PATH)),
     }),
     ratified: readRatified(path.join(root, LEDGER_PATH)),
-    staleness: readStaleness(path.join(root, LEDGER_PATH)),
+    classified: readClassified(path.join(root, LEDGER_PATH)),
   };
 }
 
@@ -545,10 +428,7 @@ export function measure(root: string): {
  * @param report - The measurement
  * @returns The report text
  */
-function humanReport(
-  report: TwoChannelReport,
-  staleness: Readonly<Record<string, StalenessClassification>>
-): string {
+function humanReport(report: TwoChannelReport): string {
   const counts = report.inspected;
   const header =
     `two-channel delivery: inspected ${counts.workflows} reusable workflow(s), ` +
@@ -568,12 +448,64 @@ function humanReport(
         `inherit. Delete it from ${LEDGER_PATH}.`
     )
     .join("");
-  // The coverage line answers the question the registry could not answer at
-  // all before this: "how many of our couplings can detect staleness?" — in one
-  // line, without opening 24 workflows.
-  const coverage = stalenessCoverage(report, staleness);
-  const unclassified = stalenessProblems(report, staleness).join("");
-  return `${header}\n${verdicts}\n${coverage}${findings}${stale}${unclassified}`;
+  return `${header}\n${verdicts}\n${stalenessReport(report)}${findings}${stale}`;
+}
+
+/**
+ * The staleness half of the report: the fleet tally and anything unanswered.
+ *
+ * Every line carries its denominator. "10 can detect staleness" is a number
+ * somebody can believe without knowing whether it is out of 12 or out of 700,
+ * and a coverage figure nobody can size is the shape of report this repository
+ * has been burned by before.
+ * @param report - The measurement
+ * @returns The staleness section
+ */
+function stalenessReport(report: TwoChannelReport): string {
+  const total = report.classifiable;
+  const handshakes = report.detectionCounts["version-handshake"];
+  const probes = report.detectionCounts["capability-probe"];
+  const blind =
+    report.detectionCounts["existence-only"] +
+    report.detectionCounts["no-probe"];
+  const unchecked = report.detectionCounts.unchecked;
+  const headline =
+    `staleness detection: ${handshakes}/${total} coupling(s) can detect a stale ` +
+    `artifact (version handshake); ${probes}/${total} detect it at one capability ` +
+    `floor only; ${blind}/${total} detect absence at most and never age; ` +
+    `${unchecked}/${total} could not be checked (nothing is delivered at the path, ` +
+    `so there is no artifact to ask).`;
+  const detections = STALENESS_DETECTIONS.map(
+    detection => `  ${detection}: ${report.detectionCounts[detection]}`
+  ).join("\n");
+  const decisions = STALENESS_DECISIONS.map(
+    decision => `  decision ${decision}: ${report.decisionCounts[decision]}`
+  ).join("\n");
+  const unclassified = report.unclassified
+    .map(
+      key =>
+        `\nUNCLASSIFIED ${key}\n  No staleness decision is recorded for this ` +
+        `coupling. Its detection is derived on every run and costs nobody ` +
+        `anything; the decision is the half a person has to make. Add an entry ` +
+        `under "staleness" in ${LEDGER_PATH} with a decision of ` +
+        `${STALENESS_DECISIONS.join(" | ")} and, unless it is \`handshake\`, a reason.`
+    )
+    .join("");
+  const contradictions = report.contradictions
+    .map(sentence => `\nCONTRADICTED DECISION ${sentence}`)
+    .join("");
+  const malformed = report.malformed
+    .map(sentence => `\nMALFORMED DECISION ${sentence}`)
+    .join("");
+  const staleDecisions = report.staleClassifications
+    .map(
+      key =>
+        `\nSTALE STALENESS DECISION ${key}\n  Nothing reads this path any more, ` +
+        `so the decision is an unexamined exemption the next matching path would ` +
+        `inherit. Delete it from ${LEDGER_PATH}.`
+    )
+    .join("");
+  return `${headline}\n${detections}\n${decisions}${unclassified}${contradictions}${malformed}${staleDecisions}`;
 }
 
 /**
@@ -587,9 +519,9 @@ export function main(argv: readonly string[]): number {
     process.stderr.write(`error: --root does not exist: ${options.root}\n`);
     return EXIT_OPERATIONAL;
   }
-  const { report, ratified, staleness } = measure(options.root);
+  const { report, ratified, classified } = measure(options.root);
   process.stdout.write(
-    `${options.json ? JSON.stringify(report, null, 2) : humanReport(report, staleness)}\n`
+    `${options.json ? JSON.stringify(report, null, 2) : humanReport(report)}\n`
   );
   if (!report.measured) {
     process.stderr.write(
@@ -600,7 +532,7 @@ export function main(argv: readonly string[]): number {
     return EXIT_OPERATIONAL;
   }
   const ledgerPath = path.join(options.root, LEDGER_PATH);
-  const rendered = `${JSON.stringify(toLedger(report, ratified, staleness), null, 2)}\n`;
+  const rendered = `${JSON.stringify(toLedger(report, ratified, classified), null, 2)}\n`;
   const current = existsSync(ledgerPath)
     ? readFileSync(ledgerPath, "utf8")
     : "";
@@ -616,14 +548,13 @@ export function main(argv: readonly string[]): number {
     mkdirSync(path.dirname(ledgerPath), { recursive: true });
     writeFileSync(ledgerPath, rendered);
   }
-  // The staleness half fails in BOTH modes, exactly as findings do. A gate you
-  // can regenerate your way past is not a gate: regenerating records a coupling,
-  // it does not classify one, and `toLedger` carries the map through untouched
-  // rather than inventing a default for a new entry (#3687).
   const failed =
     report.findings.length > 0 ||
     report.staleRatifications.length > 0 ||
-    stalenessProblems(report, staleness).length > 0 ||
+    report.unclassified.length > 0 ||
+    report.contradictions.length > 0 ||
+    report.malformed.length > 0 ||
+    report.staleClassifications.length > 0 ||
     ledgerStale;
   return failed ? 1 : 0;
 }

package/scripts/lisa-enforcement-fallback.sh

@@ -829,6 +829,37 @@ if [ "$notice_due" -eq 1 ]; then
   fi
 fi
 
+# ---------------------------------------------------------------------------
+# One evaluation per guard per tool call
+#
+# The guards below are also registered individually by the plugin manifest, so
+# on a machine where both channels are live each one runs twice for a single
+# tool call. `guard-dedupe.bash`, sourced by each guard, lets the second copy
+# replay the first copy's ALLOW instead of recomputing it — and only when the
+# two copies are byte-identical, on the identical payload, within the identical
+# tool call. Nothing above is de-registered for it, because plugin-hook liveness
+# is not observable from disk and standing down on a disk guess is how this
+# dispatcher once switched enforcement off silently (CodySwannGT/lisa#3814).
+#
+# What is handed down here is only the state directory. `$notice_temp_base` has
+# already been resolved physically and had every parent checked for ownership
+# and mode, so the eight guards this loop spawns inherit that work instead of
+# repeating it eight times. A guard reached by the plugin channel has no such
+# parent and resolves its own; a guard that finds this variable unusable does
+# the same. Exported only when the chain was trusted, so an untrusted TMPDIR
+# hands down nothing rather than handing down a bad path.
+if [ -n "$notice_temp_base" ] && [ "$notice_state_trusted" -eq 1 ]; then
+  guard_memo_dir="$notice_temp_base/lisa-guard-memo-$notice_uid"
+  if [ ! -e "$guard_memo_dir" ] && [ ! -L "$guard_memo_dir" ]; then
+    (umask 077 && mkdir "$guard_memo_dir") 2>/dev/null || true
+  fi
+  if [ -d "$guard_memo_dir" ] && [ ! -L "$guard_memo_dir" ] && \
+    [ -O "$guard_memo_dir" ]; then
+    export LISA_GUARD_MEMO_DIR="$guard_memo_dir"
+    export LISA_GUARD_MEMO_UID="$notice_uid"
+  fi
+fi
+
 # ---------------------------------------------------------------------------
 # Dispatch
 status=0