@sublang/slc 0.1.0

package/dist/pin-generate.js

@@ -0,0 +1,131 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+/**
+ * Pin generation: the explicit build-and-review flow that writes `slc.pins.json`
+ * (PIN-15; DR-007).
+ *
+ * This is the inverse of the currency validator: given a built and reviewed
+ * compiled artifact, {@link generatePinRecord} records — over committed bytes —
+ * the definition, compiled entry module and reviewed artifact bundle, the
+ * semantic-input closure derived from the definition's `## Pin Inputs`, and the
+ * link-target identity, so the resulting record validates as current.
+ * {@link writePinFile} writes the pin index for a pipeline directory. Generation
+ * is invoked only by an explicit build-and-review step, never during an ordinary
+ * pipeline run; `slc` does not regenerate or rewrite pins per invocation
+ * (DR-007 lifecycle). See specs/dev/pinning.md.
+ */
+import { writeFile } from 'node:fs/promises';
+import { dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';
+import { hashFile } from './hash.js';
+import { deriveClosure } from './pin-closure.js';
+import { artifactBundleLayoutIssue, hashTree } from './pin-currency.js';
+import { resolvePinPath } from './pin-paths.js';
+import { PINS_FILE, PIN_HASH_ALGORITHM, PIN_SCHEMA, PinError, } from './pins.js';
+import { resolveRuntimePackage } from './runtime-package.js';
+/** The default recorded path boundary (the pipeline directory). */
+const BOUNDARY = '.';
+/**
+ * Generates a current {@link PinRecord} for one phase from its committed inputs
+ * (PIN-15). The definition is recorded separately; the rest of its `## Pin Inputs`
+ * closure becomes the enumerated `semanticInputs`.
+ */
+export async function generatePinRecord(pipelineDir, spec, opts = {}) {
+    const boundary = opts.boundary ?? BOUNDARY;
+    const definitionResolved = resolvePinPath(pipelineDir, boundary, spec.definition, 'definition');
+    const closure = await deriveClosure(pipelineDir, boundary, spec.definition);
+    const semanticInputs = await Promise.all([...closure]
+        .filter((resolved) => resolved !== definitionResolved)
+        .sort()
+        .map(async (resolved) => {
+        const path = toPosix(relative(pipelineDir, resolved));
+        const hash = await hashFile(resolved);
+        const role = spec.roles?.[path];
+        return role === undefined ? { path, hash } : { path, hash, role };
+    }));
+    const artifactResolved = resolvePinPath(pipelineDir, boundary, spec.artifact, 'artifact');
+    const artifactBundleResolved = resolvePinPath(pipelineDir, boundary, spec.artifactBundle, 'artifactBundle');
+    const artifactRelative = relative(artifactBundleResolved, artifactResolved);
+    if (artifactRelative === '' ||
+        artifactRelative === '..' ||
+        artifactRelative.startsWith(`..${sep}`) ||
+        isAbsolute(artifactRelative) ||
+        dirname(artifactRelative) !== '.') {
+        throw new PinError('pin-invalid', 'artifact must be a direct child of artifactBundle');
+    }
+    const bundleLayout = await artifactBundleLayoutIssue(artifactBundleResolved, artifactResolved);
+    if (bundleLayout !== null) {
+        throw new PinError('pin-invalid', bundleLayout);
+    }
+    const linkResolved = resolvePinPath(pipelineDir, boundary, spec.linkTarget.locator, 'linkTarget.locator');
+    const identity = spec.linkTarget.kind === 'file'
+        ? await hashFile(linkResolved)
+        : await hashTree(linkResolved);
+    const runtimeDependencies = await Promise.all((spec.runtimeDependencies ?? []).map(async (dependency) => {
+        const resolved = resolvePinPath(pipelineDir, boundary, dependency.locator, 'runtimeDependencies.locator');
+        const dependencyIdentity = dependency.kind === 'file'
+            ? await hashFile(resolved)
+            : await hashTree(resolved);
+        if (dependency.kind === 'package') {
+            if (dependency.specifier === undefined) {
+                throw new PinError('pin-invalid', 'package runtime dependency must declare its import specifier');
+            }
+            let selected;
+            try {
+                selected = resolveRuntimePackage(artifactResolved, dependency.specifier).root;
+            }
+            catch (error) {
+                throw new PinError('pin-invalid', `runtime dependency specifier cannot be resolved: ${messageOf(error)}`);
+            }
+            if (resolve(selected) !== resolve(resolved)) {
+                throw new PinError('pin-invalid', `runtime dependency locator is not the package selected by "${dependency.specifier}"`);
+            }
+        }
+        return { ...dependency, identity: dependencyIdentity };
+    }));
+    const linkTarget = {
+        kind: spec.linkTarget.kind,
+        locator: spec.linkTarget.locator,
+        identity,
+        ...(spec.linkTarget.provenance !== undefined
+            ? { provenance: spec.linkTarget.provenance }
+            : {}),
+    };
+    return {
+        definition: {
+            path: spec.definition,
+            hash: await hashFile(definitionResolved),
+        },
+        artifact: { path: spec.artifact, hash: await hashFile(artifactResolved) },
+        artifactBundle: {
+            path: spec.artifactBundle,
+            hash: await hashTree(artifactBundleResolved, { rejectSymlinks: true }),
+        },
+        semanticInputs,
+        externalInputs: [...(spec.externalInputs ?? [])],
+        runtimeDependencies,
+        linkTarget,
+        ...(spec.producer !== undefined ? { producer: spec.producer } : {}),
+    };
+}
+/**
+ * Writes the pin index `<pipelineDir>/slc.pins.json` for the given phase records
+ * and returns its path (PIN-15).
+ */
+export async function writePinFile(pipelineDir, pins, opts = {}) {
+    const file = {
+        schema: PIN_SCHEMA,
+        hashAlgorithm: PIN_HASH_ALGORITHM,
+        pathBoundary: { path: opts.boundary ?? BOUNDARY },
+        pins: { ...pins },
+    };
+    const path = join(pipelineDir, PINS_FILE);
+    await writeFile(path, `${JSON.stringify(file, null, 2)}\n`);
+    return path;
+}
+function toPosix(path) {
+    return path.split(sep).join('/');
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=pin-generate.js.map

package/dist/pin-generate.js.map

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

package/dist/pin-paths.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Resolves a relative POSIX `relPath` against `pipelineDir`, requiring it to stay
+ * inside `boundary` (also a relative POSIX path from `pipelineDir`) (PIN-2, PIN-5).
+ *
+ * @returns the resolved absolute host path.
+ * @throws {PinError} (`pin-invalid`) when the recorded `boundary` is absolute
+ *   (naming `pathBoundary.path`), or `relPath` is absolute or escapes the
+ *   recorded boundary (naming `field`).
+ */
+export declare function resolvePinPath(pipelineDir: string, boundary: string, relPath: string, field: string): string;
+//# sourceMappingURL=pin-paths.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"pin-paths.d.ts","sourceRoot":"","sources":["../src/pin-paths.ts"],"names":[],"mappings":"AA6BA;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,WAAW,EAAE,MAAM,EACnB,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,KAAK,EAAE,MAAM,GACZ,MAAM,CA0BR"}

package/dist/pin-paths.js

@@ -0,0 +1,108 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+/**
+ * Pin path-boundary resolution for the pin-currency validator (PIN-2, PIN-5;
+ * DR-007).
+ *
+ * Every pin path is a relative POSIX-style path resolved from the pipeline
+ * directory that contains `slc.pins.json`. Absolute paths are rejected. The pin
+ * file records one path boundary (a relative POSIX path, defaulting to `.`, the
+ * pipeline directory); every local pin path must resolve inside that boundary,
+ * so `..` is permitted only when the recorded boundary is wide enough to contain
+ * the result. A violation is a {@link PinError} naming the offending field, which
+ * the currency engine maps to a malformed verdict. See specs/dev/pinning.md.
+ */
+import { realpathSync } from 'node:fs';
+import { basename, dirname, isAbsolute, relative, resolve, sep, } from 'node:path';
+import { isAbsolute as posixIsAbsolute } from 'node:path/posix';
+import { PinError } from './pins.js';
+/**
+ * Resolves a relative POSIX `relPath` against `pipelineDir`, requiring it to stay
+ * inside `boundary` (also a relative POSIX path from `pipelineDir`) (PIN-2, PIN-5).
+ *
+ * @returns the resolved absolute host path.
+ * @throws {PinError} (`pin-invalid`) when the recorded `boundary` is absolute
+ *   (naming `pathBoundary.path`), or `relPath` is absolute or escapes the
+ *   recorded boundary (naming `field`).
+ */
+export function resolvePinPath(pipelineDir, boundary, relPath, field) {
+    requireRelative(boundary, 'pathBoundary.path');
+    requireRelative(relPath, field);
+    const boundaryRoot = resolve(pipelineDir, ...splitPosix(boundary));
+    const resolved = resolve(pipelineDir, ...splitPosix(relPath));
+    if (!isInside(boundaryRoot, resolved)) {
+        throw new PinError('pin-invalid', `${field} "${relPath}" escapes the path boundary`);
+    }
+    // Lexical containment is not enough: an in-boundary symlink can resolve to
+    // bytes outside the recorded boundary. Resolve the nearest existing
+    // ancestors so the check remains fail-closed even for a missing leaf.
+    const realBoundary = canonicalProspectivePath(boundaryRoot, 'pathBoundary.path');
+    const realResolved = canonicalProspectivePath(resolved, field);
+    if (!isInside(realBoundary, realResolved)) {
+        throw new PinError('pin-invalid', `${field} "${relPath}" resolves outside the path boundary`);
+    }
+    return resolved;
+}
+/**
+ * Canonicalizes an existing path or its nearest existing ancestor. Resolving
+ * the ancestor is load-bearing for missing pinned files: `inside-link/missing`
+ * must still be rejected as a symlink escape rather than misreported stale.
+ */
+function canonicalProspectivePath(path, field) {
+    const suffix = [];
+    let cursor = path;
+    while (true) {
+        try {
+            return resolve(realpathSync.native(cursor), ...suffix.reverse());
+        }
+        catch (error) {
+            if (!isAbsentPath(error)) {
+                throw new PinError('pin-invalid', `${field} cannot be resolved safely: ${errorCode(error)}`);
+            }
+        }
+        const parent = dirname(cursor);
+        if (parent === cursor) {
+            throw new PinError('pin-invalid', `${field} cannot be resolved safely: no existing ancestor`);
+        }
+        suffix.push(basename(cursor));
+        cursor = parent;
+    }
+}
+function isAbsentPath(error) {
+    const code = errorCode(error);
+    return code === 'ENOENT' || code === 'ENOTDIR';
+}
+function errorCode(error) {
+    return typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        typeof error.code === 'string'
+        ? error.code
+        : 'unknown error';
+}
+/** Rejects an absolute (POSIX or Windows) path, naming `field` (PIN-5). */
+function requireRelative(path, field) {
+    if (path === '' || path.includes('\\') || path.includes('\0')) {
+        throw new PinError('pin-invalid', `${field} must be a non-empty portable POSIX path`);
+    }
+    if (posixIsAbsolute(path) || isWindowsAbsolute(path)) {
+        throw new PinError('pin-invalid', `${field} must be a relative path, got "${path}"`);
+    }
+}
+function splitPosix(path) {
+    return path.split('/').filter((segment) => segment.length > 0);
+}
+function isWindowsAbsolute(path) {
+    return /^[a-zA-Z]:/.test(path);
+}
+function isInside(boundaryRoot, resolved) {
+    if (resolved === boundaryRoot) {
+        return true;
+    }
+    const rel = relative(boundaryRoot, resolved);
+    return (rel !== '' &&
+        !rel.startsWith(`..${sep}`) &&
+        rel !== '..' &&
+        !isAbsolute(rel));
+}
+//# sourceMappingURL=pin-paths.js.map

package/dist/pin-paths.js.map

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

package/dist/pins.d.ts

@@ -0,0 +1,84 @@
+/** Committed pin-index filename in a pipeline directory (DR-007). */
+export declare const PINS_FILE = "slc.pins.json";
+/** The only supported pin-file schema identifier (DR-007). */
+export declare const PIN_SCHEMA = "sublang.slc.pins.v2";
+/** The only supported pin hash algorithm (DR-007). */
+export declare const PIN_HASH_ALGORITHM = "sha256";
+/** A pinned local file recorded by path and exact-byte hash (DR-007). */
+export interface PinFileRef {
+    path: string;
+    hash: string;
+}
+/** A semantic-input closure member: a local file plus a descriptive role (DR-007). */
+export interface PinSemanticInput {
+    path: string;
+    hash: string;
+    role?: string;
+}
+/** The immutable identity of the `slc.link` target consumed to produce the artifact (DR-007). */
+export interface PinLinkTarget {
+    kind: string;
+    locator: string;
+    identity: string;
+    provenance?: string;
+}
+/** A local executable dependency, optionally bound to package resolution. */
+export interface PinRuntimeDependency extends PinLinkTarget {
+    /** Bare import specifier re-resolved from the compiled entry module. */
+    specifier?: string;
+}
+/** An immutable content-addressed external input; its field shape is reserved by DR-007. */
+export type PinExternalInput = Record<string, unknown>;
+/** Provenance of the producing meta-pipeline run; never a currency input (DR-007). */
+export interface PinProducer {
+    pipeline: string;
+    slcVersion?: string;
+    metaPipelineRevision?: string;
+}
+/** The pin record for one phase (DR-007). */
+export interface PinRecord {
+    artifact: PinFileRef;
+    /** Deterministic tree identity for the reviewed files that make up the runnable artifact. */
+    artifactBundle: PinFileRef;
+    definition: PinFileRef;
+    semanticInputs: PinSemanticInput[];
+    externalInputs: PinExternalInput[];
+    /** Local executable packages/files loaded by the compiled artifact. */
+    runtimeDependencies: PinRuntimeDependency[];
+    linkTarget: PinLinkTarget;
+    producer?: PinProducer;
+}
+/** The recorded path boundary; defaults to the pipeline directory (`.`) (DR-007). */
+export interface PinPathBoundary {
+    path: string;
+}
+/** A parsed `slc.pins.json` (DR-007). */
+export interface PinFile {
+    schema: string;
+    hashAlgorithm: string;
+    pathBoundary: PinPathBoundary;
+    pins: Record<string, PinRecord>;
+}
+/** A loaded pin file: the resolved path and parsed model, or both undefined when absent. */
+export interface LoadedPins {
+    path?: string;
+    file?: PinFile;
+}
+/** Machine-readable reason a pin file was rejected (PIN-5). */
+export type PinErrorCode = 'pin-parse' | 'pin-invalid';
+/** Raised when `slc.pins.json` is not valid JSON or violates the pin schema (PIN-5). */
+export declare class PinError extends Error {
+    readonly code: PinErrorCode;
+    constructor(code: PinErrorCode, message: string);
+}
+/**
+ * Loads and validates `<pipelineDir>/slc.pins.json` (PIN-1, PIN-5).
+ *
+ * @returns `{ path, file }` when present and valid, or `{}` (no pins) when absent.
+ * @throws {PinError} when the file is not valid JSON (`pin-parse`) or violates the
+ *   schema (`pin-invalid`), with a diagnostic naming the offending field.
+ */
+export declare function loadPinFile(pipelineDir: string): Promise<LoadedPins>;
+/** Parses and structurally validates the text of a pin file into a {@link PinFile} (PIN-5). */
+export declare function parsePinFile(source: string, path?: string): PinFile;
+//# sourceMappingURL=pins.d.ts.map

package/dist/pins.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pins.d.ts","sourceRoot":"","sources":["../src/pins.ts"],"names":[],"mappings":"AAuBA,qEAAqE;AACrE,eAAO,MAAM,SAAS,kBAAkB,CAAC;AACzC,8DAA8D;AAC9D,eAAO,MAAM,UAAU,wBAAwB,CAAC;AAChD,sDAAsD;AACtD,eAAO,MAAM,kBAAkB,WAAW,CAAC;AAK3C,yEAAyE;AACzE,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,sFAAsF;AACtF,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,iGAAiG;AACjG,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,6EAA6E;AAC7E,MAAM,WAAW,oBAAqB,SAAQ,aAAa;IACzD,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,4FAA4F;AAC5F,MAAM,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAEvD,sFAAsF;AACtF,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,oBAAoB,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,6CAA6C;AAC7C,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,UAAU,CAAC;IACrB,6FAA6F;IAC7F,cAAc,EAAE,UAAU,CAAC;IAC3B,UAAU,EAAE,UAAU,CAAC;IACvB,cAAc,EAAE,gBAAgB,EAAE,CAAC;IACnC,cAAc,EAAE,gBAAgB,EAAE,CAAC;IACnC,uEAAuE;IACvE,mBAAmB,EAAE,oBAAoB,EAAE,CAAC;IAC5C,UAAU,EAAE,aAAa,CAAC;IAC1B,QAAQ,CAAC,EAAE,WAAW,CAAC;CACxB;AAED,qFAAqF;AACrF,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;CACd;AAED,yCAAyC;AACzC,MAAM,WAAW,OAAO;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,eAAe,CAAC;IAC9B,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;CACjC;AAED,4FAA4F;AAC5F,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAED,+DAA+D;AAC/D,MAAM,MAAM,YAAY,GAAG,WAAW,GAAG,aAAa,CAAC;AAEvD,wFAAwF;AACxF,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;gBAEhB,IAAI,EAAE,YAAY,EAAE,OAAO,EAAE,MAAM;CAKhD;AAED;;;;;;GAMG;AACH,wBAAsB,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAoB1E;AAWD,+FAA+F;AAC/F,wBAAgB,YAAY,CAC1B,MAAM,EAAE,MAAM,EACd,IAAI,GAAE,MAAkB,GACvB,OAAO,CAWT"}

package/dist/pins.js

@@ -0,0 +1,265 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+/**
+ * Pin-file model and strict parser for the pin-currency validator (PIN-1, PIN-5;
+ * DR-007).
+ *
+ * Loads a pipeline's committed `slc.pins.json` and structurally validates it into
+ * a typed {@link PinFile}: the supported schema identifier and hash algorithm,
+ * the optional path boundary, and each phase's pin record (with the reserved
+ * `link` key naming the link phase). An absent file yields an empty result — no
+ * pins — and a non-JSON file or a record violating the schema is rejected with a
+ * {@link PinError} naming the offending field. This module performs structural
+ * validation only: it does not hash inputs, resolve the path boundary, derive the
+ * semantic closure, or judge currency — those are later validator stages. See
+ * specs/dev/pinning.md.
+ */
+import { lstat, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { isBarePackageSpecifier } from './runtime-package.js';
+/** Committed pin-index filename in a pipeline directory (DR-007). */
+export const PINS_FILE = 'slc.pins.json';
+/** The only supported pin-file schema identifier (DR-007). */
+export const PIN_SCHEMA = 'sublang.slc.pins.v2';
+/** The only supported pin hash algorithm (DR-007). */
+export const PIN_HASH_ALGORITHM = 'sha256';
+const LINK_TARGET_KINDS = new Set(['file', 'directory', 'package']);
+const PIN_PHASE_NAME = /^[a-z0-9]+(?:-[a-z0-9]+)*2[a-z0-9]+(?:-[a-z0-9]+)*$/;
+/** Raised when `slc.pins.json` is not valid JSON or violates the pin schema (PIN-5). */
+export class PinError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'PinError';
+        this.code = code;
+    }
+}
+/**
+ * Loads and validates `<pipelineDir>/slc.pins.json` (PIN-1, PIN-5).
+ *
+ * @returns `{ path, file }` when present and valid, or `{}` (no pins) when absent.
+ * @throws {PinError} when the file is not valid JSON (`pin-parse`) or violates the
+ *   schema (`pin-invalid`), with a diagnostic naming the offending field.
+ */
+export async function loadPinFile(pipelineDir) {
+    const path = join(pipelineDir, PINS_FILE);
+    let info;
+    try {
+        info = await lstat(path);
+    }
+    catch (error) {
+        if (errorCode(error) === 'ENOENT')
+            return {};
+        throw new PinError('pin-invalid', `${path} cannot be inspected: ${errorCode(error)}`);
+    }
+    if (!info.isFile() || info.isSymbolicLink()) {
+        throw new PinError('pin-invalid', `${path} must be a regular non-symbolic-link file`);
+    }
+    const source = await readFile(path, 'utf8');
+    return { path, file: parsePinFile(source, path) };
+}
+function errorCode(error) {
+    return typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        typeof error.code === 'string'
+        ? error.code
+        : 'unknown error';
+}
+/** Parses and structurally validates the text of a pin file into a {@link PinFile} (PIN-5). */
+export function parsePinFile(source, path = PINS_FILE) {
+    let raw;
+    try {
+        raw = JSON.parse(source);
+    }
+    catch (error) {
+        throw new PinError('pin-parse', `${path} is not valid JSON: ${messageOf(error)}`);
+    }
+    return normalizePinFile(raw, path);
+}
+function normalizePinFile(value, path) {
+    const input = requireObject(value, path);
+    rejectUnknownKeys(input, new Set(['schema', 'hashAlgorithm', 'pathBoundary', 'pins']), path);
+    const schema = requireString(input.schema, `${path}.schema`);
+    if (schema !== PIN_SCHEMA) {
+        throw invalid(`${path}.schema`, `must be "${PIN_SCHEMA}"`);
+    }
+    const hashAlgorithm = requireString(input.hashAlgorithm, `${path}.hashAlgorithm`);
+    if (hashAlgorithm !== PIN_HASH_ALGORITHM) {
+        throw invalid(`${path}.hashAlgorithm`, `must be "${PIN_HASH_ALGORITHM}"`);
+    }
+    return {
+        schema,
+        hashAlgorithm,
+        pathBoundary: normalizePathBoundary(input.pathBoundary, `${path}.pathBoundary`),
+        pins: normalizePins(input.pins, `${path}.pins`),
+    };
+}
+function normalizePathBoundary(value, path) {
+    if (value === undefined) {
+        return { path: '.' };
+    }
+    const input = requireObject(value, path);
+    rejectUnknownKeys(input, new Set(['path']), path);
+    return { path: requirePortablePath(input.path, `${path}.path`) };
+}
+function normalizePins(value, path) {
+    const input = requireObject(value, path);
+    const pins = {};
+    for (const [name, record] of Object.entries(input)) {
+        if (name !== 'link' && !PIN_PHASE_NAME.test(name)) {
+            throw invalid(`${path}.${name}`, 'phase key must be "link" or a kebab-case <source>2<target> name');
+        }
+        pins[name] = normalizePinRecord(record, `${path}.${name}`);
+    }
+    return pins;
+}
+function normalizePinRecord(value, path) {
+    const input = requireObject(value, path);
+    rejectUnknownKeys(input, new Set([
+        'artifact',
+        'artifactBundle',
+        'definition',
+        'semanticInputs',
+        'externalInputs',
+        'runtimeDependencies',
+        'linkTarget',
+        'producer',
+    ]), path);
+    const record = {
+        artifact: normalizeFileRef(input.artifact, `${path}.artifact`),
+        artifactBundle: normalizeFileRef(input.artifactBundle, `${path}.artifactBundle`),
+        definition: normalizeFileRef(input.definition, `${path}.definition`),
+        linkTarget: normalizeLinkTarget(input.linkTarget, `${path}.linkTarget`),
+        semanticInputs: input.semanticInputs === undefined
+            ? []
+            : normalizeSemanticInputs(input.semanticInputs, `${path}.semanticInputs`),
+        externalInputs: input.externalInputs === undefined
+            ? []
+            : normalizeExternalInputs(input.externalInputs, `${path}.externalInputs`),
+        runtimeDependencies: normalizeRuntimeDependencies(input.runtimeDependencies, `${path}.runtimeDependencies`),
+    };
+    if (input.producer !== undefined) {
+        record.producer = normalizeProducer(input.producer, `${path}.producer`);
+    }
+    return record;
+}
+function normalizeRuntimeDependencies(value, path) {
+    return requireArray(value, path).map((entry, index) => normalizeRuntimeDependency(entry, `${path}[${index}]`));
+}
+function normalizeRuntimeDependency(value, path) {
+    const input = requireObject(value, path);
+    rejectUnknownKeys(input, new Set(['kind', 'locator', 'identity', 'provenance', 'specifier']), path);
+    const { specifier, ...linkTargetFields } = input;
+    const dependency = normalizeLinkTarget(linkTargetFields, path);
+    if (dependency.kind === 'package') {
+        dependency.specifier = requireString(specifier, `${path}.specifier`);
+        if (!isBarePackageSpecifier(dependency.specifier)) {
+            throw invalid(`${path}.specifier`, 'must be a bare package specifier');
+        }
+    }
+    else if (specifier !== undefined) {
+        throw invalid(`${path}.specifier`, 'is only valid for package dependencies');
+    }
+    return dependency;
+}
+function normalizeFileRef(value, path) {
+    const input = requireObject(value, path);
+    rejectUnknownKeys(input, new Set(['path', 'hash']), path);
+    return {
+        path: requirePortablePath(input.path, `${path}.path`),
+        hash: requireString(input.hash, `${path}.hash`),
+    };
+}
+function normalizeSemanticInputs(value, path) {
+    return requireArray(value, path).map((entry, index) => {
+        const item = `${path}[${index}]`;
+        const input = requireObject(entry, item);
+        rejectUnknownKeys(input, new Set(['path', 'hash', 'role']), item);
+        const semanticInput = {
+            path: requirePortablePath(input.path, `${item}.path`),
+            hash: requireString(input.hash, `${item}.hash`),
+        };
+        if (input.role !== undefined) {
+            semanticInput.role = requireString(input.role, `${item}.role`);
+        }
+        return semanticInput;
+    });
+}
+function normalizeLinkTarget(value, path) {
+    const input = requireObject(value, path);
+    rejectUnknownKeys(input, new Set(['kind', 'locator', 'identity', 'provenance']), path);
+    const kind = requireString(input.kind, `${path}.kind`);
+    if (!LINK_TARGET_KINDS.has(kind)) {
+        throw invalid(`${path}.kind`, 'must be one of: file, directory, package');
+    }
+    const linkTarget = {
+        kind,
+        locator: requirePortablePath(input.locator, `${path}.locator`),
+        identity: requireString(input.identity, `${path}.identity`),
+    };
+    if (input.provenance !== undefined) {
+        linkTarget.provenance = requireString(input.provenance, `${path}.provenance`);
+    }
+    return linkTarget;
+}
+function normalizeExternalInputs(value, path) {
+    return requireArray(value, path).map((entry, index) => requireObject(entry, `${path}[${index}]`));
+}
+function normalizeProducer(value, path) {
+    const input = requireObject(value, path);
+    rejectUnknownKeys(input, new Set(['pipeline', 'slcVersion', 'metaPipelineRevision']), path);
+    const producer = {
+        pipeline: requireString(input.pipeline, `${path}.pipeline`),
+    };
+    if (input.slcVersion !== undefined) {
+        producer.slcVersion = requireString(input.slcVersion, `${path}.slcVersion`);
+    }
+    if (input.metaPipelineRevision !== undefined) {
+        producer.metaPipelineRevision = requireString(input.metaPipelineRevision, `${path}.metaPipelineRevision`);
+    }
+    return producer;
+}
+function requireObject(value, path) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw invalid(path, 'must be an object');
+    }
+    return value;
+}
+function requireArray(value, path) {
+    if (!Array.isArray(value)) {
+        throw invalid(path, 'must be an array');
+    }
+    return value;
+}
+function requireString(value, path) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw invalid(path, 'must be a non-empty string');
+    }
+    return value;
+}
+function requirePortablePath(value, path) {
+    const result = requireString(value, path);
+    if (result === '' ||
+        result.includes('\\') ||
+        result.includes('\0') ||
+        result.startsWith('/') ||
+        /^[a-zA-Z]:/.test(result)) {
+        throw invalid(path, 'must be a non-empty portable relative POSIX path');
+    }
+    return result;
+}
+function rejectUnknownKeys(value, allowed, path) {
+    for (const key of Object.keys(value)) {
+        if (!allowed.has(key)) {
+            throw invalid(`${path}.${key}`, 'is an unknown field');
+        }
+    }
+}
+function invalid(field, detail) {
+    return new PinError('pin-invalid', `${field} ${detail}`);
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=pins.js.map

package/dist/pins.js.map

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