@sublang/slc 0.1.0 → 0.3.0

package/dist/file-capability.js

@@ -1,234 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
-/**
- * Host-supplied file capability for compiled phase artifacts (FCAP-1..6; DR-008).
- *
- * A {@link FileCapability} gives a compiled artifact deterministic, confined
- * whole-file access through three operations — `read`, `list`, and `write` — over
- * virtual POSIX paths inside a per-run root. A leading `/` names the run root, not
- * an operating-system absolute path; paths are normalized (repeated separators
- * collapsed, `.` removed, `..` resolved) and confined to the root after resolving
- * symlinks, so a path that escapes the root or uses platform-absolute syntax (for
- * example a Windows drive path) is rejected as `invalid_path` (FCAP-2). Reads and
- * writes return the exact-byte `sha256:` hash with no content transformation
- * (FCAP-3, FCAP-5); writes are atomic whole-file replacements and honor an
- * `ifMatch` compare-and-swap that returns `stale` on a hash mismatch (FCAP-6);
- * listing returns only immediate children, directories before files then
- * lexicographic (FCAP-4).
- *
- * This module is the artifact-facing surface. The host-side per-run grant model
- * that authorizes each operation (default-deny, writable target/linked only) is a
- * later FCAP concern; this capability authorizes by run-root containment alone.
- * See specs/dev/file-capability.md.
- */
-import { randomUUID } from 'node:crypto';
-import { readFile, readdir, realpath, rename, stat, writeFile, } from 'node:fs/promises';
-import { basename, dirname, join, relative, resolve, sep } from 'node:path';
-import { hashBytes } from './hash.js';
-/**
- * Creates a {@link FileCapability} rooted at `runRoot`, confining every operation
- * to that directory after symlink resolution (FCAP-1..6).
- */
-export function createFileCapability(runRoot) {
-    const root = resolve(runRoot);
-    let realRoot = null;
-    const canonicalRoot = () => (realRoot ??= realpath(root));
-    async function resolveHost(path) {
-        if (isPlatformAbsolute(path)) {
-            return fail('invalid_path', `path "${path}" uses platform-absolute syntax`);
-        }
-        const segments = normalizeVirtual(path);
-        if (segments === null) {
-            return fail('invalid_path', `path "${path}" escapes the run root`);
-        }
-        const host = segments.length === 0 ? root : join(root, ...segments);
-        const real = await realpathAllowingMissing(host);
-        if (!isInside(await canonicalRoot(), real)) {
-            return fail('invalid_path', `path "${path}" escapes the run root after resolving symlinks`);
-        }
-        return { ok: true, value: host };
-    }
-    // Serialize writes per resolved host path so an ifMatch read-check-rename runs
-    // without another write to the same path interleaving at an await — making the
-    // compare-and-swap atomic across operations through this capability (FCAP-6).
-    const writeLocks = new Map();
-    function serializeWrite(host, op) {
-        const prior = writeLocks.get(host) ?? Promise.resolve();
-        const run = prior.then(op, op);
-        writeLocks.set(host, run.then(() => undefined, () => undefined));
-        return run;
-    }
-    return {
-        async read(path) {
-            const resolved = await resolveHost(path);
-            if (!resolved.ok) {
-                return resolved;
-            }
-            try {
-                const info = await stat(resolved.value);
-                if (info.isDirectory()) {
-                    return fail('not_file', `path "${path}" is a directory`);
-                }
-                const bytes = await readFile(resolved.value);
-                return { ok: true, value: { bytes, hash: hashBytes(bytes) } };
-            }
-            catch (error) {
-                return fromFsError(error, path);
-            }
-        },
-        async list(path) {
-            const resolved = await resolveHost(path);
-            if (!resolved.ok) {
-                return resolved;
-            }
-            try {
-                const info = await stat(resolved.value);
-                if (!info.isDirectory()) {
-                    return fail('not_directory', `path "${path}" is not a directory`);
-                }
-                const dirents = await readdir(resolved.value, { withFileTypes: true });
-                const entries = dirents
-                    .map((entry) => ({
-                    name: entry.name,
-                    kind: entry.isDirectory() ? 'directory' : 'file',
-                }))
-                    .sort(compareEntries);
-                return { ok: true, value: { entries } };
-            }
-            catch (error) {
-                return fromFsError(error, path);
-            }
-        },
-        async write(path, bytes, opts) {
-            const resolved = await resolveHost(path);
-            if (!resolved.ok) {
-                return resolved;
-            }
-            const host = resolved.value;
-            return serializeWrite(host, async () => {
-                try {
-                    const current = await currentHash(host);
-                    if (current.kind === 'directory') {
-                        return fail('not_file', `path "${path}" is a directory`);
-                    }
-                    if (opts?.ifMatch !== undefined && opts.ifMatch !== current.hash) {
-                        return fail('stale', `path "${path}" did not match ifMatch ${opts.ifMatch}`);
-                    }
-                    await atomicWrite(host, bytes);
-                    return { ok: true, value: { hash: hashBytes(bytes) } };
-                }
-                catch (error) {
-                    return fromFsError(error, path);
-                }
-            });
-        },
-    };
-}
-/** The current exact-byte hash of `host`, or `null` when it does not exist. */
-async function currentHash(host) {
-    try {
-        const info = await stat(host);
-        if (info.isDirectory()) {
-            return { kind: 'directory' };
-        }
-        return { kind: 'file', hash: hashBytes(await readFile(host)) };
-    }
-    catch (error) {
-        if (isNotFound(error)) {
-            return { kind: 'absent', hash: null };
-        }
-        throw error;
-    }
-}
-/** Atomically replaces or creates `host` by writing a sibling temp file and renaming. */
-async function atomicWrite(host, bytes) {
-    const temp = join(dirname(host), `.${basename(host)}.${randomUUID()}.tmp`);
-    await writeFile(temp, bytes);
-    await rename(temp, host);
-}
-/**
- * Normalizes a virtual POSIX path to in-root segments, treating a leading `/` as
- * the root and resolving `.`/`..`; returns `null` when `..` escapes the root.
- */
-function normalizeVirtual(path) {
-    const out = [];
-    for (const part of path.split('/')) {
-        if (part === '' || part === '.') {
-            continue;
-        }
-        if (part === '..') {
-            if (out.length === 0) {
-                return null;
-            }
-            out.pop();
-            continue;
-        }
-        out.push(part);
-    }
-    return out;
-}
-/** Rejects Windows drive paths and UNC syntax (DR-008 platform-absolute paths). */
-function isPlatformAbsolute(path) {
-    return /^[a-zA-Z]:[\\/]/.test(path) || path.startsWith('\\');
-}
-/**
- * Canonicalizes a virtual POSIX path to its normalized `/`-prefixed form — the key
- * the host-side grant model matches on — or `null` when the path is
- * platform-absolute or escapes the run root (FCAP-2).
- */
-export function canonicalize(path) {
-    if (isPlatformAbsolute(path)) {
-        return null;
-    }
-    const segments = normalizeVirtual(path);
-    if (segments === null) {
-        return null;
-    }
-    return `/${segments.join('/')}`;
-}
-/** Resolves `host` through symlinks, falling back to the deepest existing ancestor. */
-async function realpathAllowingMissing(host) {
-    try {
-        return await realpath(host);
-    }
-    catch (error) {
-        if (!isNotFound(error)) {
-            throw error;
-        }
-        const parent = dirname(host);
-        if (parent === host) {
-            return host;
-        }
-        return join(await realpathAllowingMissing(parent), basename(host));
-    }
-}
-function isInside(root, candidate) {
-    if (candidate === root) {
-        return true;
-    }
-    const rel = relative(root, candidate);
-    return rel !== '' && rel !== '..' && !rel.startsWith(`..${sep}`);
-}
-/** Orders entries with directories before files, then lexicographically by name. */
-function compareEntries(a, b) {
-    if (a.kind !== b.kind) {
-        return a.kind === 'directory' ? -1 : 1;
-    }
-    return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
-}
-function fromFsError(error, path) {
-    if (isNotFound(error)) {
-        return fail('not_found', `path "${path}" was not found`);
-    }
-    return fail('io_error', `path "${path}": ${messageOf(error)}`);
-}
-function isNotFound(error) {
-    return error?.code === 'ENOENT';
-}
-function fail(code, diagnostic) {
-    return { ok: false, code, diagnostic };
-}
-function messageOf(error) {
-    return error instanceof Error ? error.message : String(error);
-}
-//# sourceMappingURL=file-capability.js.map

