peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/fixture/fixture-capture-service.js

@@ -0,0 +1,317 @@
+/**
+ * v2.14.0 G1 AC-1.4 — Fixture capture service.
+ *
+ * Producer-side counterpart of `fixture-sanitize-service`. The CLI
+ * (`scripts/fixture-capture.mjs`) is a thin wrapper around this module.
+ *
+ * Two capture modes:
+ *
+ *   1. **historical** — copy a real envelope file from
+ *      `.peaks/_runtime/<sid>/<role>/<envelope>` to
+ *      `tests/fixtures/replay/<name>.md` (or `.json`), sanitize, checksum.
+ *
+ *   2. **derived-variant** — take an already-captured fixture and apply
+ *      a deterministic edge-case transformation. The transformations
+ *      are the 5 v2.13.x historical bug shapes that the replay suite
+ *      must hit (PRD A1.2):
+ *
+ *      - `chinese-colon`            — replace ASCII `:` after
+ *                                     `verdict` / `passed` with fullwidth
+ *                                     `：` in the frontmatter / body
+ *      - `yaml-frontmatter-variation` — inject CRLF / BOM / extra spaces
+ *                                     into the YAML frontmatter
+ *      - `double-format`            — embed a JSON blob inside a markdown
+ *                                     body (or vice versa)
+ *      - `empty-body`               — strip everything after `## Summary`
+ *      - `multi-findings`           — duplicate the `## Findings` block
+ *
+ * Every captured fixture is paired with a `fixture.meta.json` that
+ * validates against `schemas/replay-fixture.schema.json`.
+ */
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, sep } from 'node:path';
+import { sanitizeFixtureStrict, SANITIZE_RULE_NAMES } from './fixture-sanitize-service.js';
+export const ENVELOPE_KINDS = [
+    'audit-security',
+    'audit-perf',
+    'karpathy-review',
+    'mut-report',
+    'qa-report',
+    'prd-handoff'
+];
+/**
+ * Map envelope kind → on-disk path segment under `.peaks/_runtime/<sid>/`.
+ * `qa-report` is intentionally absent — the PRD lists 5 envelope types;
+ * `qa-report` is a 6th bonus to widen coverage. All 6 are accepted as
+ * inputs; the replay test enforces ≥5 distinct kinds.
+ */
+export const ENVELOPE_ON_DISK_PATH = {
+    'audit-security': 'audit/security.md',
+    'audit-perf': 'audit/perf.md',
+    'karpathy-review': 'rd/karpathy-review.md',
+    'mut-report': 'dogfood-v2132/mut/mut-report.json',
+    'qa-report': 'qa/test-reports/2026-06-27-verdict-aggregator.md',
+    'prd-handoff': 'prd/handoff.md'
+};
+export const ENVELOPE_FILE_EXTENSION = {
+    'audit-security': 'md',
+    'audit-perf': 'md',
+    'karpathy-review': 'md',
+    'mut-report': 'json',
+    'qa-report': 'md',
+    'prd-handoff': 'md'
+};
+export const EDGE_CASE_VARIANTS = [
+    'chinese-colon',
+    'yaml-frontmatter-variation',
+    'double-format',
+    'empty-body',
+    'multi-findings',
+    'historical-canonical'
+];
+// ─── Public API ───────────────────────────────────────────────────────
+/**
+ * Resolve a historical capture: read the source file from disk, sanitize
+ * it, compute the checksum, write the body + `fixture.meta.json` pair.
+ *
+ * Pure orchestration — no command-line parsing here. The CLI in
+ * `scripts/fixture-capture.mjs` validates args and calls this function.
+ *
+ * @throws if the source file does not exist and `requireSource !== false`.
+ */
+export function captureHistoricalFixture(input) {
+    const requireSource = input.requireSource !== false;
+    const root = input.projectRoot ?? process.cwd();
+    const sourcePath = join(root, '.peaks', '_runtime', input.sessionId, ENVELOPE_ON_DISK_PATH[input.envelopeKind]);
+    const sourcePathPosix = sourcePath.split(sep).join('/');
+    if (!existsSync(sourcePath)) {
+        if (requireSource) {
+            throw new Error(`[peaks fixture capture] source not found: ${sourcePath}. ` +
+                `Ensure session ${input.sessionId} contains ${ENVELOPE_ON_DISK_PATH[input.envelopeKind]}.`);
+        }
+        throw new Error('source-not-found');
+    }
+    const raw = readFileSync(sourcePath, 'utf8');
+    return writeCapturedPair({
+        fixtureId: input.fixtureId,
+        envelopeKind: input.envelopeKind,
+        raw,
+        sourceOrigin: {
+            kind: 'historical-artifact',
+            path: sourcePathPosix,
+            sessionId: input.sessionId,
+            parentFixtureId: null,
+            variantCommand: null
+        },
+        edgeCases: deriveEdgeCasesFromRaw(raw),
+        outDir: input.outDir
+    });
+}
+/**
+ * Derive a variant fixture from a parent fixture body. The parent must
+ * already be a captured fixture (i.e. it has been sanitized). Variants
+ * are deterministic — same parent + same variant → identical output.
+ */
+export function captureDerivedVariant(input) {
+    const parentPath = input.parentFixturePath;
+    if (!existsSync(parentPath)) {
+        throw new Error(`[peaks fixture capture] parent fixture not found: ${parentPath}`);
+    }
+    const parentRaw = readFileSync(parentPath, 'utf8');
+    const parentMetaPath = parentPath.replace(/\.(md|json)$/, '.meta.json');
+    const parentMeta = existsSync(parentMetaPath)
+        ? JSON.parse(readFileSync(parentMetaPath, 'utf8'))
+        : null;
+    const mutated = applyEdgeCaseVariant(parentRaw, input.variant, parentMeta?.envelopeKind ?? null);
+    return writeCapturedPair({
+        fixtureId: input.fixtureId,
+        envelopeKind: parentMeta?.envelopeKind ?? inferEnvelopeFromBody(mutated),
+        raw: mutated,
+        sourceOrigin: {
+            kind: 'derived-variant',
+            path: parentPath.split(sep).join('/'),
+            sessionId: parentMeta?.sourceOrigin.sessionId ?? null,
+            parentFixtureId: parentMeta?.fixtureId ?? null,
+            variantCommand: input.variant
+        },
+        edgeCases: [input.variant],
+        outDir: input.outDir
+    });
+}
+function writeCapturedPair(input) {
+    mkdirSync(input.outDir, { recursive: true });
+    const { redacted, report } = sanitizeFixtureStrict(input.raw);
+    const ext = inferExtension(input.envelopeKind);
+    const bodyFilename = `${input.fixtureId}.${ext}`;
+    const metaFilename = `${input.fixtureId}.meta.json`;
+    const bodyPath = join(input.outDir, bodyFilename);
+    const metaPath = join(input.outDir, metaFilename);
+    const checksum = createHash('sha256').update(redacted, 'utf8').digest('hex');
+    const meta = {
+        schemaVersion: 1,
+        fixtureId: input.fixtureId,
+        envelopeKind: input.envelopeKind,
+        producer: 'peaks-fixture-capture-cli',
+        producerVersion: '2.14.0',
+        sourceOrigin: input.sourceOrigin,
+        capturedAt: new Date().toISOString(),
+        sanitization: report,
+        checksum: { algorithm: 'sha256', value: checksum },
+        edgeCases: input.edgeCases
+    };
+    writeFileSync(bodyPath, redacted, 'utf8');
+    writeFileSync(metaPath, JSON.stringify(meta, null, 2) + '\n', 'utf8');
+    return {
+        fixtureId: input.fixtureId,
+        envelopeKind: input.envelopeKind,
+        bodyPath,
+        metaPath,
+        meta
+    };
+}
+function inferExtension(kind) {
+    return ENVELOPE_FILE_EXTENSION[kind];
+}
+function inferEnvelopeFromBody(body) {
+    if (/^---\n[\s\S]*?verdict\s*:/m.test(body) && /security-audit|## Findings/i.test(body))
+        return 'audit-security';
+    if (/^---\n[\s\S]*?verdict\s*:/m.test(body) && /perf|baseline|threshold/i.test(body))
+        return 'audit-perf';
+    if (/^## Karpathy-Gate[\s\S]*?gateAction\s*:/m.test(body) || /gateAction\s*:\s*(pass|warn|block)/m.test(body))
+        return 'karpathy-review';
+    if (/^---$|schemaVersion.*2|sha256\s*:/m.test(body))
+        return 'prd-handoff';
+    if (/^verdict\s*:\s*(pass|return-to-rd|blocked)/m.test(body))
+        return 'qa-report';
+    return 'audit-security';
+}
+function deriveEdgeCasesFromRaw(raw) {
+    const cases = [];
+    if (/[：]/.test(raw))
+        cases.push('chinese-colon');
+    if (/\r\n|/.test(raw))
+        cases.push('yaml-frontmatter-variation');
+    if (cases.length === 0)
+        cases.push('historical-canonical');
+    return cases;
+}
+function applyEdgeCaseVariant(raw, variant, envelope) {
+    switch (variant) {
+        case 'chinese-colon': {
+            // The real v2.13.1 dogfood case: some real audit envelopes used
+            // Chinese fullwidth punctuation in body content (Summary,
+            // Findings descriptions). The parser still extracts the verdict
+            // from the frontmatter (ASCII `:`) but the body retains
+            // 中文冒号 — that is the exact shape the fixture must preserve.
+            // For envelopes without a `## Summary` section (karpathy, qa,
+            // prd-handoff) we apply fullwidth colon to body prose lines
+            // (those that have a colon followed by text) but never to
+            // frontmatter or parser-load-bearing `verdict:` / `passed:`
+            // lines — those stay ASCII so the parser can still extract them.
+            // Split body from frontmatter, mutate the body only.
+            const fmMatch = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+            const mutateBody = (body) => body
+                .replace(/^## Summary\n([\s\S]*?)(?=\n## |\s*$)/m, (_full, summary) => `## Summary\n${summary.replace(/:/g, '：')}`)
+                .replace(/^## Findings\n([\s\S]*?)(?=\n## |\s*$)/m, (_full, findings) => `## Findings\n${findings.replace(/:/g, '：')}`)
+                // Body prose lines with a colon: "Authors: ..." → "Authors：..."
+                // EXCLUDE parser-load-bearing lines (verdict / passed / gateAction).
+                .replace(/^([A-Za-z][A-Za-z0-9 _-]{2,40})\s*:\s*(.+)$/gm, (line, label, rest) => {
+                if (/^(verdict|passed|gateAction)$/i.test(label.trim()))
+                    return line;
+                return `${label}：${rest}`;
+            });
+            if (fmMatch !== null) {
+                const frontmatter = fmMatch[1];
+                const body = fmMatch[2];
+                return `---\n${frontmatter}\n---\n${mutateBody(body)}`;
+            }
+            return mutateBody(raw);
+        }
+        case 'yaml-frontmatter-variation': {
+            // Convert LF to CRLF in the frontmatter only. This stresses the
+            // CRLF tolerance of the parser regex (line-anchored `^...$` with
+            // multiline flag must treat `\r` as whitespace, not data).
+            // For envelopes with no frontmatter (karpathy, qa-report) we
+            // append a BOM () to the body to exercise the parser's
+            // tolerance of leading BOM.
+            const m = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+            if (m !== null) {
+                const frontmatter = m[1].replace(/\n/g, '\r\n');
+                const body = m[2];
+                return `---\r\n${frontmatter}\r\n---\n${body}`;
+            }
+            // No frontmatter — prepend a BOM and CRLF-terminate the first
+            // body line so the variant is observable.
+            return `${raw.replace(/\n/, '\r\n')}`;
+        }
+        case 'double-format': {
+            // Embed a JSON blob inside a markdown `## Embedded JSON` block.
+            // The parser must still recover the frontmatter envelope.
+            const json = JSON.stringify({
+                verdict: 'warn',
+                violations: [{ dimension: 'embed', severity: 'HIGH', file: 'embed.ts', line: 1, hint: 'embedded json' }],
+                summary: 'embedded json inside markdown'
+            }, null, 2);
+            return `${raw}\n\n## Embedded JSON\n\n\`\`\`json\n${json}\n\`\`\`\n`;
+        }
+        case 'empty-body': {
+            // For envelopes with `## Summary`/`## Findings` structure, strip
+            // everything after `## Summary` — leaves a Summary-only envelope
+            // with no Findings block. The parser must return
+            // {verdict, violations: [], summary: ...} without crashing.
+            // For envelopes without those sections, strip non-load-bearing
+            // body lines while preserving parser-load-bearing lines
+            // (verdict: / passed: / gateAction:) so the parser still
+            // extracts a verdict.
+            const idx = raw.indexOf('## Summary');
+            if (idx !== -1) {
+                const tail = raw.indexOf('\n## ', idx + 1);
+                return tail === -1 ? raw.slice(0, idx) + '## Summary\n\n(no body)\n' : raw.slice(0, tail);
+            }
+            // Karpathy / qa / handoff: keep only load-bearing body lines.
+            const fmMatch = raw.match(/^---\n([\s\S]*?)\n---\n([\s\S]*)$/);
+            const body = fmMatch !== null ? fmMatch[2] : raw;
+            const kept = body
+                .split('\n')
+                .filter((line) => /^\s*(verdict|passed|gateAction|verdict\s*：)\s*[:：]/i.test(line) || line.trim().length === 0)
+                .join('\n');
+            return fmMatch !== null
+                ? `---\n${fmMatch[1]}\n---\n${kept}`
+                : kept;
+        }
+        case 'multi-findings': {
+            // For envelopes with `## Findings` sections, duplicate the
+            // block. For envelopes without that structure, duplicate the
+            // first non-frontmatter body line so the variant is observable.
+            const m = raw.match(/(## Findings[\s\S]*?)(?=\n## |\s*$)/);
+            if (m !== null) {
+                return `${raw}\n\n${m[1]}`;
+            }
+            // No Findings section — duplicate the first body line after
+            // frontmatter (or after line 0 if no frontmatter).
+            const fmEnd = raw.match(/^---\n[\s\S]*?\n---\n/);
+            const bodyStart = fmEnd !== null ? fmEnd[0].length : 0;
+            const firstNewlineAfter = raw.indexOf('\n', bodyStart);
+            if (firstNewlineAfter === -1)
+                return raw;
+            const firstBodyLine = raw.slice(bodyStart, firstNewlineAfter + 1);
+            return `${raw}\n${firstBodyLine}`;
+        }
+        case 'historical-canonical': {
+            // No transformation — the historical capture is the canonical
+            // shape. Returned verbatim. (This branch exists so the
+            // `EdgeCaseVariant` exhaustive check is satisfied; the
+            // captureHistorical path never invokes it.)
+            return raw;
+        }
+        default: {
+            const _exhaustive = variant;
+            void _exhaustive;
+            return raw;
+        }
+    }
+}
+// ─── Sanitize rule-name re-export (so the CLI + tests don't need to
+//    import from both sanitize-service and capture-service) ───────────
+export { SANITIZE_RULE_NAMES };

package/dist/services/fixture/fixture-sanitize-service.d.ts

@@ -0,0 +1,117 @@
+/**
+ * v2.14.0 G1 AC-1.5 — Fixture sanitization service.
+ *
+ * Five sanitize rules (PRD AC-1.5 + the explicit
+ * "username path segment" extension):
+ *
+ *   1. cookie-redaction              — `Cookie: <name>=<value>` / `Set-Cookie: ...`
+ *   2. token-redaction               — Bearer tokens, JWTs, API keys (sk-/ghp-/... prefixes)
+ *   3. sso-url-redaction             — SSO redirect URLs with embedded tokens (`?token=`,
+ *                                       `?code=`, `#access_token=`)
+ *   4. personal-email-redaction      — RFC-5322-shaped personal emails
+ *   5. username-path-segment-redaction — `/Users/<name>/` and `C:\\Users\\<name>\\`
+ *                                       path segments (only the username segment,
+ *                                       not the whole path)
+ *
+ * Sanitize contract:
+ *   - Pure (no IO). `sanitizeFixture(input: string)` returns the redacted
+ *     string + a `SanitizationReport`.
+ *   - `passed: true` only when ALL rules have been applied. The capture
+ *     CLI refuses to write a fixture with `passed: false`.
+ *   - Each rule produces a stable replacement token (`<REDACTED-<rule}>`)
+ *     so the test suite can grep for redaction without depending on
+ *     the original (potentially sensitive) values.
+ *
+ * Why a separate service (not inline in capture CLI):
+ *   - Unit-testable in isolation. The PRD AC-1.5 mandate is "tested",
+ *     and 5 sanitize rules need 5+ test cases per rule. Keeping the
+ *     logic in a service makes the tests trivial.
+ *   - Re-usable by future capture tools (`peaks fixture redact`,
+ *     `peaks fixture snapshot-share`) without forking logic.
+ */
+import { z } from 'zod';
+export type SanitizeRuleName = 'cookie-redaction' | 'token-redaction' | 'sso-url-redaction' | 'personal-email-redaction' | 'username-path-segment-redaction';
+export declare const SANITIZE_RULE_NAMES: ReadonlyArray<SanitizeRuleName>;
+/**
+ * A single sanitize rule is a `name + regex + replacement`. Rules are
+ * applied in array order; later rules see the output of earlier ones.
+ * This matters for `sso-url-redaction` (runs after `token-redaction`
+ * so the token in `?token=...` is not double-redacted).
+ */
+export interface SanitizeRule {
+    readonly name: SanitizeRuleName;
+    readonly pattern: RegExp;
+    readonly replacement: string;
+}
+export declare const SANITIZE_RULES: ReadonlyArray<SanitizeRule>;
+export declare const SanitizationIssueSchema: z.ZodObject<{
+    rule: z.ZodString;
+    match: z.ZodString;
+    position: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    match: string;
+    rule: string;
+    position: number;
+}, {
+    match: string;
+    rule: string;
+    position: number;
+}>;
+export declare const SanitizationReportSchema: z.ZodObject<{
+    passed: z.ZodBoolean;
+    rulesApplied: z.ZodArray<z.ZodEnum<["cookie-redaction", "token-redaction", "sso-url-redaction", "personal-email-redaction", "username-path-segment-redaction"]>, "many">;
+    issues: z.ZodArray<z.ZodObject<{
+        rule: z.ZodString;
+        match: z.ZodString;
+        position: z.ZodNumber;
+    }, "strip", z.ZodTypeAny, {
+        match: string;
+        rule: string;
+        position: number;
+    }, {
+        match: string;
+        rule: string;
+        position: number;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    issues: {
+        match: string;
+        rule: string;
+        position: number;
+    }[];
+    passed: boolean;
+    rulesApplied: ("cookie-redaction" | "token-redaction" | "sso-url-redaction" | "personal-email-redaction" | "username-path-segment-redaction")[];
+}, {
+    issues: {
+        match: string;
+        rule: string;
+        position: number;
+    }[];
+    passed: boolean;
+    rulesApplied: ("cookie-redaction" | "token-redaction" | "sso-url-redaction" | "personal-email-redaction" | "username-path-segment-redaction")[];
+}>;
+export type SanitizationIssue = z.infer<typeof SanitizationIssueSchema>;
+export type SanitizationReport = z.infer<typeof SanitizationReportSchema>;
+/**
+ * Apply all sanitize rules in order. Returns the redacted string and
+ * a structured report. `passed` is `true` iff every rule from
+ * `SANITIZE_RULE_NAMES` was applied (which it always is — the boolean
+ * exists so future rules can short-circuit, and to give the CLI a
+ * consistent contract surface).
+ *
+ * Pure function: no IO, no side effects. Safe to call in a tight loop.
+ */
+export declare function sanitizeFixture(input: string): {
+    redacted: string;
+    report: SanitizationReport;
+};
+/**
+ * Sanitize + structural sanity check. Refuses to produce a `passed:
+ * true` report if the redacted output is empty, has zero newlines, or
+ * is identical to the input AND the input contains any of the
+ * forbidden patterns. This guards against accidental no-op sanitization.
+ */
+export declare function sanitizeFixtureStrict(input: string): {
+    redacted: string;
+    report: SanitizationReport;
+};

package/dist/services/fixture/fixture-sanitize-service.js

@@ -0,0 +1,161 @@
+/**
+ * v2.14.0 G1 AC-1.5 — Fixture sanitization service.
+ *
+ * Five sanitize rules (PRD AC-1.5 + the explicit
+ * "username path segment" extension):
+ *
+ *   1. cookie-redaction              — `Cookie: <name>=<value>` / `Set-Cookie: ...`
+ *   2. token-redaction               — Bearer tokens, JWTs, API keys (sk-/ghp-/... prefixes)
+ *   3. sso-url-redaction             — SSO redirect URLs with embedded tokens (`?token=`,
+ *                                       `?code=`, `#access_token=`)
+ *   4. personal-email-redaction      — RFC-5322-shaped personal emails
+ *   5. username-path-segment-redaction — `/Users/<name>/` and `C:\\Users\\<name>\\`
+ *                                       path segments (only the username segment,
+ *                                       not the whole path)
+ *
+ * Sanitize contract:
+ *   - Pure (no IO). `sanitizeFixture(input: string)` returns the redacted
+ *     string + a `SanitizationReport`.
+ *   - `passed: true` only when ALL rules have been applied. The capture
+ *     CLI refuses to write a fixture with `passed: false`.
+ *   - Each rule produces a stable replacement token (`<REDACTED-<rule}>`)
+ *     so the test suite can grep for redaction without depending on
+ *     the original (potentially sensitive) values.
+ *
+ * Why a separate service (not inline in capture CLI):
+ *   - Unit-testable in isolation. The PRD AC-1.5 mandate is "tested",
+ *     and 5 sanitize rules need 5+ test cases per rule. Keeping the
+ *     logic in a service makes the tests trivial.
+ *   - Re-usable by future capture tools (`peaks fixture redact`,
+ *     `peaks fixture snapshot-share`) without forking logic.
+ */
+import { z } from 'zod';
+export const SANITIZE_RULE_NAMES = [
+    'cookie-redaction',
+    'token-redaction',
+    'sso-url-redaction',
+    'personal-email-redaction',
+    'username-path-segment-redaction'
+];
+export const SANITIZE_RULES = [
+    {
+        name: 'cookie-redaction',
+        // Match `Cookie: name=value` and `Set-Cookie: name=value; ...` headers.
+        // Also match bare `name=value` cookie fragments inside JSON for fixtures
+        // that originated from a JSON debug capture.
+        pattern: /(?:set-cookie|cookie)\s*:\s*([^;\r\n]+)/gi,
+        replacement: '<REDACTED-cookie>'
+    },
+    {
+        name: 'token-redaction',
+        // Bearer tokens (Authorization: Bearer ...), JWTs (xxx.yyy.zzz),
+        // and well-known API-key prefixes.
+        pattern: /(?:bearer\s+)[a-zA-Z0-9._\-+/=]{12,}|eyJ[a-zA-Z0-9._\-+/=]{20,}|(?:sk-|ghp_|gho_|ghs_|ghu_|ghr_|github_pat_|xox[abprs]-|AIza[0-9A-Za-z_\-]{35})[A-Za-z0-9_\-]+/gi,
+        replacement: '<REDACTED-token>'
+    },
+    {
+        name: 'sso-url-redaction',
+        // SSO callback URLs with embedded tokens via `?` (e.g. `?token=`,
+        // `?code=`, `?access_token=`) or via fragment `#access_token=`.
+        pattern: /\bhttps?:\/\/[^\s"'<>]*(?:[?&](?:token|code|access_token|id_token|assertion)=[^&\s"'<>]*|#[^/\s"'<>]*access_token=[^\s"'<>]*)/gi,
+        replacement: '<REDACTED-sso-url>'
+    },
+    {
+        name: 'personal-email-redaction',
+        // RFC-5322-ish local-part @ domain.tld. Restrict TLD to letters
+        // (length 2-24) to avoid false positives like `pr-1234` (no `@`).
+        pattern: /\b[A-Za-z0-9._%+\-]{1,64}@[A-Za-z0-9.\-]{1,255}\.[A-Za-z]{2,24}\b/g,
+        replacement: '<REDACTED-email>'
+    },
+    {
+        name: 'username-path-segment-redaction',
+        // `/Users/<name>/` on POSIX and `C:\\Users\\<name>\\` / `\\Users\\<name>\\`
+        // on Windows. The replacement PRESERVES the path separator that
+        // precedes the username (slash or backslash) so the rest of the
+        // path stays intact and the fixture still parses structurally.
+        pattern: /((?:\/Users\/|\/home\/|C:\\Users\\|\\\\Users\\|\\Users\\|\\home\\))[A-Za-z0-9._\-]+/g,
+        replacement: '$1<REDACTED-user>'
+    }
+];
+// ─── Zod schemas ──────────────────────────────────────────────────────
+export const SanitizationIssueSchema = z.object({
+    rule: z.string(),
+    match: z.string(),
+    position: z.number().int().nonnegative()
+});
+export const SanitizationReportSchema = z.object({
+    passed: z.boolean(),
+    rulesApplied: z.array(z.enum([
+        'cookie-redaction',
+        'token-redaction',
+        'sso-url-redaction',
+        'personal-email-redaction',
+        'username-path-segment-redaction'
+    ])),
+    issues: z.array(SanitizationIssueSchema)
+});
+// ─── Public API ───────────────────────────────────────────────────────
+/**
+ * Apply all sanitize rules in order. Returns the redacted string and
+ * a structured report. `passed` is `true` iff every rule from
+ * `SANITIZE_RULE_NAMES` was applied (which it always is — the boolean
+ * exists so future rules can short-circuit, and to give the CLI a
+ * consistent contract surface).
+ *
+ * Pure function: no IO, no side effects. Safe to call in a tight loop.
+ */
+export function sanitizeFixture(input) {
+    let redacted = input;
+    const issues = [];
+    const rulesApplied = [];
+    for (const rule of SANITIZE_RULES) {
+        rulesApplied.push(rule.name);
+        // Reset the regex (since they are global + stateful across calls
+        // when reused without resetting lastIndex).
+        rule.pattern.lastIndex = 0;
+        const matches = redacted.matchAll(rule.pattern);
+        let localCount = 0;
+        for (const m of matches) {
+            // Only record the redacted form (not the original sensitive value)
+            // to avoid leaking the secret back into the report.
+            issues.push({
+                rule: rule.name,
+                match: rule.replacement,
+                position: typeof m.index === 'number' ? m.index : 0
+            });
+            localCount++;
+        }
+        if (localCount > 0) {
+            redacted = redacted.replace(rule.pattern, rule.replacement);
+        }
+    }
+    return {
+        redacted,
+        report: {
+            passed: true,
+            rulesApplied,
+            issues
+        }
+    };
+}
+/**
+ * Sanitize + structural sanity check. Refuses to produce a `passed:
+ * true` report if the redacted output is empty, has zero newlines, or
+ * is identical to the input AND the input contains any of the
+ * forbidden patterns. This guards against accidental no-op sanitization.
+ */
+export function sanitizeFixtureStrict(input) {
+    const result = sanitizeFixture(input);
+    const looksSanitized = result.redacted !== input ||
+        !SANITIZE_RULES.some((r) => {
+            r.pattern.lastIndex = 0;
+            return r.pattern.test(input);
+        });
+    if (input.length === 0 || result.redacted.length === 0 || !looksSanitized) {
+        return {
+            redacted: result.redacted,
+            report: { ...result.report, passed: false }
+        };
+    }
+    return result;
+}

package/dist/services/fixture/index.d.ts

@@ -0,0 +1,8 @@
+/**
+ * v2.14.0 G1 — Fixture services barrel.
+ *
+ * Re-exports both the sanitize + capture services so consumers (CLI,
+ * tests) import from one path.
+ */
+export { sanitizeFixture, sanitizeFixtureStrict, SANITIZE_RULES, SANITIZE_RULE_NAMES, SanitizationReportSchema, SanitizationIssueSchema, type SanitizeRule, type SanitizeRuleName, type SanitizationReport, type SanitizationIssue } from './fixture-sanitize-service.js';
+export { captureHistoricalFixture, captureDerivedVariant, ENVELOPE_KINDS, ENVELOPE_ON_DISK_PATH, ENVELOPE_FILE_EXTENSION, EDGE_CASE_VARIANTS, type EnvelopeKind, type EdgeCaseVariant, type HistoricalCaptureInput, type DerivedVariantInput, type CaptureInput, type CapturedFixture, type FixtureMeta } from './fixture-capture-service.js';

package/dist/services/fixture/index.js

@@ -0,0 +1,8 @@
+/**
+ * v2.14.0 G1 — Fixture services barrel.
+ *
+ * Re-exports both the sanitize + capture services so consumers (CLI,
+ * tests) import from one path.
+ */
+export { sanitizeFixture, sanitizeFixtureStrict, SANITIZE_RULES, SANITIZE_RULE_NAMES, SanitizationReportSchema, SanitizationIssueSchema } from './fixture-sanitize-service.js';
+export { captureHistoricalFixture, captureDerivedVariant, ENVELOPE_KINDS, ENVELOPE_ON_DISK_PATH, ENVELOPE_FILE_EXTENSION, EDGE_CASE_VARIANTS } from './fixture-capture-service.js';