@sublang/slc 0.1.0

package/dist/phase-runner.js

@@ -0,0 +1,322 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+/**
+ * SLC phase-runner facade for compiled `playbook` artifacts (PHEXEC-23,
+ * PHEXEC-24; DR-005).
+ *
+ * A compiled `playbook` artifact default-exports a `PlaybookRuntimeFactory`
+ * (`createPlaybookRuntime`). `slc` drives it host-side — `init` with the
+ * DR-010 session/legacy compatibility view over a `PlaybookPorts` adapter, one
+ * `handleBossInput` turn seeded from the {@link PhaseInput}, then `dispose` —
+ * and derives a {@link PhaseResult}
+ * (`ok`/`blocked`/`error`) that {@link mapPhaseResult} maps onto the DR-003
+ * protocol: `ok` proceeds to the generic checks, `blocked` is the BLOCKED
+ * outcome, and `error` stops the pipeline like a failed generic check.
+ *
+ * The non-interactive driving lives in the compiled executor; this module owns
+ * the shared facade types, the static `playbook`-format recognition the
+ * pin-currency validator uses, the seeding of a phase request into the
+ * runtime's single Boss turn (PHEXEC-29), and the host workspace contract a
+ * transformation-performing direct Captain call carries (PHEXEC-34). See
+ * specs/dev/phase-execution.md.
+ */
+import ts from 'typescript';
+/**
+ * Maps a compiled phase's {@link PhaseResult} onto the DR-003 execution-boundary
+ * outcome consumed by `runPhase` (PHEXEC-24).
+ *
+ * The facade result (owned by the DR-005 artifact contract) and the executor
+ * result (owned by the DR-003 boundary) are distinct types, so the compiled
+ * executor crosses the boundary through this seam rather than casting: `ok`
+ * proceeds to the generic checks, `blocked` is the BLOCKED outcome, and `error`
+ * stops the pipeline like a failed generic check, with diagnostics surfaced for
+ * every status.
+ */
+export function mapPhaseResult(result) {
+    return { status: result.status, diagnostics: result.diagnostics };
+}
+const PLAYBOOK_FACTORY = 'createPlaybookRuntime';
+/**
+ * Reports whether a compiled artifact's source resolves to the linked `playbook`
+ * format: a module exposing a `createPlaybookRuntime` default export (DR-005).
+ * This is the static byte-level recognition the pin-currency validator uses; the
+ * loader confirms the contract at run time.
+ */
+export function resolvesToPlaybook(source) {
+    const file = ts.createSourceFile('artifact.playbook.ts', source, ts.ScriptTarget.Latest, true, ts.ScriptKind.TS);
+    const diagnostics = file.parseDiagnostics;
+    if (diagnostics?.some((item) => item.category === ts.DiagnosticCategory.Error)) {
+        return false;
+    }
+    if (!usesErasableTypeScript(file) || defaultExportCount(file) !== 1) {
+        return false;
+    }
+    if (factoryValueBindingCount(file, PLAYBOOK_FACTORY) !== 1)
+        return false;
+    const hasFactoryBinding = factoryBindingIsCallable(file, PLAYBOOK_FACTORY);
+    for (const statement of file.statements) {
+        if (ts.isFunctionDeclaration(statement) &&
+            statement.name?.text === PLAYBOOK_FACTORY &&
+            statement.body !== undefined &&
+            hasModifier(statement, ts.SyntaxKind.ExportKeyword) &&
+            hasModifier(statement, ts.SyntaxKind.DefaultKeyword) &&
+            isSynchronousFunction(statement)) {
+            return true;
+        }
+        if (ts.isExportAssignment(statement) &&
+            !statement.isExportEquals &&
+            ts.isIdentifier(unwrapExpression(statement.expression)) &&
+            (unwrapExpression(statement.expression).text ===
+                PLAYBOOK_FACTORY ||
+                // `const factory: PlaybookRuntimeFactory<…> = createPlaybookRuntime;
+                // export default factory;` — a typed alias of the factory is the
+                // factory; linkers use it to state contract conformance in erasable
+                // TypeScript.
+                aliasesFactory(file, unwrapExpression(statement.expression).text)) &&
+            hasFactoryBinding) {
+            return true;
+        }
+        if (ts.isExportDeclaration(statement) &&
+            statement.exportClause !== undefined) {
+            if (ts.isNamedExports(statement.exportClause) &&
+                statement.exportClause.elements.some((element) => !statement.isTypeOnly &&
+                    !element.isTypeOnly &&
+                    element.name.text === 'default' &&
+                    (element.propertyName?.text ?? element.name.text) ===
+                        PLAYBOOK_FACTORY) &&
+                statement.moduleSpecifier === undefined &&
+                hasFactoryBinding) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/** True when `name` is a top-level `const <name> = createPlaybookRuntime;`. */
+function aliasesFactory(file, name) {
+    for (const statement of file.statements) {
+        if (!ts.isVariableStatement(statement))
+            continue;
+        if ((statement.declarationList.flags & ts.NodeFlags.Const) === 0 ||
+            hasModifier(statement, ts.SyntaxKind.DeclareKeyword)) {
+            continue;
+        }
+        for (const declaration of statement.declarationList.declarations) {
+            if (ts.isIdentifier(declaration.name) &&
+                declaration.name.text === name &&
+                declaration.initializer !== undefined &&
+                ts.isIdentifier(unwrapExpression(declaration.initializer)) &&
+                unwrapExpression(declaration.initializer).text ===
+                    PLAYBOOK_FACTORY) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+function usesErasableTypeScript(file) {
+    let erasable = true;
+    const visit = (node) => {
+        if (ts.isEnumDeclaration(node) ||
+            ts.isModuleDeclaration(node) ||
+            ts.isImportEqualsDeclaration(node) ||
+            (ts.isExportAssignment(node) && node.isExportEquals) ||
+            (ts.isParameter(node) &&
+                ts.isParameterPropertyDeclaration(node, node.parent))) {
+            erasable = false;
+            return;
+        }
+        ts.forEachChild(node, visit);
+    };
+    visit(file);
+    return erasable;
+}
+function defaultExportCount(file) {
+    let count = 0;
+    for (const statement of file.statements) {
+        if ((ts.isFunctionDeclaration(statement) ||
+            ts.isClassDeclaration(statement)) &&
+            hasModifier(statement, ts.SyntaxKind.DefaultKeyword)) {
+            count++;
+        }
+        else if (ts.isExportAssignment(statement) && !statement.isExportEquals) {
+            count++;
+        }
+        else if (ts.isExportDeclaration(statement) &&
+            statement.exportClause !== undefined &&
+            ts.isNamedExports(statement.exportClause)) {
+            count += statement.exportClause.elements.filter((element) => !statement.isTypeOnly &&
+                !element.isTypeOnly &&
+                element.name.text === 'default').length;
+        }
+    }
+    return count;
+}
+function factoryValueBindingCount(file, name) {
+    let count = 0;
+    for (const statement of file.statements) {
+        if (ts.isFunctionDeclaration(statement) &&
+            statement.name?.text === name &&
+            statement.body !== undefined) {
+            count++;
+        }
+        if (ts.isVariableStatement(statement)) {
+            count += statement.declarationList.declarations.filter((declaration) => ts.isIdentifier(declaration.name) &&
+                declaration.name.text === name &&
+                declaration.initializer !== undefined).length;
+        }
+    }
+    return count;
+}
+function hasModifier(node, kind) {
+    return (ts.canHaveModifiers(node) &&
+        ts.getModifiers(node)?.some((modifier) => modifier.kind === kind) === true);
+}
+function factoryBindingIsCallable(file, name, seen = new Set()) {
+    if (seen.has(name))
+        return false;
+    const nextSeen = new Set(seen).add(name);
+    for (const statement of file.statements) {
+        if (ts.isFunctionDeclaration(statement) &&
+            statement.name?.text === name &&
+            statement.body !== undefined &&
+            isSynchronousFunction(statement)) {
+            return true;
+        }
+        if (ts.isVariableStatement(statement)) {
+            for (const declaration of statement.declarationList.declarations) {
+                if (ts.isIdentifier(declaration.name) &&
+                    declaration.name.text === name &&
+                    declaration.initializer !== undefined &&
+                    callableExpression(file, declaration.initializer, nextSeen)) {
+                    return true;
+                }
+            }
+        }
+    }
+    return false;
+}
+function callableExpression(file, expression, seen) {
+    const value = unwrapExpression(expression);
+    if ((ts.isArrowFunction(value) || ts.isFunctionExpression(value)) &&
+        isSynchronousFunction(value)) {
+        return true;
+    }
+    if (ts.isIdentifier(value)) {
+        return factoryBindingIsCallable(file, value.text, seen);
+    }
+    // A DR-019 thin module binds the factory to a shared-engine factory call —
+    // `createXStatePlaybookRuntime(machine, spec)`. Static recognition accepts
+    // the call exactly when its callee is a non-type named import from the
+    // shared engine module; the loader confirms the returned factory's
+    // callability at run time (DR-017).
+    if (ts.isCallExpression(value)) {
+        const callee = unwrapExpression(value.expression);
+        if (ts.isIdentifier(callee)) {
+            return importedFromSharedEngine(file, callee.text);
+        }
+    }
+    return false;
+}
+const SHARED_ENGINE_MODULE = '@sublang/playbook/xstate-runtime';
+/** True when `name` locally binds the shared engine's runtime factory export. */
+function importedFromSharedEngine(file, name) {
+    for (const statement of file.statements) {
+        if (!ts.isImportDeclaration(statement))
+            continue;
+        if (!ts.isStringLiteral(statement.moduleSpecifier) ||
+            statement.moduleSpecifier.text !== SHARED_ENGINE_MODULE) {
+            continue;
+        }
+        const clause = statement.importClause;
+        if (clause === undefined || clause.phaseModifier !== undefined)
+            continue;
+        const bindings = clause.namedBindings;
+        if (bindings === undefined || !ts.isNamedImports(bindings))
+            continue;
+        for (const element of bindings.elements) {
+            if (!element.isTypeOnly &&
+                element.name.text === name &&
+                (element.propertyName?.text ?? element.name.text) ===
+                    'createXStatePlaybookRuntime') {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+function isSynchronousFunction(node) {
+    return (!hasModifier(node, ts.SyntaxKind.AsyncKeyword) &&
+        (!('asteriskToken' in node) || node.asteriskToken === undefined));
+}
+function unwrapExpression(expression) {
+    let current = expression;
+    while (ts.isParenthesizedExpression(current) ||
+        ts.isTypeAssertionExpression(current) ||
+        ts.isAsExpression(current) ||
+        ts.isSatisfiesExpression(current) ||
+        ts.isNonNullExpression(current)) {
+        current = current.expression;
+    }
+    return current;
+}
+/**
+ * Seeds a phase request into the single non-interactive Boss turn `slc` hands
+ * the runtime through `handleBossInput` (PHEXEC-29; DR-005).
+ *
+ * The settled SLC-to-runtime seeding contract: one Boss turn whose text states
+ * the request kind in prose — so any compiled playbook's judge-backed classifier
+ * can route it — and carries the full request as a single-line JSON object
+ * introduced by `Request: `, with workspace paths already resolved to absolute
+ * host paths, so a runtime (or a deterministic fixture) recovers the exact
+ * `PhaseInput` without host-specific parsing.
+ */
+export function seedPhaseTurn(input) {
+    const directive = input.kind === 'compile'
+        ? 'Perform this compile phase non-interactively: transform the source into the target artifact, then stop.'
+        : 'Perform this link phase non-interactively: link the object artifacts against the link target into the linked artifact, then stop.';
+    return `${directive}\nRequest: ${JSON.stringify(input)}`;
+}
+/**
+ * Composes the host workspace contract a transformation-performing direct
+ * Captain call carries (PHEXEC-34; DR-005, DR-012).
+ *
+ * A linked `playbook` artifact composes host-agnostic Captain prompts — the
+ * GEARS-derived domain body plus typed runtime evidence — and is forbidden from
+ * appending workspace specifics, which only the host owns. Mirroring the
+ * interpreted agent contract (PHEXEC-14), the host therefore supplies the
+ * request's absolute workspace paths and write-scope rules at its transport
+ * boundary, so the acting Captain writes exactly the declared target instead
+ * of merely emitting the artifact in its reply. Routing-only Captain calls
+ * (explicitly empty `allowedTools`) and hidden judge calls never carry it.
+ */
+export function composeWorkspaceContract(input) {
+    const target = input.kind === 'compile' ? input.target : input.linked;
+    const inputs = input.kind === 'compile'
+        ? [`source to read: ${input.source}`]
+        : [
+            `object artifacts to read, in order: ${input.objects.join(', ')}`,
+            `link target module: ${input.linkTarget}`,
+            `options: ${formatWorkspaceOptions(input.options)}`,
+        ];
+    return [
+        'Host workspace (SubLang Compiler):',
+        'You are performing the work above non-interactively as one compiled phase of the SubLang Compiler (slc), against these workspace files:',
+        ...inputs.map((line) => `- ${line}`),
+        `- artifact to write: ${target}`,
+        '',
+        'Workspace contract — you must:',
+        `- write only ${target}, creating or overwriting exactly that file; emitting the artifact solely in your reply does not produce it;`,
+        '- not edit the sources, the phase or link definition, specs, link targets, object artifacts, or any other file;',
+        '- not commit or otherwise touch version control;',
+        '- produce a complete artifact, not a sketch or placeholder;',
+        '- verify the produced artifact before finishing, then reply with a concise summary of what you produced and any ambiguity you resolved.',
+    ].join('\n');
+}
+function formatWorkspaceOptions(options) {
+    const entries = Object.entries(options);
+    if (entries.length === 0)
+        return '(none)';
+    return entries.map(([name, value]) => `${name}=${value}`).join(', ');
+}
+//# sourceMappingURL=phase-runner.js.map

package/dist/phase-runner.js.map

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

package/dist/phase.d.ts

@@ -0,0 +1,62 @@
+/** A format token bound to its canonical file extension. */
+export interface FormatDecl {
+    /** Short kebab-case language identifier, e.g. `text`, `gears`, `fsm`. */
+    format: string;
+    /** Canonical extension including the leading dot, e.g. `.md`, `.ts`. */
+    ext: string;
+}
+/** A loaded ordinary compile phase or format-preserving pass phase. */
+export interface Phase {
+    /** Phase basename without the `.md` suffix, e.g. `text2gears` or `optimize`. */
+    name: string;
+    /** Declared source role. */
+    source: FormatDecl;
+    /** Declared target role. */
+    target: FormatDecl;
+    /**
+     * True for a format-preserving pass phase (source format equals target
+     * format), which sits outside the linear chain and runs only when a compile
+     * opts in (DR-013).
+     */
+    pass: boolean;
+}
+/** Machine-readable reason a `## Formats` table was refused. */
+export type FormatsErrorCode = 'missing-formats' | 'malformed-formats' | 'missing-role';
+/** Machine-readable reason a phase was refused. */
+export type PhaseErrorCode = FormatsErrorCode | 'filename-mismatch' | 'extension-conflict';
+/** Raised when a phase definition is refused under DR-001. */
+export declare class PhaseError extends Error {
+    readonly code: PhaseErrorCode;
+    constructor(code: PhaseErrorCode, message: string);
+}
+/**
+ * Reads the authoritative `## Formats` table into its source and target
+ * declarations (PIPE-1), shared by the phase and link loaders.
+ *
+ * Refusals are reported through `fail` so each loader can raise its own error
+ * type; `fail` must not return.
+ */
+export declare function readFormats(content: string, fail: (code: FormatsErrorCode, message: string) => never): {
+    source: FormatDecl;
+    target: FormatDecl;
+};
+/**
+ * Parses and validates a phase definition from its filename and content.
+ *
+ * @throws {PhaseError} when the `## Formats` table is missing or malformed, or
+ *   when the filename does not match the declared tokens (PIPE-1, PIPE-2).
+ */
+export declare function parsePhase(file: {
+    name: string;
+    content: string;
+}): Phase;
+/** Reads a phase definition file from disk and parses it (PIPE-1, PIPE-2). */
+export declare function loadPhaseFile(path: string): Promise<Phase>;
+/**
+ * Refuses a set of phases that declare conflicting extensions for the same
+ * format token (PIPE-3).
+ *
+ * @throws {PhaseError} with code `extension-conflict` on the first conflict.
+ */
+export declare function checkExtensionConsistency(phases: readonly Phase[]): void;
+//# sourceMappingURL=phase.d.ts.map

package/dist/phase.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"phase.d.ts","sourceRoot":"","sources":["../src/phase.ts"],"names":[],"mappings":"AAkBA,4DAA4D;AAC5D,MAAM,WAAW,UAAU;IACzB,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,GAAG,EAAE,MAAM,CAAC;CACb;AAED,uEAAuE;AACvE,MAAM,WAAW,KAAK;IACpB,gFAAgF;IAChF,IAAI,EAAE,MAAM,CAAC;IACb,4BAA4B;IAC5B,MAAM,EAAE,UAAU,CAAC;IACnB,4BAA4B;IAC5B,MAAM,EAAE,UAAU,CAAC;IACnB;;;;OAIG;IACH,IAAI,EAAE,OAAO,CAAC;CACf;AAED,gEAAgE;AAChE,MAAM,MAAM,gBAAgB,GACxB,iBAAiB,GACjB,mBAAmB,GACnB,cAAc,CAAC;AAEnB,mDAAmD;AACnD,MAAM,MAAM,cAAc,GACtB,gBAAgB,GAChB,mBAAmB,GACnB,oBAAoB,CAAC;AAEzB,8DAA8D;AAC9D,qBAAa,UAAW,SAAQ,KAAK;IACnC,QAAQ,CAAC,IAAI,EAAE,cAAc,CAAC;gBAElB,IAAI,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM;CAKlD;AAKD;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,CAAC,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,KAAK,KAAK,GACvD;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,MAAM,EAAE,UAAU,CAAA;CAAE,CAwC5C;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,KAAK,CAmBzE;AAED,8EAA8E;AAC9E,wBAAsB,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAGhE;AAED;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,GAAG,IAAI,CAgBxE"}

package/dist/phase.js

@@ -0,0 +1,111 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+/**
+ * Phase model and `## Formats` parsing (DR-001).
+ *
+ * Implements PIPE-1 (read the authoritative `## Formats` table), PIPE-2 (refuse
+ * a phase whose `<source-format>2<target-format>.md` filename does not match its
+ * table), and PIPE-3 (refuse phases declaring conflicting extensions for the
+ * same format token). The `## Formats` reader is shared with the link loader.
+ * See specs/dev/pipeline.md.
+ */
+import { readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { findSection, parseTable } from './markdown.js';
+/** Raised when a phase definition is refused under DR-001. */
+export class PhaseError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'PhaseError';
+        this.code = code;
+    }
+}
+const FORMAT_TOKEN = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+const EXTENSION = /^\.[A-Za-z0-9]+$/;
+/**
+ * Reads the authoritative `## Formats` table into its source and target
+ * declarations (PIPE-1), shared by the phase and link loaders.
+ *
+ * Refusals are reported through `fail` so each loader can raise its own error
+ * type; `fail` must not return.
+ */
+export function readFormats(content, fail) {
+    const section = findSection(content, 'Formats');
+    if (section === null) {
+        fail('missing-formats', 'missing a ## Formats section');
+    }
+    const decls = new Map();
+    for (const cells of parseTable(section)) {
+        if (cells.length < 3)
+            continue;
+        const role = cells[0].toLowerCase();
+        if (role !== 'source' && role !== 'target')
+            continue;
+        const [, format, ext] = cells;
+        if (!FORMAT_TOKEN.test(format)) {
+            fail('malformed-formats', `${role} format token "${format}" is not a kebab-case identifier`);
+        }
+        if (!EXTENSION.test(ext)) {
+            fail('malformed-formats', `${role} extension "${ext}" is not a canonical extension (e.g. ".md")`);
+        }
+        if (decls.has(role)) {
+            fail('malformed-formats', `## Formats declares ${role} more than once`);
+        }
+        decls.set(role, { format, ext });
+    }
+    const source = decls.get('source');
+    const target = decls.get('target');
+    if (source === undefined || target === undefined) {
+        fail('missing-role', `## Formats is missing a ${source === undefined ? 'source' : 'target'} row`);
+    }
+    return { source, target };
+}
+/**
+ * Parses and validates a phase definition from its filename and content.
+ *
+ * @throws {PhaseError} when the `## Formats` table is missing or malformed, or
+ *   when the filename does not match the declared tokens (PIPE-1, PIPE-2).
+ */
+export function parsePhase(file) {
+    const { source, target } = readFormats(file.content, (code, message) => {
+        throw new PhaseError(code, message);
+    });
+    // A format-preserving pass phase is named freely — its filename is the pass
+    // name (DR-013); the `<source>2<target>.md` rule identifies transform phases.
+    const pass = source.format === target.format;
+    if (!pass) {
+        const expected = `${source.format}2${target.format}.md`;
+        if (file.name !== expected) {
+            throw new PhaseError('filename-mismatch', `phase filename "${file.name}" does not match its ## Formats tokens (expected "${expected}")`);
+        }
+    }
+    return { name: file.name.slice(0, -'.md'.length), source, target, pass };
+}
+/** Reads a phase definition file from disk and parses it (PIPE-1, PIPE-2). */
+export async function loadPhaseFile(path) {
+    const content = await readFile(path, 'utf8');
+    return parsePhase({ name: basename(path), content });
+}
+/**
+ * Refuses a set of phases that declare conflicting extensions for the same
+ * format token (PIPE-3).
+ *
+ * @throws {PhaseError} with code `extension-conflict` on the first conflict.
+ */
+export function checkExtensionConsistency(phases) {
+    const seen = new Map();
+    for (const phase of phases) {
+        for (const decl of [phase.source, phase.target]) {
+            const prior = seen.get(decl.format);
+            if (prior === undefined) {
+                seen.set(decl.format, { ext: decl.ext, phase: phase.name });
+            }
+            else if (prior.ext !== decl.ext) {
+                throw new PhaseError('extension-conflict', `format "${decl.format}" declares conflicting extensions: ` +
+                    `"${prior.ext}" (in ${prior.phase}) vs "${decl.ext}" (in ${phase.name})`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=phase.js.map

package/dist/phase.js.map

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

package/dist/pin-closure.d.ts

@@ -0,0 +1,19 @@
+import type { PinRecord } from './pins.js';
+/** Extracts the inline-code paths cited by a `## Pin Inputs` section (DR-007). */
+export declare function parsePinInputs(content: string): string[];
+/**
+ * Derives the semantic-input closure of `definitionPath` as a set of resolved
+ * absolute paths: the definition plus every transitively cited local file
+ * (PIN-2, PIN-4).
+ *
+ * @throws {import('./pins.js').PinError} when a cited path is absolute or escapes
+ *   the recorded boundary (PIN-5).
+ */
+export declare function deriveClosure(pipelineDir: string, boundary: string, definitionPath: string): Promise<Set<string>>;
+/**
+ * Reports whether the closure derived from `record.definition` matches the
+ * recorded definition plus semanticInputs, compared as sets of resolved paths
+ * (PIN-4).
+ */
+export declare function closureMatchesRecord(pipelineDir: string, boundary: string, record: PinRecord): Promise<boolean>;
+//# sourceMappingURL=pin-closure.d.ts.map

package/dist/pin-closure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pin-closure.d.ts","sourceRoot":"","sources":["../src/pin-closure.ts"],"names":[],"mappings":"AAuBA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AAK3C,kFAAkF;AAClF,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAYxD;AAED;;;;;;;GAOG;AACH,wBAAsB,aAAa,CACjC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,cAAc,EAAE,MAAM,GACrB,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAoCtB;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,SAAS,GAChB,OAAO,CAAC,OAAO,CAAC,CAqBlB"}

package/dist/pin-closure.js

@@ -0,0 +1,110 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+/**
+ * Semantic-input closure derivation for the pin-currency validator (PIN-2, PIN-4;
+ * DR-007).
+ *
+ * A pinned phase's semantic-input closure is the definition file plus every local
+ * file transitively cited by a `## Pin Inputs` section. A `## Pin Inputs` section
+ * cites each input as an inline-code path (for example `` `reference/gears.md` ``)
+ * expressed relative to the pipeline directory — the same coordinate system as
+ * the recorded pin paths. Derivation recurses only into Markdown inputs that
+ * declare their own `## Pin Inputs`; a non-Markdown input, or a Markdown input
+ * without the section, is a closure member but terminates the transitive walk.
+ * The derived closure is compared — as a set of resolved paths — to the recorded
+ * definition plus semanticInputs; any difference is a stale verdict (PIN-4). See
+ * specs/dev/pinning.md.
+ */
+import { readFile } from 'node:fs/promises';
+import { findSection } from './markdown.js';
+import { resolvePinPath } from './pin-paths.js';
+const PIN_INPUT_FIELD = 'pin input path';
+const INLINE_CODE = /`([^`]+)`/g;
+/** Extracts the inline-code paths cited by a `## Pin Inputs` section (DR-007). */
+export function parsePinInputs(content) {
+    const lines = findSection(content, 'Pin Inputs');
+    if (lines === null) {
+        return [];
+    }
+    const paths = [];
+    for (const line of lines) {
+        for (const match of line.matchAll(INLINE_CODE)) {
+            paths.push(match[1].trim());
+        }
+    }
+    return paths;
+}
+/**
+ * Derives the semantic-input closure of `definitionPath` as a set of resolved
+ * absolute paths: the definition plus every transitively cited local file
+ * (PIN-2, PIN-4).
+ *
+ * @throws {import('./pins.js').PinError} when a cited path is absolute or escapes
+ *   the recorded boundary (PIN-5).
+ */
+export async function deriveClosure(pipelineDir, boundary, definitionPath) {
+    const closure = new Set();
+    const seen = new Set();
+    const queue = [definitionPath];
+    while (queue.length > 0) {
+        const rel = queue.shift();
+        if (seen.has(rel)) {
+            continue;
+        }
+        seen.add(rel);
+        const resolved = resolvePinPath(pipelineDir, boundary, rel, PIN_INPUT_FIELD);
+        closure.add(resolved);
+        // Recurse only into Markdown inputs that declare their own ## Pin Inputs;
+        // non-Markdown and sectionless inputs are members but terminate the walk.
+        if (!isMarkdown(rel)) {
+            continue;
+        }
+        const content = await readIfPresent(resolved);
+        if (content === null) {
+            continue;
+        }
+        for (const cited of parsePinInputs(content)) {
+            if (!seen.has(cited)) {
+                queue.push(cited);
+            }
+        }
+    }
+    return closure;
+}
+/**
+ * Reports whether the closure derived from `record.definition` matches the
+ * recorded definition plus semanticInputs, compared as sets of resolved paths
+ * (PIN-4).
+ */
+export async function closureMatchesRecord(pipelineDir, boundary, record) {
+    const derived = await deriveClosure(pipelineDir, boundary, record.definition.path);
+    const recorded = new Set();
+    recorded.add(resolvePinPath(pipelineDir, boundary, record.definition.path, 'definition.path'));
+    for (const input of record.semanticInputs) {
+        recorded.add(resolvePinPath(pipelineDir, boundary, input.path, 'semanticInputs.path'));
+    }
+    return setsEqual(derived, recorded);
+}
+function isMarkdown(path) {
+    return path.toLowerCase().endsWith('.md');
+}
+async function readIfPresent(absolutePath) {
+    try {
+        return await readFile(absolutePath, 'utf8');
+    }
+    catch {
+        return null;
+    }
+}
+function setsEqual(a, b) {
+    if (a.size !== b.size) {
+        return false;
+    }
+    for (const value of a) {
+        if (!b.has(value)) {
+            return false;
+        }
+    }
+    return true;
+}
+//# sourceMappingURL=pin-closure.js.map