package/dist/file-capability.js.map

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

package/dist/file-grants.d.ts

@@ -1,79 +0,0 @@
-/**
- * Host-side per-run grant model for the file capability (FCAP-11..14; DR-008).
- *
- * A compiled phase artifact reaches files only through a {@link FileCapability}
- * the host builds for that run. The capability is default-deny: an operation
- * succeeds only when its path is inside the run root (enforced by the artifact-
- * facing layer in `file-capability.ts`) and is covered by a {@link Grant} of the
- * matching access. {@link buildRunGrants} encodes the policy — the only writable
- * path is the run's `target` (compile) or `linked` (link), and read grants are
- * the run's source/object inputs, its link target when applicable, and the
- * recorded semantic-input closure, each enumerated as a file grant.
- * {@link createGuardedCapability} wraps a run-root capability with that grant set,
- * reporting `unauthorized` for any ungranted access.
- *
- * Directory listing and recursive directory reads are withheld: until a pinning
- * extension defines directory listing and subtree identities, this model grants
- * neither (DR-008), so a pinned phase cannot widen its closure at run time.
- * Scope failures (`invalid_path`, `unauthorized`) are distinguished by
- * {@link isScopeFailure} so the executor can fail them like a generic check rather
- * than a phase `BLOCKED`. See specs/dev/file-capability.md.
- */
-import { type FileCapability, type FileErrorCode, type SlcPath } from './file-capability.js';
-import { type Hash } from './hash.js';
-/** Whether a grant authorizes reading or writing (DR-008). */
-export type GrantAccess = 'read' | 'write';
-/** Whether a grant covers a file or a directory (DR-008). */
-export type GrantKind = 'file' | 'directory';
-/** Why a path is granted, for audit and diagnostics (DR-008). */
-export type GrantReason = 'source' | 'object' | 'linkTarget' | 'semanticInput' | 'target' | 'linked';
-/** One host-side authorization over a normalized virtual path (DR-008). */
-export interface Grant {
-    /** Normalized virtual path (see {@link canonicalize}). */
-    path: string;
-    access: GrantAccess;
-    kind: GrantKind;
-    /** Directory grants only: whether `list` is allowed. */
-    listing?: boolean;
-    /** Directory read grants only: whether descendant reads are covered. */
-    recursive?: boolean;
-    /** Expected identity for audit: file hash, listing identity, or subtree identity. */
-    identity?: Hash;
-    reason: GrantReason;
-}
-/** The run inputs a grant set is closed over (DR-008; the closure to authorize). */
-export interface RunGrantSpec {
-    kind: 'compile' | 'link';
-    /** Compile source input. */
-    source?: SlcPath;
-    /** Link object artifacts. */
-    objects?: readonly SlcPath[];
-    /** Runtime link target, when the run consumes one. */
-    linkTarget?: SlcPath;
-    /** Compile writable target. */
-    target?: SlcPath;
-    /** Link writable artifact. */
-    linked?: SlcPath;
-    /** Recorded semantic-input closure files, each enumerated (DR-007). */
-    semanticInputs?: readonly {
-        path: SlcPath;
-        identity?: Hash;
-    }[];
-}
-/**
- * Builds the default-deny grant set for a run (FCAP-12, FCAP-13).
- *
- * The only writable grant is the run's `target` (compile) or `linked` (link); read
- * grants enumerate the source/object inputs, the link target when present, and the
- * semantic-input closure. Directory listing and recursive reads are not granted.
- */
-export declare function buildRunGrants(spec: RunGrantSpec): Grant[];
-/**
- * Wraps a run-root capability with a grant set, denying every ungranted access
- * (FCAP-11). Path validity and run-root containment are left to the wrapped
- * capability, so an invalid or escaping path still reports `invalid_path`.
- */
-export declare function createGuardedCapability(runRoot: string, grants: readonly Grant[]): FileCapability;
-/** Reports whether a capability error is a host-enforced scope failure (FCAP-14). */
-export declare function isScopeFailure(code: FileErrorCode): boolean;
-//# sourceMappingURL=file-grants.d.ts.map

