@sublang/slc 0.1.0

package/dist/execution.js

@@ -0,0 +1,207 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: 2026 SubLang International <https://sublang.ai>
+/**
+ * Execution boundary orchestrator and generic checks (DR-003).
+ *
+ * `runPhase` performs only generic mechanics (PHEXEC-1): it snapshots the
+ * protected inputs, runs an injected {@link PhaseExecutor} (interpreted in
+ * IR-001 Task 9, compiled later), then applies the generic checks — the target
+ * exists and its extension matches the declared one (PHEXEC-4); the source,
+ * objects, link target, and the chain's definition files are unchanged; and an
+ * optional `revalidate` hook confirms the pipeline chain still infers, catching
+ * added/removed phase files (PHEXEC-5). Input-mutating write-scope violations
+ * are caught after any executor outcome (PHEXEC-3, PHEXEC-6). A `blocked` or
+ * `error` result, a thrown executor, or any failed check becomes a failure
+ * report naming the phase, target, and reasons (PHEXEC-7, PHEXEC-9).
+ *
+ * The executor honors PHEXEC-2 by treating the passed definition as the
+ * semantic source of truth. Broader write-scope enforcement (sandbox or
+ * allowlist) is a host concern per DR-003 and is left as a future capability.
+ * See specs/dev/phase-execution.md.
+ */
+import { createHash } from 'node:crypto';
+import { lstat, readFile, readdir, readlink, stat } from 'node:fs/promises';
+import { extname, join } from 'node:path';
+/**
+ * Runs a single phase through the execution boundary: generic mechanics only,
+ * plus the DR-003 generic checks and blocked protocol (PHEXEC-1, PHEXEC-4..9).
+ */
+export async function runPhase(opts) {
+    const { request, phase, targetExt, executor } = opts;
+    const signal = opts.signal ?? new AbortController().signal;
+    const target = request.kind === 'compile' ? request.target : request.linked;
+    const inputs = request.kind === 'compile'
+        ? [request.source, ...(request.references ?? [])]
+        : [...request.objects, request.linkTarget];
+    const definitions = [request.definitionPath, ...(opts.definitions ?? [])];
+    const protectedPaths = [...new Set([...inputs, ...definitions])];
+    const before = await snapshot(protectedPaths);
+    const reasons = [];
+    let result = null;
+    try {
+        result = await executor.run(request, signal);
+    }
+    catch (error) {
+        reasons.push(`executor threw: ${messageOf(error)}`);
+    }
+    if (result !== null && result.status !== 'ok') {
+        reasons.push(...reasonsFor(result));
+    }
+    if (result?.status === 'ok') {
+        if (!(await exists(target))) {
+            reasons.push(`expected target "${target}" was not written`);
+        }
+        else if (extname(target) !== targetExt) {
+            reasons.push(`target "${target}" extension does not match the declared "${targetExt}"`);
+        }
+    }
+    // Protected inputs and chain definitions are re-checked after any outcome, so
+    // a mutation is caught even when the executor blocks, errors, or throws
+    // (PHEXEC-5, PHEXEC-6).
+    const after = await snapshot(protectedPaths);
+    for (const path of protectedPaths) {
+        if (before.get(path) !== after.get(path)) {
+            reasons.push(`protected path "${path}" changed during the run`);
+        }
+    }
+    if (opts.revalidate) {
+        try {
+            await opts.revalidate();
+        }
+        catch (error) {
+            reasons.push(`pipeline chain is no longer valid: ${messageOf(error)}`);
+        }
+    }
+    if (reasons.length > 0) {
+        return failure(phase, target, reasons);
+    }
+    return { ok: true, target, diagnostics: result?.diagnostics ?? [] };
+}
+/** Renders a failure report as a multi-line diagnostic string (PHEXEC-9). */
+export function formatFailureReport(report) {
+    const lines = [`slc: phase "${report.phase}" failed at "${report.target}"`];
+    for (const reason of report.reasons) {
+        lines.push(`  - ${reason}`);
+    }
+    return lines.join('\n');
+}
+function reasonsFor(result) {
+    if (result.diagnostics.length > 0) {
+        return result.diagnostics;
+    }
+    return [`phase reported ${result.status} without diagnostics`];
+}
+function failure(phase, target, reasons) {
+    return { ok: false, report: { phase, target, reasons } };
+}
+async function snapshot(paths) {
+    const entries = await Promise.all(paths.map(async (path) => [path, await pathIdentity(path)]));
+    return new Map(entries);
+}
+/**
+ * Returns a deterministic identity for one protected path. The kind prefix
+ * keeps a missing path, a file, and a directory distinct; directory identities
+ * cover every nested entry so modifying a directory link target cannot pass the
+ * DR-003 before/after check merely because `readFile(directory)` fails.
+ */
+async function pathIdentity(path) {
+    try {
+        const rootInfo = await lstat(path);
+        if (rootInfo.isSymbolicLink()) {
+            const target = await readlink(path);
+            return `symlink:${JSON.stringify(target)}:${await followedPathIdentity(path)}`;
+        }
+        return identityForInfo(path, rootInfo);
+    }
+    catch (error) {
+        if (isMissing(error))
+            return 'missing';
+        return `unreadable:${errorCode(error)}`;
+    }
+}
+async function followedPathIdentity(path) {
+    try {
+        return await identityForInfo(path, await stat(path));
+    }
+    catch (error) {
+        if (isMissing(error))
+            return 'missing';
+        return `unreadable:${errorCode(error)}`;
+    }
+}
+async function identityForInfo(path, info) {
+    if (info.isFile())
+        return `file:${await fileDigest(path)}`;
+    if (info.isDirectory())
+        return `directory:${await treeDigest(path)}`;
+    return `other:${info.mode}:${info.size}:${info.mtimeMs}:${info.ctimeMs}`;
+}
+async function fileDigest(path) {
+    return createHash('sha256')
+        .update(await readFile(path))
+        .digest('hex');
+}
+/** Exact-content identity for a directory, including empty directories and links. */
+async function treeDigest(root) {
+    const records = [];
+    await collectTreeRecords(root, '', records);
+    return createHash('sha256').update(JSON.stringify(records)).digest('hex');
+}
+async function collectTreeRecords(root, prefix, records) {
+    const entries = await readdir(root, { withFileTypes: true });
+    entries.sort((left, right) => compareNames(left.name, right.name));
+    for (const entry of entries) {
+        const relative = prefix ? `${prefix}/${entry.name}` : entry.name;
+        const path = join(root, entry.name);
+        if (entry.isDirectory()) {
+            records.push(['directory', relative]);
+            await collectTreeRecords(path, relative, records);
+        }
+        else if (entry.isFile()) {
+            records.push(['file', relative, await fileDigest(path)]);
+        }
+        else if (entry.isSymbolicLink()) {
+            records.push(['symlink', relative, await readlink(path)]);
+        }
+        else {
+            const info = await lstat(path);
+            records.push([
+                'other',
+                relative,
+                String(info.mode),
+                String(info.size),
+                String(info.mtimeMs),
+                String(info.ctimeMs),
+            ]);
+        }
+    }
+}
+function compareNames(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+function isMissing(error) {
+    const code = errorCode(error);
+    return code === 'ENOENT' || code === 'ENOTDIR';
+}
+function errorCode(error) {
+    if (typeof error === 'object' &&
+        error !== null &&
+        'code' in error &&
+        typeof error.code === 'string') {
+        return error.code;
+    }
+    return 'unknown';
+}
+async function exists(path) {
+    try {
+        await stat(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function messageOf(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+//# sourceMappingURL=execution.js.map

package/dist/execution.js.map

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

package/dist/file-capability.d.ts

@@ -0,0 +1,46 @@
+import { type Hash } from './hash.js';
+/** A virtual POSIX path inside the run root (DR-008). */
+export type SlcPath = string;
+/** Machine-readable reason a capability operation failed (DR-008). */
+export type FileErrorCode = 'invalid_path' | 'not_found' | 'not_file' | 'not_directory' | 'unauthorized' | 'stale' | 'io_error';
+/** The result of a capability operation: a value, or a coded failure (DR-008). */
+export type FileResult<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    code: FileErrorCode;
+    diagnostic: string;
+};
+/** One immediate child returned by {@link FileCapability.list} (DR-008). */
+export interface DirectoryEntry {
+    name: string;
+    kind: 'file' | 'directory';
+}
+/** The artifact-facing file capability (FCAP-1; DR-008). */
+export interface FileCapability {
+    read(path: SlcPath): Promise<FileResult<{
+        bytes: Uint8Array;
+        hash: Hash;
+    }>>;
+    list(path: SlcPath): Promise<FileResult<{
+        entries: DirectoryEntry[];
+    }>>;
+    write(path: SlcPath, bytes: Uint8Array, opts?: {
+        ifMatch?: Hash;
+    }): Promise<FileResult<{
+        hash: Hash;
+    }>>;
+}
+/**
+ * Creates a {@link FileCapability} rooted at `runRoot`, confining every operation
+ * to that directory after symlink resolution (FCAP-1..6).
+ */
+export declare function createFileCapability(runRoot: string): FileCapability;
+/**
+ * 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 declare function canonicalize(path: SlcPath): string | null;
+//# sourceMappingURL=file-capability.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"file-capability.d.ts","sourceRoot":"","sources":["../src/file-capability.ts"],"names":[],"mappings":"AAoCA,OAAO,EAAE,KAAK,IAAI,EAAa,MAAM,WAAW,CAAC;AAEjD,yDAAyD;AACzD,MAAM,MAAM,OAAO,GAAG,MAAM,CAAC;AAE7B,sEAAsE;AACtE,MAAM,MAAM,aAAa,GACrB,cAAc,GACd,WAAW,GACX,UAAU,GACV,eAAe,GACf,cAAc,GACd,OAAO,GACP,UAAU,CAAC;AAEf,kFAAkF;AAClF,MAAM,MAAM,UAAU,CAAC,CAAC,IACpB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACtB;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,aAAa,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,CAAC;AAE3D,4EAA4E;AAC5E,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,WAAW,CAAC;CAC5B;AAED,4DAA4D;AAC5D,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC;QAAE,KAAK,EAAE,UAAU,CAAC;QAAC,IAAI,EAAE,IAAI,CAAA;KAAE,CAAC,CAAC,CAAC;IAC5E,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC;QAAE,OAAO,EAAE,cAAc,EAAE,CAAA;KAAE,CAAC,CAAC,CAAC;IACxE,KAAK,CACH,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,UAAU,EACjB,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,IAAI,CAAA;KAAE,GACxB,OAAO,CAAC,UAAU,CAAC;QAAE,IAAI,EAAE,IAAI,CAAA;KAAE,CAAC,CAAC,CAAC;CACxC;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAoHpE;AAwDD;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CASzD"}

package/dist/file-capability.js

@@ -0,0 +1,234 @@
+// 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

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

package/dist/file-grants.d.ts

@@ -0,0 +1,79 @@
+/**
+ * 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

@@ -0,0 +1 @@
+{"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"}