wingfoil 0.2.1

package/dist/validation/secret-scan.js

@@ -0,0 +1,367 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_IGNORE_FILE = exports.SCAN_SURFACE_ROOTS = exports.SECRET_PATTERNS = void 0;
+exports.scanText = scanText;
+exports.isBinaryContent = isBinaryContent;
+exports.loadIgnoreGlobs = loadIgnoreGlobs;
+exports.matchesIgnoreGlob = matchesIgnoreGlob;
+exports.scanProjectSurface = scanProjectSurface;
+/**
+ * Secret/credential hygiene scan (task-043-secret-credential-hygiene, REQ-SEC-08), built to
+ * `spec-007-secret-hygiene-patterns` — the single canonical pattern set and scan procedure spec-007
+ * requires so no future call site (a commit-time gate, `task-044`'s `init` integrity check, a future
+ * `wingfoil audit`) re-implements its own regex list and lets the patterns drift.
+ *
+ * `SECRET_PATTERNS` reproduces spec-007 §2's ten named rules; each JS `RegExp` below carries a
+ * comment quoting the exact spec-007 YAML `regex:` string it implements. Two of spec-007's patterns
+ * use the PCRE inline mode-modifier syntax `(?i)`/`(?im)` in their YAML text — JS `RegExp` has no
+ * such inline syntax (`new RegExp('(?i)...')` throws `SyntaxError`) — so that flag is moved to the
+ * equivalent JS `i` flag instead. This is a mechanical syntax translation, not a semantic rewrite:
+ * the matched shape is unchanged, so it satisfies spec-007's Consequences-section instruction to
+ * "reproduce the pattern table in §2 verbatim (or import it as data)" rather than hand-roll
+ * alternative regexes.
+ */
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const path_1 = require("path");
+/**
+ * The canonical secret-hygiene pattern set (spec-007 §2), in the fixed declaration order every scan
+ * must evaluate patterns in (determinism, REQ-SYS-07, spec-007 §4 step 3). Adding, removing, or
+ * re-classifying a pattern is a revision to spec-007's §2 table, not a call-site code change.
+ */
+exports.SECRET_PATTERNS = [
+    {
+        id: 'private-key-pem',
+        description: 'PEM-encoded private key header',
+        severity: 'block',
+        // spec-007 §2: '-----BEGIN (RSA |EC |DSA |OPENSSH |PGP )?PRIVATE KEY-----'
+        regex: /-----BEGIN (RSA |EC |DSA |OPENSSH |PGP )?PRIVATE KEY-----/,
+    },
+    {
+        id: 'generic-api-key-assignment',
+        description: 'Variable assignment that looks like an API key/secret/token',
+        severity: 'block',
+        // spec-007 §2 (case-insensitive per its `(?i)` marker):
+        // '(api[_-]?key|secret|token|passwd|password)\s*[:=]\s*["\']?[A-Za-z0-9_\-\/+=]{16,}["\']?'
+        regex: /(api[_-]?key|secret|token|passwd|password)\s*[:=]\s*["']?[A-Za-z0-9_\-/+=]{16,}["']?/i,
+    },
+    {
+        id: 'aws-access-key-id',
+        description: 'AWS access key ID shape',
+        severity: 'block',
+        // spec-007 §2: '\b(AKIA|ASIA|AGPA|AIDA|AROA|AIPA|ANPA|ANVA|ASCA)[0-9A-Z]{16}\b'
+        regex: /\b(AKIA|ASIA|AGPA|AIDA|AROA|AIPA|ANPA|ANVA|ASCA)[0-9A-Z]{16}\b/,
+    },
+    {
+        id: 'aws-secret-access-key',
+        description: "AWS secret access key assignment (40-char base64-ish, near 'aws' or 'secret')",
+        severity: 'block',
+        // spec-007 §2 (case-insensitive per its `(?i)` marker):
+        // 'aws.{0,20}(secret|key).{0,5}[:=]\s*["\']?[A-Za-z0-9\/+=]{40}["\']?'
+        regex: /aws.{0,20}(secret|key).{0,5}[:=]\s*["']?[A-Za-z0-9/+=]{40}["']?/i,
+    },
+    {
+        id: 'gcp-service-account-key',
+        description: 'GCP service-account JSON key fragment',
+        severity: 'block',
+        // spec-007 §2: '"type"\s*:\s*"service_account"|"private_key_id"\s*:\s*"[0-9a-f]{40}"'
+        regex: /"type"\s*:\s*"service_account"|"private_key_id"\s*:\s*"[0-9a-f]{40}"/,
+    },
+    {
+        id: 'github-token',
+        description: 'GitHub personal access / app / fine-grained token',
+        severity: 'block',
+        // spec-007 §2: '\b(ghp|gho|ghu|ghs|ghr|github_pat)_[A-Za-z0-9_]{36,}\b'
+        regex: /\b(ghp|gho|ghu|ghs|ghr|github_pat)_[A-Za-z0-9_]{36,}\b/,
+    },
+    {
+        id: 'slack-token',
+        description: 'Slack bot/user/app token',
+        severity: 'block',
+        // spec-007 §2: '\bxox[baprs]-[A-Za-z0-9-]{10,}\b'
+        regex: /\bxox[baprs]-[A-Za-z0-9-]{10,}\b/,
+    },
+    {
+        id: 'jwt-like',
+        description: 'JSON Web Token shape (header.payload.signature, base64url segments)',
+        // promoted warn → block by dl-036-secret-scan-warn-severity-vs-req-sec-08 (spec-007 §2 amended)
+        severity: 'block',
+        // spec-007 §2: '\beyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\b'
+        regex: /\beyJ[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\.[A-Za-z0-9_-]{5,}\b/,
+    },
+    {
+        id: 'generic-high-entropy-string',
+        description: 'Long contiguous base64/hex-alphabet token assigned to a suspicious key name',
+        severity: 'warn',
+        // spec-007 §2 (case-insensitive per its `(?i)` marker):
+        // '(auth|credential|bearer)\s*[:=]\s*["\']?[A-Za-z0-9_\-\/+=]{24,}["\']?'
+        regex: /(auth|credential|bearer)\s*[:=]\s*["']?[A-Za-z0-9_\-/+=]{24,}["']?/i,
+    },
+    {
+        id: 'dotenv-style-secret-line',
+        description: '.env-style KEY=VALUE line where KEY names a credential',
+        // promoted warn → block by dl-036-secret-scan-warn-severity-vs-req-sec-08 (spec-007 §2 amended)
+        severity: 'block',
+        // spec-007 §2 (case-insensitive per its `(?im)` marker; the `m` is a no-op here because the
+        // scan procedure already evaluates one line at a time, so `^`/`$` anchor to that line either way):
+        // '^[A-Z0-9_]*(SECRET|TOKEN|PASSWORD|API_KEY|PRIVATE_KEY)[A-Z0-9_]*\s*=\s*\S+'
+        regex: /^[A-Z0-9_]*(SECRET|TOKEN|PASSWORD|API_KEY|PRIVATE_KEY)[A-Z0-9_]*\s*=\s*\S+/i,
+    },
+];
+const FENCE_DELIMITER_RE = /^`{3,}/;
+const FENCE_EXEMPT_MARKERS = new Set(['<!-- example -->', '<!-- placeholder -->']);
+/** Literal placeholder values spec-007 §3 exempts outright (case-insensitive, whole-value match). */
+const PLACEHOLDER_LITERALS = new Set(['REDACTED', 'PLACEHOLDER', 'EXAMPLE', 'XXXXXXXXXXXXXXXX']);
+/** True for a value that is entirely `x`/`X`/`*` repeats, or one of spec-007 §3's literal strings. */
+function isPlaceholderValue(value) {
+    if (value.length === 0)
+        return false;
+    if (/^[xX*]+$/.test(value))
+        return true;
+    return PLACEHOLDER_LITERALS.has(value.toUpperCase());
+}
+/**
+ * Best-effort extraction of the "value" side of a `key: value` / `key=value` match, for the
+ * placeholder-value exclusion (spec-007 §3). Takes everything after the match's last `:`/`=` (the
+ * separator every value-shaped pattern in §2 requires), trims whitespace, and strips one layer of
+ * surrounding quotes. Falls back to the whole match when no separator is present (vendor-prefixed
+ * shapes like `aws-access-key-id`/`github-token` have no separate value to isolate — the placeholder
+ * exclusion legitimately does not apply to those; the fenced-example / ignore-path exclusions do).
+ */
+function extractCandidateValue(matchText) {
+    const lastEquals = matchText.lastIndexOf('=');
+    const lastColon = matchText.lastIndexOf(':');
+    const sepIndex = Math.max(lastEquals, lastColon);
+    const raw = sepIndex >= 0 ? matchText.slice(sepIndex + 1) : matchText;
+    return raw.trim().replace(/^["']/, '').replace(/["']$/, '');
+}
+/** Every match of `pattern.regex` on a single `line`, as unexempt {@link SecretFinding}s. */
+function matchLine(line, pattern, lineNumber, filePath) {
+    const flags = pattern.regex.flags.includes('g') ? pattern.regex.flags : `${pattern.regex.flags}g`;
+    const global = new RegExp(pattern.regex.source, flags);
+    const findings = [];
+    let match;
+    while ((match = global.exec(line)) !== null) {
+        findings.push({
+            patternId: pattern.id,
+            severity: pattern.severity,
+            file: filePath,
+            line: lineNumber,
+            column: match.index + 1,
+            excerpt: match[0],
+        });
+        if (match[0].length === 0)
+            global.lastIndex += 1; // guard a zero-length match's infinite loop
+    }
+    return findings;
+}
+/**
+ * Scan one file's already-decoded text content (spec-007 §4): evaluate {@link SECRET_PATTERNS} in
+ * declared order against every line, apply the §3 exclusions, and classify each surviving finding by
+ * severity. This is the seam a future commit-time gate or `task-044`'s `init` integrity check calls
+ * per file-about-to-be-written/committed (spec-007 §4 step 5).
+ */
+function scanText(content, filePath, options = {}) {
+    const lines = content.split(/\r\n|\r|\n/);
+    const blocking = [];
+    const warnings = [];
+    const info = [];
+    let inFence = false;
+    let fenceExempt = false;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        if (FENCE_DELIMITER_RE.test(line.trim())) {
+            if (!inFence) {
+                const prevLine = i > 0 ? (lines[i - 1] ?? '').trim().toLowerCase() : '';
+                fenceExempt = FENCE_EXEMPT_MARKERS.has(prevLine);
+                inFence = true;
+            }
+            else {
+                inFence = false;
+                fenceExempt = false;
+            }
+            continue;
+        }
+        for (const pattern of exports.SECRET_PATTERNS) {
+            for (const finding of matchLine(line, pattern, i + 1, filePath)) {
+                const valueExempt = isPlaceholderValue(extractCandidateValue(finding.excerpt));
+                if (fenceExempt || valueExempt || options.pathIgnored) {
+                    const exemptReason = fenceExempt
+                        ? 'fenced-example'
+                        : valueExempt
+                            ? 'placeholder-value'
+                            : 'ignore-path';
+                    info.push({ ...finding, exemptReason });
+                }
+                else if (finding.severity === 'block') {
+                    blocking.push(finding);
+                }
+                else {
+                    warnings.push(finding);
+                }
+            }
+        }
+    }
+    return { blocking, warnings, info, filesScanned: 1 };
+}
+/** Concatenate {@link ScanResult}s (file iteration order — deterministic when the caller's is). */
+function mergeScanResults(results) {
+    return {
+        blocking: results.flatMap((r) => r.blocking),
+        warnings: results.flatMap((r) => r.warnings),
+        info: results.flatMap((r) => r.info),
+        filesScanned: results.reduce((total, r) => total + r.filesScanned, 0),
+    };
+}
+/** Null-byte sniff on the first 8KB (spec-007 §1) — binary files are out of scan scope. */
+function isBinaryContent(buf) {
+    const head = buf.subarray(0, 8192);
+    return head.includes(0);
+}
+/**
+ * Default scan-surface roots (spec-007 §1): `.wingfoil/` once `init` exists, plus the current
+ * self-hosted analog (`docs/self/.wingfoil/`, `docs/self/docs/04_memory/`) "applied by analogy until
+ * the tool-managed root exists". A root with no indexed files contributes nothing, so
+ * {@link scanProjectSurface} is safe to call before `init` has ever run.
+ */
+exports.SCAN_SURFACE_ROOTS = ['.wingfoil', 'docs/self/.wingfoil', 'docs/self/docs/04_memory'];
+/** Default path (root-relative) of the `security-ignore` glob list (spec-007 §3). */
+exports.DEFAULT_IGNORE_FILE = '.wingfoil/security-ignore';
+/** `git ls-files -s` mode of a gitlink (submodule commit) — not a blob, nothing to read. */
+const GITLINK_MODE = '160000';
+/** One `git ls-files -s -z` record: mode, object id, stage, then a tab and the raw path. */
+const INDEX_RECORD_RE = /^(\d+) ([0-9a-f]+) \d\t([\s\S]+)$/;
+/**
+ * List every indexed (tracked or staged, spec-007 §1) blob under `surfaceRoots`, in git's path order.
+ * `-z` keeps paths unquoted; gitlinks are skipped. An unmerged path contributes one entry per conflict
+ * stage — each is content that could be committed. A surface root absent from the index yields no
+ * entries (git accepts an unmatched pathspec), so there is no on-disk existence check: the index is
+ * the only source. Mirrors `src/storage/commit.ts`'s `execFileSync('git', ['-C', root, ...])` style.
+ */
+function listIndexedBlobs(root, surfaceRoots) {
+    if (surfaceRoots.length === 0)
+        return [];
+    const out = (0, child_process_1.execFileSync)('git', ['-C', root, 'ls-files', '-s', '-z', '--', ...surfaceRoots], {
+        encoding: 'utf-8',
+        env: process.env,
+    });
+    const entries = [];
+    for (const record of out.split('\0')) {
+        // `<mode> <object id> <stage>\t<path>`; the trailing empty record after the last NUL never matches
+        const match = INDEX_RECORD_RE.exec(record);
+        if (match === null || match[1] === GITLINK_MODE)
+            continue;
+        entries.push({ path: match[3], blob: match[2] });
+    }
+    return entries;
+}
+/**
+ * Read every entry's staged bytes from the object store in ONE `git cat-file --batch` call, preserving
+ * `entries` order. Each response is `<id> blob <size>\n<size bytes>\n`; any other header (e.g.
+ * `<id> missing`) means the index names an object the repository does not have, which is corruption,
+ * not a scan result — it throws.
+ */
+function readIndexedBlobs(root, entries) {
+    if (entries.length === 0)
+        return [];
+    const out = (0, child_process_1.execFileSync)('git', ['-C', root, 'cat-file', '--batch'], {
+        input: `${entries.map((entry) => entry.blob).join('\n')}\n`,
+        env: process.env,
+        maxBuffer: Number.POSITIVE_INFINITY,
+    });
+    let offset = 0;
+    return entries.map(({ path, blob }) => {
+        const headerEnd = out.indexOf(0x0a, offset);
+        const header = out.subarray(offset, headerEnd).toString('utf-8');
+        const match = /^([0-9a-f]+) blob (\d+)$/.exec(header);
+        if (match === null || match[1] !== blob) {
+            throw new Error(`git cat-file could not read the indexed blob of ${path}: "${header}"`);
+        }
+        const start = headerEnd + 1;
+        const end = start + Number(match[2]);
+        offset = end + 1; // skip the LF that terminates each object's content
+        return { path, content: out.subarray(start, end) };
+    });
+}
+/**
+ * Parse a `security-ignore` file (spec-007 §3): one glob per line, git-attribute-style — blank lines
+ * and lines starting with `#` are ignored. Returns `[]` when `ignoreFilePath` does not exist (no
+ * ignore list configured is not an error).
+ */
+function loadIgnoreGlobs(ignoreFilePath) {
+    if (!(0, fs_1.existsSync)(ignoreFilePath))
+        return [];
+    return (0, fs_1.readFileSync)(ignoreFilePath, 'utf-8')
+        .split(/\r\n|\r|\n/)
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0 && !line.startsWith('#'));
+}
+/** Escape one non-wildcard character for safe insertion into a glob-derived `RegExp` source. */
+function escapeGlobLiteral(ch) {
+    return /[.*+?^${}()|[\]\\]/.test(ch) ? `\\${ch}` : ch;
+}
+/** Compile one `security-ignore` glob line (`*`, `**`, `?`) to a `RegExp` matching a full root-relative path. */
+function globToRegExp(glob) {
+    let source = '^';
+    for (let i = 0; i < glob.length; i++) {
+        const ch = glob[i];
+        if (ch === '*') {
+            if (glob[i + 1] === '*') {
+                source += '.*';
+                i += 1;
+                if (glob[i + 1] === '/')
+                    i += 1; // `**/` also swallows the following separator
+            }
+            else {
+                source += '[^/]*';
+            }
+        }
+        else if (ch === '?') {
+            source += '[^/]';
+        }
+        else if (ch !== undefined) {
+            source += escapeGlobLiteral(ch);
+        }
+    }
+    source += '$';
+    return new RegExp(source);
+}
+/** True when root-relative `filePath` matches any glob in `globs` (spec-007 §3 ignore-path exclusion). */
+function matchesIgnoreGlob(filePath, globs) {
+    return globs.some((glob) => globToRegExp(glob).test(filePath));
+}
+/**
+ * Run the full scan procedure (spec-007 §4) over `root`'s tracked/staged content under the scan
+ * surface (§1): list the indexed blobs via `git ls-files -s`, read them from the object store, skip
+ * binaries (§1), apply the `security-ignore` list (§3) as a per-file `pathIgnored` flag, and scan every
+ * remaining file's text with {@link scanText}.
+ *
+ * **Contract — the git index, not the working tree (`bug-015`).** Both the file list and the content
+ * come from the index: the scan judges exactly what the next commit would contain, which is what the
+ * pre-commit / pre-publish gate of spec-007 §4 step 5 must judge. So a file deleted on disk but still
+ * indexed is scanned from its staged blob; a staged deletion is not listed; an unstaged edit — clean or
+ * leaky — is not seen until it is staged. (Before `bug-015` the list came from the index but the bytes
+ * from disk, so an unstaged deletion threw `ENOENT` and took the whole scan down.) The
+ * `security-ignore` file itself is read from disk: it configures the scan, it is not scanned content.
+ * `root` must be a git work tree.
+ *
+ * This is the concrete entry point the REQ-SEC-08 Fit Criterion ("a scan of committed `.wingfoil/`
+ * content matches 0 known secret patterns") is checkable against: `scanProjectSurface(root).blocking`
+ * must be empty for a hygienic project. Pair that with {@link ScanResult.filesScanned} — an empty
+ * `blocking` list only means "clean" once it is known that files were actually read; `filesScanned`
+ * is `0` when no surface root exists or the index is empty under it.
+ */
+function scanProjectSurface(root, options = {}) {
+    const surfaceRoots = options.surfaceRoots ?? exports.SCAN_SURFACE_ROOTS;
+    const ignoreFilePath = options.ignoreFilePath ?? exports.DEFAULT_IGNORE_FILE;
+    const ignoreGlobs = loadIgnoreGlobs((0, path_1.join)(root, ignoreFilePath));
+    const results = [];
+    for (const { path, content } of readIndexedBlobs(root, listIndexedBlobs(root, surfaceRoots))) {
+        if (isBinaryContent(content))
+            continue;
+        const pathIgnored = matchesIgnoreGlob(path, ignoreGlobs);
+        results.push(scanText(content.toString('utf-8'), path, { pathIgnored }));
+    }
+    return mergeScanResults(results);
+}
+//# sourceMappingURL=secret-scan.js.map

package/dist/validation/secret-scan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-scan.js","sourceRoot":"","sources":["../../src/validation/secret-scan.ts"],"names":[],"mappings":";;;AA8OA,4BA2CC;AAaD,0CAGC;AAoFD,0CAMC;AA+BD,8CAEC;AA+BD,gDAYC;AA/cD;;;;;;;;;;;;;;GAcG;AACH,iDAA6C;AAC7C,2BAA8C;AAC9C,+BAA4B;AAiB5B;;;;GAIG;AACU,QAAA,eAAe,GAA6B;IACvD;QACE,EAAE,EAAE,iBAAiB;QACrB,WAAW,EAAE,gCAAgC;QAC7C,QAAQ,EAAE,OAAO;QACjB,2EAA2E;QAC3E,KAAK,EAAE,2DAA2D;KACnE;IACD;QACE,EAAE,EAAE,4BAA4B;QAChC,WAAW,EAAE,6DAA6D;QAC1E,QAAQ,EAAE,OAAO;QACjB,wDAAwD;QACxD,4FAA4F;QAC5F,KAAK,EAAE,uFAAuF;KAC/F;IACD;QACE,EAAE,EAAE,mBAAmB;QACvB,WAAW,EAAE,yBAAyB;QACtC,QAAQ,EAAE,OAAO;QACjB,gFAAgF;QAChF,KAAK,EAAE,gEAAgE;KACxE;IACD;QACE,EAAE,EAAE,uBAAuB;QAC3B,WAAW,EAAE,+EAA+E;QAC5F,QAAQ,EAAE,OAAO;QACjB,wDAAwD;QACxD,uEAAuE;QACvE,KAAK,EAAE,kEAAkE;KAC1E;IACD;QACE,EAAE,EAAE,yBAAyB;QAC7B,WAAW,EAAE,uCAAuC;QACpD,QAAQ,EAAE,OAAO;QACjB,sFAAsF;QACtF,KAAK,EAAE,sEAAsE;KAC9E;IACD;QACE,EAAE,EAAE,cAAc;QAClB,WAAW,EAAE,mDAAmD;QAChE,QAAQ,EAAE,OAAO;QACjB,wEAAwE;QACxE,KAAK,EAAE,wDAAwD;KAChE;IACD;QACE,EAAE,EAAE,aAAa;QACjB,WAAW,EAAE,0BAA0B;QACvC,QAAQ,EAAE,OAAO;QACjB,kDAAkD;QAClD,KAAK,EAAE,kCAAkC;KAC1C;IACD;QACE,EAAE,EAAE,UAAU;QACd,WAAW,EAAE,qEAAqE;QAClF,gGAAgG;QAChG,QAAQ,EAAE,OAAO;QACjB,gFAAgF;QAChF,KAAK,EAAE,gEAAgE;KACxE;IACD;QACE,EAAE,EAAE,6BAA6B;QACjC,WAAW,EAAE,6EAA6E;QAC1F,QAAQ,EAAE,MAAM;QAChB,wDAAwD;QACxD,0EAA0E;QAC1E,KAAK,EAAE,qEAAqE;KAC7E;IACD;QACE,EAAE,EAAE,0BAA0B;QAC9B,WAAW,EAAE,wDAAwD;QACrE,gGAAgG;QAChG,QAAQ,EAAE,OAAO;QACjB,4FAA4F;QAC5F,mGAAmG;QACnG,+EAA+E;QAC/E,KAAK,EAAE,6EAA6E;KACrF;CACF,CAAC;AA6DF,MAAM,kBAAkB,GAAG,QAAQ,CAAC;AACpC,MAAM,oBAAoB,GAAG,IAAI,GAAG,CAAC,CAAC,kBAAkB,EAAE,sBAAsB,CAAC,CAAC,CAAC;AAEnF,qGAAqG;AACrG,MAAM,oBAAoB,GAAG,IAAI,GAAG,CAAC,CAAC,UAAU,EAAE,aAAa,EAAE,SAAS,EAAE,kBAAkB,CAAC,CAAC,CAAC;AAEjG,sGAAsG;AACtG,SAAS,kBAAkB,CAAC,KAAa;IACvC,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACrC,IAAI,UAAU,CAAC,IAAI,CAAC,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IACxC,OAAO,oBAAoB,CAAC,GAAG,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;AACvD,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,qBAAqB,CAAC,SAAiB;IAC9C,MAAM,UAAU,GAAG,SAAS,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAC9C,MAAM,SAAS,GAAG,SAAS,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;IAC7C,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;IACjD,MAAM,GAAG,GAAG,QAAQ,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,KAAK,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IACtE,OAAO,GAAG,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC;AAC9D,CAAC;AAED,6FAA6F;AAC7F,SAAS,SAAS,CAChB,IAAY,EACZ,OAAsB,EACtB,UAAkB,EAClB,QAAgB;IAEhB,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,KAAK,CAAC,KAAK,GAAG,CAAC;IAClG,MAAM,MAAM,GAAG,IAAI,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IACvD,MAAM,QAAQ,GAAoB,EAAE,CAAC;IACrC,IAAI,KAA6B,CAAC;IAClC,OAAO,CAAC,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QAC5C,QAAQ,CAAC,IAAI,CAAC;YACZ,SAAS,EAAE,OAAO,CAAC,EAAE;YACrB,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,IAAI,EAAE,QAAQ;YACd,IAAI,EAAE,UAAU;YAChB,MAAM,EAAE,KAAK,CAAC,KAAK,GAAG,CAAC;YACvB,OAAO,EAAE,KAAK,CAAC,CAAC,CAAC;SAClB,CAAC,CAAC;QACH,IAAI,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC;YAAE,MAAM,CAAC,SAAS,IAAI,CAAC,CAAC,CAAC,4CAA4C;IAChG,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED;;;;;GAKG;AACH,SAAgB,QAAQ,CAAC,OAAe,EAAE,QAAgB,EAAE,UAA2B,EAAE;IACvF,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC;IAC1C,MAAM,QAAQ,GAAoB,EAAE,CAAC;IACrC,MAAM,QAAQ,GAAoB,EAAE,CAAC;IACrC,MAAM,IAAI,GAAoB,EAAE,CAAC;IAEjC,IAAI,OAAO,GAAG,KAAK,CAAC;IACpB,IAAI,WAAW,GAAG,KAAK,CAAC;IAExB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,MAAM,IAAI,GAAG,KAAK,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;QAC5B,IAAI,kBAAkB,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,CAAC;YACzC,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,MAAM,QAAQ,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACxE,WAAW,GAAG,oBAAoB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;gBACjD,OAAO,GAAG,IAAI,CAAC;YACjB,CAAC;iBAAM,CAAC;gBACN,OAAO,GAAG,KAAK,CAAC;gBAChB,WAAW,GAAG,KAAK,CAAC;YACtB,CAAC;YACD,SAAS;QACX,CAAC;QAED,KAAK,MAAM,OAAO,IAAI,uBAAe,EAAE,CAAC;YACtC,KAAK,MAAM,OAAO,IAAI,SAAS,CAAC,IAAI,EAAE,OAAO,EAAE,CAAC,GAAG,CAAC,EAAE,QAAQ,CAAC,EAAE,CAAC;gBAChE,MAAM,WAAW,GAAG,kBAAkB,CAAC,qBAAqB,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC;gBAC/E,IAAI,WAAW,IAAI,WAAW,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC;oBACtD,MAAM,YAAY,GAAiB,WAAW;wBAC5C,CAAC,CAAC,gBAAgB;wBAClB,CAAC,CAAC,WAAW;4BACX,CAAC,CAAC,mBAAmB;4BACrB,CAAC,CAAC,aAAa,CAAC;oBACpB,IAAI,CAAC,IAAI,CAAC,EAAE,GAAG,OAAO,EAAE,YAAY,EAAE,CAAC,CAAC;gBAC1C,CAAC;qBAAM,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;oBACxC,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBACzB,CAAC;qBAAM,CAAC;oBACN,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;gBACzB,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,YAAY,EAAE,CAAC,EAAE,CAAC;AACvD,CAAC;AAED,mGAAmG;AACnG,SAAS,gBAAgB,CAAC,OAA8B;IACtD,OAAO;QACL,QAAQ,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;QAC5C,QAAQ,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC;QAC5C,IAAI,EAAE,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;QACpC,YAAY,EAAE,OAAO,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,CAAC,EAAE,EAAE,CAAC,KAAK,GAAG,CAAC,CAAC,YAAY,EAAE,CAAC,CAAC;KACtE,CAAC;AACJ,CAAC;AAED,2FAA2F;AAC3F,SAAgB,eAAe,CAAC,GAAW;IACzC,MAAM,IAAI,GAAG,GAAG,CAAC,QAAQ,CAAC,CAAC,EAAE,IAAI,CAAC,CAAC;IACnC,OAAO,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC;AAC1B,CAAC;AAED;;;;;GAKG;AACU,QAAA,kBAAkB,GAAG,CAAC,WAAW,EAAE,qBAAqB,EAAE,0BAA0B,CAAU,CAAC;AAE5G,qFAAqF;AACxE,QAAA,mBAAmB,GAAG,2BAA2B,CAAC;AAQ/D,4FAA4F;AAC5F,MAAM,YAAY,GAAG,QAAQ,CAAC;AAE9B,4FAA4F;AAC5F,MAAM,eAAe,GAAG,mCAAmC,CAAC;AAE5D;;;;;;GAMG;AACH,SAAS,gBAAgB,CAAC,IAAY,EAAE,YAA+B;IACrE,IAAI,YAAY,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACzC,MAAM,GAAG,GAAG,IAAA,4BAAY,EAAC,KAAK,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,YAAY,CAAC,EAAE;QAC3F,QAAQ,EAAE,OAAO;QACjB,GAAG,EAAE,OAAO,CAAC,GAAG;KACjB,CAAC,CAAC;IACH,MAAM,OAAO,GAAkB,EAAE,CAAC;IAClC,KAAK,MAAM,MAAM,IAAI,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC;QACrC,mGAAmG;QACnG,MAAM,KAAK,GAAG,eAAe,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QAC3C,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,YAAY;YAAE,SAAS;QAC1D,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAW,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC,CAAW,EAAE,CAAC,CAAC;IACvE,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;GAKG;AACH,SAAS,gBAAgB,CACvB,IAAY,EACZ,OAA+B;IAE/B,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACpC,MAAM,GAAG,GAAG,IAAA,4BAAY,EAAC,KAAK,EAAE,CAAC,IAAI,EAAE,IAAI,EAAE,UAAU,EAAE,SAAS,CAAC,EAAE;QACnE,KAAK,EAAE,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI;QAC3D,GAAG,EAAE,OAAO,CAAC,GAAG;QAChB,SAAS,EAAE,MAAM,CAAC,iBAAiB;KACpC,CAAC,CAAC;IACH,IAAI,MAAM,GAAG,CAAC,CAAC;IACf,OAAO,OAAO,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,EAAE,EAAE;QACpC,MAAM,SAAS,GAAG,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC5C,MAAM,MAAM,GAAG,GAAG,CAAC,QAAQ,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;QACjE,MAAM,KAAK,GAAG,0BAA0B,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACtD,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;YACxC,MAAM,IAAI,KAAK,CAAC,mDAAmD,IAAI,MAAM,MAAM,GAAG,CAAC,CAAC;QAC1F,CAAC;QACD,MAAM,KAAK,GAAG,SAAS,GAAG,CAAC,CAAC;QAC5B,MAAM,GAAG,GAAG,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;QACrC,MAAM,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC,oDAAoD;QACtE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,QAAQ,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,CAAC;IACrD,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;GAIG;AACH,SAAgB,eAAe,CAAC,cAAsB;IACpD,IAAI,CAAC,IAAA,eAAU,EAAC,cAAc,CAAC;QAAE,OAAO,EAAE,CAAC;IAC3C,OAAO,IAAA,iBAAY,EAAC,cAAc,EAAE,OAAO,CAAC;SACzC,KAAK,CAAC,YAAY,CAAC;SACnB,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC;SAC1B,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC;AAChE,CAAC;AAED,gGAAgG;AAChG,SAAS,iBAAiB,CAAC,EAAU;IACnC,OAAO,oBAAoB,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AACxD,CAAC;AAED,iHAAiH;AACjH,SAAS,YAAY,CAAC,IAAY;IAChC,IAAI,MAAM,GAAG,GAAG,CAAC;IACjB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,MAAM,EAAE,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACnB,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;YACf,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC;gBACxB,MAAM,IAAI,IAAI,CAAC;gBACf,CAAC,IAAI,CAAC,CAAC;gBACP,IAAI,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,KAAK,GAAG;oBAAE,CAAC,IAAI,CAAC,CAAC,CAAC,8CAA8C;YACjF,CAAC;iBAAM,CAAC;gBACN,MAAM,IAAI,OAAO,CAAC;YACpB,CAAC;QACH,CAAC;aAAM,IAAI,EAAE,KAAK,GAAG,EAAE,CAAC;YACtB,MAAM,IAAI,MAAM,CAAC;QACnB,CAAC;aAAM,IAAI,EAAE,KAAK,SAAS,EAAE,CAAC;YAC5B,MAAM,IAAI,iBAAiB,CAAC,EAAE,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IACD,MAAM,IAAI,GAAG,CAAC;IACd,OAAO,IAAI,MAAM,CAAC,MAAM,CAAC,CAAC;AAC5B,CAAC;AAED,0GAA0G;AAC1G,SAAgB,iBAAiB,CAAC,QAAgB,EAAE,KAAwB;IAC1E,OAAO,KAAK,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC;AACjE,CAAC;AAUD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,SAAgB,kBAAkB,CAAC,IAAY,EAAE,UAA8B,EAAE;IAC/E,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,0BAAkB,CAAC;IAChE,MAAM,cAAc,GAAG,OAAO,CAAC,cAAc,IAAI,2BAAmB,CAAC;IACrE,MAAM,WAAW,GAAG,eAAe,CAAC,IAAA,WAAI,EAAC,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC;IAEhE,MAAM,OAAO,GAAiB,EAAE,CAAC;IACjC,KAAK,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,gBAAgB,CAAC,IAAI,EAAE,gBAAgB,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC;QAC7F,IAAI,eAAe,CAAC,OAAO,CAAC;YAAE,SAAS;QACvC,MAAM,WAAW,GAAG,iBAAiB,CAAC,IAAI,EAAE,WAAW,CAAC,CAAC;QACzD,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,gBAAgB,CAAC,OAAO,CAAC,CAAC;AACnC,CAAC"}

package/dist/validation/two-pass.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Two-pass validation pipeline (spec-009-validation-strategy §1).
+ *
+ * Pass 1 is the structural Zod parse (`schema.safeParse`); on failure it is fatal and Pass 2 never
+ * runs. On success the unknown-field warning fires once (spec-009 §2), then every caller-supplied
+ * semantic check (Pass 2) executes in order. The typed, parsed data is returned.
+ */
+import type { ZodType } from 'zod';
+/** A Pass-2 semantic / cross-field check: returns silently on success, throws on failure. */
+export type SemanticCheck = () => void;
+/** Optional inputs to {@link runValidation}: the Pass-1 error-code map and the ordered Pass-2 checks. */
+export interface RunValidationOptions {
+    /** Dot-path → `E_*` code map for Pass-1 issues (spec-009 §3). */
+    errorMap?: Record<string, string>;
+    /** Pass-2 checks, run in order only after Pass 1 succeeds. */
+    semanticChecks?: SemanticCheck[];
+}
+/**
+ * Run the two-pass pipeline (spec-009 §1) for one file: Pass 1 is `schema.safeParse` (fatal on
+ * failure, mapped via {@link toValidationError}); on success the unknown-field warning fires once,
+ * then every `semanticChecks` entry runs in order. Returns the typed, parsed data.
+ */
+export declare function runValidation<T>(schema: ZodType<T>, raw: unknown, filePath: string, opts?: RunValidationOptions): T;
+//# sourceMappingURL=two-pass.d.ts.map

package/dist/validation/two-pass.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"two-pass.d.ts","sourceRoot":"","sources":["../../src/validation/two-pass.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAKnC,6FAA6F;AAC7F,MAAM,MAAM,aAAa,GAAG,MAAM,IAAI,CAAC;AAEvC,yGAAyG;AACzG,MAAM,WAAW,oBAAoB;IACnC,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,8DAA8D;IAC9D,cAAc,CAAC,EAAE,aAAa,EAAE,CAAC;CAClC;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAC7B,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,EAClB,GAAG,EAAE,OAAO,EACZ,QAAQ,EAAE,MAAM,EAChB,IAAI,GAAE,oBAAyB,GAC9B,CAAC,CAeH"}

package/dist/validation/two-pass.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runValidation = runValidation;
+const error_mapper_1 = require("./error-mapper");
+const warning_1 = require("./warning");
+/**
+ * Run the two-pass pipeline (spec-009 §1) for one file: Pass 1 is `schema.safeParse` (fatal on
+ * failure, mapped via {@link toValidationError}); on success the unknown-field warning fires once,
+ * then every `semanticChecks` entry runs in order. Returns the typed, parsed data.
+ */
+function runValidation(schema, raw, filePath, opts = {}) {
+    const result = schema.safeParse(raw);
+    if (!result.success) {
+        // Pass 1 fatal — Pass 2 never runs.
+        throw (0, error_mapper_1.toValidationError)(result.error, filePath, opts.errorMap);
+    }
+    // Every consuming schema is a `.passthrough()` object (spec-009 Consequences), so it exposes
+    // `.shape`; the cast narrows the generic `ZodType<T>` to that structural view for the warning.
+    (0, warning_1.emitUnknownFieldWarning)(raw, schema, filePath); // fires regardless of Pass-2 outcome (spec-009 §2)
+    for (const check of opts.semanticChecks ?? [])
+        check(); // Pass 2
+    return result.data;
+}
+//# sourceMappingURL=two-pass.js.map

package/dist/validation/two-pass.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"two-pass.js","sourceRoot":"","sources":["../../src/validation/two-pass.ts"],"names":[],"mappings":";;AA4BA,sCAoBC;AAvCD,iDAAmD;AACnD,uCAA8D;AAa9D;;;;GAIG;AACH,SAAgB,aAAa,CAC3B,MAAkB,EAClB,GAAY,EACZ,QAAgB,EAChB,OAA6B,EAAE;IAE/B,MAAM,MAAM,GAAG,MAAM,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;IACrC,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;QACpB,oCAAoC;QACpC,MAAM,IAAA,gCAAiB,EAAC,MAAM,CAAC,KAAK,EAAE,QAAQ,EAAE,IAAI,CAAC,QAAQ,CAAC,CAAC;IACjE,CAAC;IACD,6FAA6F;IAC7F,+FAA+F;IAC/F,IAAA,iCAAuB,EACrB,GAA8B,EAC9B,MAA6B,EAC7B,QAAQ,CACT,CAAC,CAAC,mDAAmD;IACtD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,cAAc,IAAI,EAAE;QAAE,KAAK,EAAE,CAAC,CAAC,SAAS;IACjE,OAAO,MAAM,CAAC,IAAI,CAAC;AACrB,CAAC"}

package/dist/validation/warning.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Unknown-field warning policy for `.passthrough()` schemas (spec-009-validation-strategy §2).
+ *
+ * Unknown-ness is decided against the schema's own declared key set (`schema.shape`), NOT against
+ * the passthrough-parsed output. Under `.passthrough()` the parsed object retains every unknown
+ * key, so a `raw` vs `parsed` diff is always empty — the "known-defective mechanism" spec-009 §2
+ * explicitly warns against. Diffing raw keys against `schema.shape` is the correct mechanism.
+ *
+ * The same diff is applied recursively at every nesting level that is itself a `.passthrough()`
+ * object schema (spec-009 §2: "the same diff is applied recursively at each nesting level that
+ * itself has a `.passthrough()` schema, so unknown fields inside nested config blocks are reported
+ * too, not only at the document root"). This matters because the files this module guards —
+ * `memory.yaml`, `dna.yaml`, `workflows.yaml` — all carry deeply nested config blocks (per-type
+ * state machines, phase objects, etc.), where an unknown field would otherwise go undetected.
+ */
+/**
+ * Minimal structural view of a Zod object schema: only its declared top-level `shape` is needed.
+ * Typed structurally rather than as `AnyZodObject` (spec-009 §2's listing) because Zod 4 — the
+ * version pinned in `dna.yaml` / `package.json` (`zod@^4`) — no longer exports the `AnyZodObject`
+ * alias; every `.passthrough()` object schema still exposes `.shape`, which is all this check reads.
+ */
+export interface HasShape {
+    readonly shape: Record<string, unknown>;
+}
+/**
+ * Emit one stderr warning (spec-009 §2) listing every raw key not declared in `schema`'s shape,
+ * recursively through nested passthrough object/array-of-object schemas. Writes nothing when there
+ * are no unknown fields.
+ */
+export declare function emitUnknownFieldWarning(raw: Record<string, unknown>, schema: HasShape, filePath: string): void;
+//# sourceMappingURL=warning.d.ts.map

package/dist/validation/warning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"warning.d.ts","sourceRoot":"","sources":["../../src/validation/warning.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC;AAwED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,MAAM,EAAE,QAAQ,EAChB,QAAQ,EAAE,MAAM,GACf,IAAI,CAKN"}

package/dist/validation/warning.js

@@ -0,0 +1,81 @@
+"use strict";
+/**
+ * Unknown-field warning policy for `.passthrough()` schemas (spec-009-validation-strategy §2).
+ *
+ * Unknown-ness is decided against the schema's own declared key set (`schema.shape`), NOT against
+ * the passthrough-parsed output. Under `.passthrough()` the parsed object retains every unknown
+ * key, so a `raw` vs `parsed` diff is always empty — the "known-defective mechanism" spec-009 §2
+ * explicitly warns against. Diffing raw keys against `schema.shape` is the correct mechanism.
+ *
+ * The same diff is applied recursively at every nesting level that is itself a `.passthrough()`
+ * object schema (spec-009 §2: "the same diff is applied recursively at each nesting level that
+ * itself has a `.passthrough()` schema, so unknown fields inside nested config blocks are reported
+ * too, not only at the document root"). This matters because the files this module guards —
+ * `memory.yaml`, `dna.yaml`, `workflows.yaml` — all carry deeply nested config blocks (per-type
+ * state machines, phase objects, etc.), where an unknown field would otherwise go undetected.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.emitUnknownFieldWarning = emitUnknownFieldWarning;
+/** True when `v` is a Zod object schema (structurally: exposes a `.shape` record). */
+function isHasShape(v) {
+    return (typeof v === 'object' &&
+        v !== null &&
+        'shape' in v &&
+        typeof v.shape === 'object' &&
+        v.shape !== null);
+}
+/** True when `v` is a Zod array schema (structurally: exposes an `.element` schema). */
+function isHasElement(v) {
+    return typeof v === 'object' && v !== null && 'element' in v;
+}
+/** True for a plain (non-array) object — a candidate raw value to recurse into. */
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+/**
+ * Recursively collect the paths of every raw key that is not declared in the schema's shape.
+ * Top-level unknowns are reported by bare name (`mysteryField`); nested unknowns carry a dotted /
+ * indexed path (`nested.field`, `phases[0].field`) so the operator can locate the offending block.
+ */
+function collectUnknownFields(raw, schema, prefix) {
+    const known = new Set(Object.keys(schema.shape));
+    const out = [];
+    for (const key of Object.keys(raw)) {
+        const path = prefix ? `${prefix}.${key}` : key;
+        if (!known.has(key)) {
+            out.push(path);
+            continue;
+        }
+        // Known key: descend when the declared field is itself a passthrough object schema (or an
+        // array of them) AND the raw value has the matching shape. Anything else (scalars, records,
+        // mismatched raw shapes) is left to Pass-1's own field-level validation.
+        const fieldSchema = schema.shape[key];
+        const rawValue = raw[key];
+        if (isHasShape(fieldSchema) && isPlainObject(rawValue)) {
+            out.push(...collectUnknownFields(rawValue, fieldSchema, path));
+        }
+        else if (isHasElement(fieldSchema) && Array.isArray(rawValue)) {
+            const elementSchema = fieldSchema.element;
+            if (isHasShape(elementSchema)) {
+                rawValue.forEach((item, index) => {
+                    if (isPlainObject(item)) {
+                        out.push(...collectUnknownFields(item, elementSchema, `${path}[${index}]`));
+                    }
+                });
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Emit one stderr warning (spec-009 §2) listing every raw key not declared in `schema`'s shape,
+ * recursively through nested passthrough object/array-of-object schemas. Writes nothing when there
+ * are no unknown fields.
+ */
+function emitUnknownFieldWarning(raw, schema, filePath) {
+    const unknown = collectUnknownFields(raw, schema, '');
+    if (unknown.length > 0) {
+        process.stderr.write(`Warning: ${filePath}: unknown field(s) ignored: ${unknown.join(', ')}\n`);
+    }
+}
+//# sourceMappingURL=warning.js.map

package/dist/validation/warning.js.map

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

package/dist/validation/yaml.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Parse `text` as YAML, returning the resulting data structure (`undefined` for an empty document —
+ * that is a valid, if useless, YAML document, not a parse failure).
+ *
+ * @throws {@link ValidationError} `E_YAML_PARSE_ERROR` (exit 2) if `text` cannot be parsed as YAML
+ *   at all. Zod never runs in that case (spec-009 §1).
+ */
+export declare function parseYaml(text: string, filePath: string): unknown;
+//# sourceMappingURL=yaml.d.ts.map

package/dist/validation/yaml.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml.d.ts","sourceRoot":"","sources":["../../src/validation/yaml.ts"],"names":[],"mappings":"AAYA;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAOjE"}

package/dist/validation/yaml.js

@@ -0,0 +1,30 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseYaml = parseYaml;
+/**
+ * Shared pre-Zod YAML parse step (spec-009-validation-strategy §1, Pass 1 step 1: "Parse the raw
+ * text as YAML. A parse failure never reaches Zod — see E_YAML_PARSE_ERROR below."). Every pillar
+ * loader (memory.yaml, dna.yaml, workflows.yaml + its included workflow files, directive
+ * frontmatter) calls this before handing the result to `runValidation`, so a malformed file always
+ * surfaces as the same `E_YAML_PARSE_ERROR` / exit-2 `ValidationError` instead of each loader
+ * re-wrapping `js-yaml` itself.
+ */
+const js_yaml_1 = require("js-yaml");
+const errors_1 = require("./errors");
+/**
+ * Parse `text` as YAML, returning the resulting data structure (`undefined` for an empty document —
+ * that is a valid, if useless, YAML document, not a parse failure).
+ *
+ * @throws {@link ValidationError} `E_YAML_PARSE_ERROR` (exit 2) if `text` cannot be parsed as YAML
+ *   at all. Zod never runs in that case (spec-009 §1).
+ */
+function parseYaml(text, filePath) {
+    try {
+        return (0, js_yaml_1.load)(text);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw errors_1.ValidationError.yamlParse(filePath, message);
+    }
+}
+//# sourceMappingURL=yaml.js.map

package/dist/validation/yaml.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"yaml.js","sourceRoot":"","sources":["../../src/validation/yaml.ts"],"names":[],"mappings":";;AAmBA,8BAOC;AA1BD;;;;;;;GAOG;AACH,qCAA+B;AAE/B,qCAA2C;AAE3C;;;;;;GAMG;AACH,SAAgB,SAAS,CAAC,IAAY,EAAE,QAAgB;IACtD,IAAI,CAAC;QACH,OAAO,IAAA,cAAI,EAAC,IAAI,CAAC,CAAC;IACpB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACjE,MAAM,wBAAe,CAAC,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IACrD,CAAC;AACH,CAAC"}

package/dist/workflow/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `workflow` module — Project Workflow pillar; phases/steps/atomic actions, `include()` composition
+ * (P4.1). `workflows.yaml`'s Layer-1 manifest + Layer-2 Workflow DSL schemas
+ * (spec-003-workflows-yaml-schema) live here — the pillar owns its own independent schema
+ * (REQ-SYS-02); `src/core`'s loader wires it through the shared validation pipeline. Further
+ * Workflow behavior (engine execution, `wingfoil workflow *`) lands in later tasks.
+ */
+export declare const MODULE_NAME: "workflow";
+export { WorkflowsYaml, Workflow, Phase } from './schema';
+//# sourceMappingURL=index.d.ts.map

package/dist/workflow/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/workflow/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,eAAO,MAAM,WAAW,EAAG,UAAmB,CAAC;AAE/C,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,UAAU,CAAC"}