audit-tools 0.50.21 → 0.51.1

package/dist/audit/orchestrator/charterPacketArchive.d.ts

@@ -0,0 +1,51 @@
+import { type CharterKind } from "audit-tools/shared";
+/** The retained-evidence directory, beside `design-review-snapshots/`. */
+export declare const CHARTER_PACKET_ARCHIVE_DIRNAME = "charter-packets";
+/**
+ * One retention record. `archived: false` is a STATED failure, never a silent
+ * one: the source packet is still in the lane-asset directory, and the reason
+ * says why the archive could not be trusted.
+ */
+export interface CharterPacketArchiveRow {
+    kind: CharterKind;
+    /** Full sha256 of the packet bytes — the identity, even when `archived` is false. */
+    sha256: string;
+    byte_length: number;
+    archived_at: string;
+    /** The lane-asset filename the packet was read from. */
+    source_filename: string;
+    archived: boolean;
+    /** Present only on `archived: false`. */
+    reason?: string;
+}
+export declare function charterPacketArchiveDir(artifactsDir: string): string;
+export declare function charterPacketIndexPath(artifactsDir: string): string;
+/**
+ * The archived packet's filename: `<kind>-<first 12 of sha256>.md`. Keyed by
+ * CONTENT, so a re-extraction that produced identical evidence reuses the same
+ * file (one copy of one packet) while a re-extraction that produced DIFFERENT
+ * evidence lands beside it instead of overwriting the record of what an earlier
+ * lane actually read.
+ */
+export declare function charterPacketArchiveFilename(kind: CharterKind, sha256: string): string;
+/**
+ * Read the retention index. An ABSENT file, and a payload that is not an array,
+ * read as no rows. Anything else — a malformed body, a directory in its place,
+ * a permission failure — THROWS, deliberately: the caller that overwrites this
+ * file must be able to tell "there was nothing to accumulate" from "the record
+ * could not be read", and only the second must stop it from clobbering.
+ */
+export declare function readCharterPacketIndex(artifactsDir: string): Promise<CharterPacketArchiveRow[]>;
+/**
+ * Archive each kind's evidence packet, then remove it from the emitter's read
+ * path. Returns the rows written for this pass (the index on disk accumulates
+ * across re-extractions). Absent packets are skipped: nothing was delivered, so
+ * there is nothing to retain and nothing to report.
+ */
+export declare function archiveCharterPackets(params: {
+    artifactsDir: string;
+    kinds: readonly CharterKind[];
+    /** Injectable so a test pins the record rather than the clock. */
+    now?: () => string;
+}): Promise<CharterPacketArchiveRow[]>;
+//# sourceMappingURL=charterPacketArchive.d.ts.map

package/dist/audit/orchestrator/charterPacketArchive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"charterPacketArchive.d.ts","sourceRoot":"","sources":["../../../src/audit/orchestrator/charterPacketArchive.ts"],"names":[],"mappings":"AAqCA,OAAO,EAKL,KAAK,WAAW,EACjB,MAAM,oBAAoB,CAAC;AAG5B,0EAA0E;AAC1E,eAAO,MAAM,8BAA8B,oBAAoB,CAAC;AAKhE;;;;GAIG;AACH,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,WAAW,CAAC;IAClB,qFAAqF;IACrF,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,wDAAwD;IACxD,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,OAAO,CAAC;IAClB,yCAAyC;IACzC,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,uBAAuB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEpE;AAED,wBAAgB,sBAAsB,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAEnE;AAED;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,IAAI,EAAE,WAAW,EACjB,MAAM,EAAE,MAAM,GACb,MAAM,CAER;AAED;;;;;;GAMG;AACH,wBAAsB,sBAAsB,CAC1C,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAKpC;AAYD;;;;;GAKG;AACH,wBAAsB,qBAAqB,CAAC,MAAM,EAAE;IAClD,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,SAAS,WAAW,EAAE,CAAC;IAC9B,kEAAkE;IAClE,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB,GAAG,OAAO,CAAC,uBAAuB,EAAE,CAAC,CAgGrC"}

package/dist/audit/orchestrator/charterPacketArchive.js