package/dist/file-grants.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"file-grants.d.ts","sourceRoot":"","sources":["../src/file-grants.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,aAAa,EAElB,KAAK,OAAO,EAGb,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EAAE,KAAK,IAAI,EAAE,MAAM,WAAW,CAAC;AAEtC,8DAA8D;AAC9D,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,OAAO,CAAC;AAE3C,6DAA6D;AAC7D,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,WAAW,CAAC;AAE7C,iEAAiE;AACjE,MAAM,MAAM,WAAW,GACnB,QAAQ,GACR,QAAQ,GACR,YAAY,GACZ,eAAe,GACf,QAAQ,GACR,QAAQ,CAAC;AAEb,2EAA2E;AAC3E,MAAM,WAAW,KAAK;IACpB,0DAA0D;IAC1D,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,WAAW,CAAC;IACpB,IAAI,EAAE,SAAS,CAAC;IAChB,wDAAwD;IACxD,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,wEAAwE;IACxE,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,qFAAqF;IACrF,QAAQ,CAAC,EAAE,IAAI,CAAC;IAChB,MAAM,EAAE,WAAW,CAAC;CACrB;AAED,oFAAoF;AACpF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,SAAS,GAAG,MAAM,CAAC;IACzB,4BAA4B;IAC5B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,6BAA6B;IAC7B,OAAO,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IAC7B,sDAAsD;IACtD,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,+BAA+B;IAC/B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,8BAA8B;IAC9B,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,uEAAuE;IACvE,cAAc,CAAC,EAAE,SAAS;QAAE,IAAI,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,EAAE,IAAI,CAAA;KAAE,EAAE,CAAC;CAChE;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,YAAY,GAAG,KAAK,EAAE,CAqB1D;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,EAAE,MAAM,EACf,MAAM,EAAE,SAAS,KAAK,EAAE,GACvB,cAAc,CAahB;AAED,qFAAqF;AACrF,wBAAgB,cAAc,CAAC,IAAI,EAAE,aAAa,GAAG,OAAO,CAE3D"}

package/dist/file-grants.js

@@ -1,133 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
-/**
- * Host-side per-run grant model for the file capability (FCAP-11..14; DR-008).
- *
- * A compiled phase artifact reaches files only through a {@link FileCapability}
- * the host builds for that run. The capability is default-deny: an operation
- * succeeds only when its path is inside the run root (enforced by the artifact-
- * facing layer in `file-capability.ts`) and is covered by a {@link Grant} of the
- * matching access. {@link buildRunGrants} encodes the policy — the only writable
- * path is the run's `target` (compile) or `linked` (link), and read grants are
- * the run's source/object inputs, its link target when applicable, and the
- * recorded semantic-input closure, each enumerated as a file grant.
- * {@link createGuardedCapability} wraps a run-root capability with that grant set,
- * reporting `unauthorized` for any ungranted access.
- *
- * Directory listing and recursive directory reads are withheld: until a pinning
- * extension defines directory listing and subtree identities, this model grants
- * neither (DR-008), so a pinned phase cannot widen its closure at run time.
- * Scope failures (`invalid_path`, `unauthorized`) are distinguished by
- * {@link isScopeFailure} so the executor can fail them like a generic check rather
- * than a phase `BLOCKED`. See specs/dev/file-capability.md.
- */
-import { canonicalize, createFileCapability, } from './file-capability.js';
-import {} from './hash.js';
-/**
- * Builds the default-deny grant set for a run (FCAP-12, FCAP-13).
- *
- * The only writable grant is the run's `target` (compile) or `linked` (link); read
- * grants enumerate the source/object inputs, the link target when present, and the
- * semantic-input closure. Directory listing and recursive reads are not granted.
- */
-export function buildRunGrants(spec) {
-    const grants = [];
-    if (spec.kind === 'compile' && spec.target !== undefined) {
-        grants.push(fileGrant(spec.target, 'write', 'target'));
-    }
-    if (spec.kind === 'link' && spec.linked !== undefined) {
-        grants.push(fileGrant(spec.linked, 'write', 'linked'));
-    }
-    if (spec.source !== undefined) {
-        grants.push(fileGrant(spec.source, 'read', 'source'));
-    }
-    for (const object of spec.objects ?? []) {
-        grants.push(fileGrant(object, 'read', 'object'));
-    }
-    if (spec.linkTarget !== undefined) {
-        grants.push(fileGrant(spec.linkTarget, 'read', 'linkTarget'));
-    }
-    for (const input of spec.semanticInputs ?? []) {
-        grants.push(fileGrant(input.path, 'read', 'semanticInput', input.identity));
-    }
-    return grants;
-}
-/**
- * Wraps a run-root capability with a grant set, denying every ungranted access
- * (FCAP-11). Path validity and run-root containment are left to the wrapped
- * capability, so an invalid or escaping path still reports `invalid_path`.
- */
-export function createGuardedCapability(runRoot, grants) {
-    const inner = createFileCapability(runRoot);
-    return {
-        async read(path) {
-            return authorize(grants, path, 'read') ?? inner.read(path);
-        },
-        async list(path) {
-            return authorizeList(grants, path) ?? inner.list(path);
-        },
-        async write(path, bytes, opts) {
-            return authorize(grants, path, 'write') ?? inner.write(path, bytes, opts);
-        },
-    };
-}
-/** Reports whether a capability error is a host-enforced scope failure (FCAP-14). */
-export function isScopeFailure(code) {
-    return code === 'invalid_path' || code === 'unauthorized';
-}
-/**
- * Returns an `unauthorized` denial when no grant covers `path` for `access`, or
- * `null` to defer to the wrapped capability (which validates the path itself).
- */
-function authorize(grants, path, access) {
-    const canonical = canonicalize(path);
-    if (canonical === null) {
-        return null;
-    }
-    if (!covers(grants, canonical, access)) {
-        return deny(`no ${access} grant covers "${path}"`);
-    }
-    return null;
-}
-function authorizeList(grants, path) {
-    const canonical = canonicalize(path);
-    if (canonical === null) {
-        return null;
-    }
-    const granted = grants.some((grant) => grant.access === 'read' &&
-        grant.path === canonical &&
-        grant.kind === 'directory' &&
-        grant.listing === true);
-    return granted ? null : deny(`no listing grant covers "${path}"`);
-}
-function covers(grants, canonical, access) {
-    return grants.some((grant) => {
-        if (grant.access !== access) {
-            return false;
-        }
-        if (grant.path === canonical) {
-            return true;
-        }
-        return (access === 'read' &&
-            grant.kind === 'directory' &&
-            grant.recursive === true &&
-            isUnder(grant.path, canonical));
-    });
-}
-function isUnder(ancestor, candidate) {
-    const prefix = ancestor === '/' ? '/' : `${ancestor}/`;
-    return candidate.startsWith(prefix);
-}
-function fileGrant(path, access, reason, identity) {
-    const canonical = canonicalize(path);
-    if (canonical === null) {
-        throw new Error(`grant path "${path}" is not a valid run-root path`);
-    }
-    return identity === undefined
-        ? { path: canonical, access, kind: 'file', reason }
-        : { path: canonical, access, kind: 'file', identity, reason };
-}
-function deny(diagnostic) {
-    return { ok: false, code: 'unauthorized', diagnostic };
-}
-//# sourceMappingURL=file-grants.js.map

package/dist/file-grants.js.map

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