@@ -0,0 +1,173 @@
+/**
+ * Charter evidence-packet RETENTION.
+ *
+ * Packets are consumed inputs: a stale packet left in the lane-asset directory
+ * would feed a later staleness-triggered re-extraction yesterday's evidence, so
+ * the emitter's read path must be empty after ingest. That reason is real and is
+ * preserved verbatim here — what changes is that the bytes are no longer
+ * DESTROYED to achieve it.
+ *
+ * The packet's content was nowhere else when it was unlinked, which inverts the
+ * P25-f rule stated 130 lines above the deletion site: a submission is only ever
+ * destroyed once its content is somewhere else. So three independent lanes could
+ * each report that the request path was absent from their packet, and the
+ * orchestrator could not confirm it — a glob against the deleted names matched
+ * nothing and produced a confident, meaningless "0 of 3".
+ *
+ * A HASH ALONE WOULD NOT ANSWER THE QUESTION. `materializeCharterPacket` reads
+ * the audited repository from disk, so a packet is a function of bundle + WORKING
+ * TREE. Once the audited tree moves the packet is not regenerable and a hash
+ * becomes unfalsifiable — it answers "did this lane get the tool's packet", never
+ * "what exactly did this lane read". Retain the bytes; carry the hash as identity.
+ *
+ * ARCHIVE-THEN-UNLINK, never unlink-then-hope. The archived bytes are re-read and
+ * re-hashed BEFORE the source is removed; a failed or unverifiable archive leaves
+ * the source in place and records `archived: false` with a reason.
+ *
+ * IT NEVER THROWS. This runs after `runAuditStepUnlocked` has applied the
+ * submission and after the lane files are marked applied — the RECORD arm of
+ * `514cd31c`, not the throw arm. A throw here would abort a fold whose ingest had
+ * already succeeded, which is strictly worse than a stated retention failure.
+ *
+ * `charter-packets/` is a retained-evidence directory with no `ARTIFACT_DEFINITIONS`
+ * row and no dependency-map node — the precedent `design-review-snapshots/` set.
+ * Nothing reads it as input, so it adds no DAG edge and cannot re-stale anything.
+ */
+import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { compareCodeUnits, hashContent, laneAssetsDir, readOptionalJsonFile, } from "audit-tools/shared";
+import { charterExtractionPacketFilename } from "../cli/laneSubmissions.js";
+/** The retained-evidence directory, beside `design-review-snapshots/`. */
+export const CHARTER_PACKET_ARCHIVE_DIRNAME = "charter-packets";
+/** Characters of the content digest that name an archived packet file. */
+const ARCHIVE_NAME_DIGEST_CHARS = 12;
+export function charterPacketArchiveDir(artifactsDir) {
+    return join(artifactsDir, CHARTER_PACKET_ARCHIVE_DIRNAME);
+}
+export function charterPacketIndexPath(artifactsDir) {
+    return join(charterPacketArchiveDir(artifactsDir), "index.json");
+}
+/**
+ * The archived packet's filename: `<kind>-<first 12 of sha256>.md`. Keyed by
+ * CONTENT, so a re-extraction that produced identical evidence reuses the same
+ * file (one copy of one packet) while a re-extraction that produced DIFFERENT
+ * evidence lands beside it instead of overwriting the record of what an earlier
+ * lane actually read.
+ */
+export function charterPacketArchiveFilename(kind, sha256) {
+    return `${kind}-${sha256.slice(0, ARCHIVE_NAME_DIGEST_CHARS)}.md`;
+}
+/**
+ * Read the retention index. An ABSENT file, and a payload that is not an array,
+ * read as no rows. Anything else — a malformed body, a directory in its place,
+ * a permission failure — THROWS, deliberately: the caller that overwrites this
+ * file must be able to tell "there was nothing to accumulate" from "the record
+ * could not be read", and only the second must stop it from clobbering.
+ */
+export async function readCharterPacketIndex(artifactsDir) {
+    const rows = await readOptionalJsonFile(charterPacketIndexPath(artifactsDir));
+    return Array.isArray(rows) ? rows : [];
+}
+/** Stable order: kind, then content digest. Never insertion or IO-completion order. */
+function sortRows(rows) {
+    return [...rows].sort((a, b) => compareCodeUnits(a.kind, b.kind) ||
+        compareCodeUnits(a.sha256, b.sha256) ||
+        (a.archived === b.archived ? 0 : a.archived ? 1 : -1));
+}
+/**
+ * Archive each kind's evidence packet, then remove it from the emitter's read
+ * path. Returns the rows written for this pass (the index on disk accumulates
+ * across re-extractions). Absent packets are skipped: nothing was delivered, so
+ * there is nothing to retain and nothing to report.
+ */
+export async function archiveCharterPackets(params) {
+    const now = params.now ?? (() => new Date().toISOString());
+    const archiveDir = charterPacketArchiveDir(params.artifactsDir);
+    const written = [];
+    for (const kind of params.kinds) {
+        const sourceFilename = charterExtractionPacketFilename(kind);
+        const sourcePath = join(laneAssetsDir(params.artifactsDir), sourceFilename);
+        let bytes;
+        try {
+            bytes = await readFile(sourcePath);
+        }
+        catch {
+            continue; // No packet on disk — nothing was delivered to retain.
+        }
+        const digest = hashContent(bytes);
+        const row = {
+            kind,
+            sha256: digest,
+            byte_length: bytes.byteLength,
+            archived_at: now(),
+            source_filename: sourceFilename,
+            archived: false,
+        };
+        try {
+            await mkdir(archiveDir, { recursive: true });
+            const archivePath = join(archiveDir, charterPacketArchiveFilename(kind, digest));
+            await writeFile(archivePath, bytes);
+            // Re-read and re-hash BEFORE unlinking: a write that reported success over
+            // truncated or unflushed bytes must not be paid for with the only copy.
+            const readBack = await readFile(archivePath);
+            if (hashContent(readBack) !== digest) {
+                row.reason = "archived bytes did not re-hash to the packet's digest";
+            }
+            else {
+                row.archived = true;
+            }
+        }
+        catch (error) {
+            row.reason = `archive write failed: ${error instanceof Error ? error.message : String(error)}`;
+        }
+        if (row.archived) {
+            // Only now is the content somewhere else (P25-f). A failed unlink leaves a
+            // verified archive plus a live source — recorded, never reported as clean.
+            try {
+                await unlink(sourcePath);
+            }
+            catch (error) {
+                row.archived = false;
+                row.reason = `packet archived but the lane-asset copy survived: ${error instanceof Error ? error.message : String(error)}`;
+            }
+        }
+        written.push(row);
+    }
+    if (written.length === 0)
+        return written;
+    // The WHOLE index phase — read, merge, write — is inside one guard. The READ
+    // was outside it, and that broke the never-throw contract on one platform
+    // only: `readCharterPacketIndex` wraps its own IO failure (`Failed to read
+    // <path>`) for anything it cannot classify as absent, and "absent" is decided
+    // by an ENOENT test, while a path that traverses a FILE reports ENOENT on
+    // win32 and ENOTDIR on POSIX. So the identical filesystem state read as an
+    // empty index here and as a rejected promise in Linux CI. A directory in
+    // place of the index file (EISDIR on both) escaped everywhere, as did a
+    // malformed index, whose parse error is not an absence either.
+    try {
+        // The index ACCUMULATES — a re-extraction adds what it retained and never
+        // overwrites the record of what an earlier lane read. Identical (kind,
+        // digest, outcome) rows collapse: same bytes, same packet, already recorded.
+        const existing = await readCharterPacketIndex(params.artifactsDir);
+        const seen = new Set(existing.map((r) => `${r.kind}|${r.sha256}|${r.archived}`));
+        const merged = [...existing];
+        for (const row of written) {
+            const key = `${row.kind}|${row.sha256}|${row.archived}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            merged.push(row);
+        }
+        await mkdir(archiveDir, { recursive: true });
+        await writeFile(charterPacketIndexPath(params.artifactsDir), `${JSON.stringify(sortRows(merged), null, 2)}\n`, "utf8");
+    }
+    catch {
+        // The index is a convenience over the archived files themselves; failing to
+        // write it must not abort a fold whose ingest already succeeded. Nothing is
+        // written when the existing rows could not be READ either — the write is
+        // reached only through a successful read, so a failed read can never
+        // overwrite the accumulated record this index exists to keep.
+    }
+    return written;
+}
+//# sourceMappingURL=charterPacketArchive.js.map

package/dist/audit/orchestrator/charterPacketArchive.js.map

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

package/dist/audit/orchestrator/charterPackets.d.ts

@@ -1,5 +1,6 @@
-import type { CharterKind } from "audit-tools/shared";
+import type { CharterKind, CharterPacketCoverage, CharterPacketManifest, PacketExcerpt } from "audit-tools/shared";
 import type { ArtifactBundle } from "../io/artifacts.js";
+import { type NumberedSourceLine } from "../extractors/commentDecomposition.js";
 /**
  * The charter layer's read-set over the repo: consensus MEMBER files (every
  * channel is a projection of member content — comments for stated, organization
@@ -21,24 +22,41 @@ export declare function charterPacketReadSet(bundle: ArtifactBundle): {
  */
 export declare function memberDependencyEdgeLines(bundle: ArtifactBundle): string[];
 /**
- * Top-level declaration lines of a comment-stripped source: non-blank lines at
- * indent zero that do not merely close a scope. A deliberate language-neutral
- * HEURISTIC (a lead, not a parse): in brace- and indent-family languages alike,
- * a file's organization — imports, exports, signatures, class/type heads — sits
- * at column 0 while implementation bodies sit indented. Good enough to show the
- * structural channel what the file declares without leaking how it works.
+ * Top-level declaration lines of a masked source: non-blank lines at indent zero
+ * that do not merely close a scope. A deliberate language-neutral HEURISTIC (a
+ * lead, not a parse): in brace- and indent-family languages alike, a file's
+ * organization — imports, exports, signatures, class/type heads — sits at column
+ * 0 while implementation bodies sit indented. Good enough to show the structural
+ * channel what the file declares without leaking how it works.
+ *
+ * It takes NUMBERED lines and returns numbered lines, so a declaration keeps the
+ * line it actually occupies in its own file. Feeding it `stripCommentText` output
+ * would number every declaration against a collapsed view — a confidently wrong
+ * citation, which is worse than none.
  */
-export declare function topLevelDeclarationLines(strippedSource: string): string[];
+export declare function topLevelDeclarationLines(lines: readonly NumberedSourceLine[]): NumberedSourceLine[];
 export interface MaterializeCharterPacketParams {
     root: string;
     bundle: ArtifactBundle;
     kind: CharterKind;
 }
+export interface MaterializedCharterPacket {
+    markdown: string;
+    coverage: CharterPacketCoverage;
+    excerpts: PacketExcerpt[];
+}
+/**
+ * The machine header a lane copies its citations from, and — byte-identically —
+ * the lane asset the emit pass persists for the ingest pass. ONE function builds
+ * both, so what a lane reads and what a validator checks against cannot drift.
+ */
+export declare function buildCharterPacketManifest(kind: CharterKind, excerpts: readonly PacketExcerpt[], coverage: CharterPacketCoverage): CharterPacketManifest;
 /**
- * Materialize ONE kind's evidence packet as markdown. Deterministic given the
- * bundle + file contents: stable path order, fixed budgets, explicit omitted
- * lists. Unreadable/oversized files are named in the omitted list (never
- * silently absent) so a lane can say "evidence missing" instead of guessing.
+ * Materialize ONE kind's evidence packet. Deterministic given the bundle + file
+ * contents: stable path order, every named candidate delivered in full, and an
+ * explicit per-class coverage record in which
+ * `delivered + omitted.length === named` for every class — so a file that
+ * contributed nothing is NAMED rather than silently absent.
  */
-export declare function materializeCharterPacket(params: MaterializeCharterPacketParams): Promise<string>;
+export declare function materializeCharterPacket(params: MaterializeCharterPacketParams): Promise<MaterializedCharterPacket>;
 //# sourceMappingURL=charterPackets.d.ts.map

package/dist/audit/orchestrator/charterPackets.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"charterPackets.d.ts","sourceRoot":"","sources":["../../../src/audit/orchestrator/charterPackets.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAYzD;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,cAAc,GAAG;IAC5D,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAaA;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,EAAE,CAa1E;AAED;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,EAAE,CASzE;AA8DD,MAAM,WAAW,8BAA8B;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,cAAc,CAAC;IACvB,IAAI,EAAE,WAAW,CAAC;CACnB;AAED;;;;;GAKG;AACH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,8BAA8B,GACrC,OAAO,CAAC,MAAM,CAAC,CAgFjB"}
+{"version":3,"file":"charterPackets.d.ts","sourceRoot":"","sources":["../../../src/audit/orchestrator/charterPackets.ts"],"names":[],"mappings":"AAmBA,OAAO,KAAK,EACV,WAAW,EACX,qBAAqB,EAErB,qBAAqB,EAGrB,aAAa,EAEd,MAAM,oBAAoB,CAAC;AAM5B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,uCAAuC,CAAC;AAE/C;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,cAAc,GAAG;IAC5D,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,CAaA;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,EAAE,CAa1E;AAGD;;;;;;;;;;;;GAYG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,SAAS,kBAAkB,EAAE,GACnC,kBAAkB,EAAE,CAatB;AAsGD,MAAM,WAAW,8BAA8B;IAC7C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,cAAc,CAAC;IACvB,IAAI,EAAE,WAAW,CAAC;CACnB;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,qBAAqB,CAAC;IAChC,QAAQ,EAAE,aAAa,EAAE,CAAC;CAC3B;AAED;;;;GAIG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,WAAW,EACjB,QAAQ,EAAE,SAAS,aAAa,EAAE,EAClC,QAAQ,EAAE,qBAAqB,GAC9B,qBAAqB,CAcvB;AA0ED;;;;;;GAMG;AACH,wBAAsB,wBAAwB,CAC5C,MAAM,EAAE,8BAA8B,GACrC,OAAO,CAAC,yBAAyB,CAAC,CAsGpC"}