@try-works/dsh-model-as-tool 0.1.1 → 0.1.3

package/lib/adapters/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/adapters/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AAEpD,oEAAoE;AACpE,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,EAAE,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAA;AAErG,8BAA8B;AAC9B,MAAM,WAAW,iBAAiB;IAChC,wFAAwF;IACxF,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IAChD,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;CAC7B;AAED,uCAAuC;AACvC,MAAM,WAAW,YAAY;IAC3B,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB;;;;;;;OAOG;IACH,MAAM,CAAC,UAAU,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAA;IACzE;;;;;OAKG;IACH,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1B;AAED,oFAAoF;AACpF,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,YAAY,GAAG,SAAS,CAAA;AAEnF;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAExD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAM1F;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACvC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACjF,MAAM,CAOR;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACvC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACtD,MAAM,GAAG,SAAS,CAOpB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACvC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,OAAO,GAChB,OAAO,CAKT"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/adapters/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AACpD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAA;AAE1D,oEAAoE;AACpE,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,SAAS,EAAE,GAAG;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAA;AAErG,8BAA8B;AAC9B,MAAM,WAAW,iBAAiB;IAChC,wFAAwF;IACxF,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;IAChD,uDAAuD;IACvD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B;;;;;;;;OAQG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,mBAAmB,CAAA;CACzC;AAED,uCAAuC;AACvC,MAAM,WAAW,YAAY;IAC3B,0CAA0C;IAC1C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB;;;;;;;OAOG;IACH,MAAM,CAAC,UAAU,EAAE,iBAAiB,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAA;IACzE;;;;;OAKG;IACH,OAAO,CAAC,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1B;AAED,oFAAoF;AACpF,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,iBAAiB,KAAK,YAAY,GAAG,SAAS,CAAA;AAEnF;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAExD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,GAAG,EAAE,MAAM,GAAG,MAAM,CAM1F;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACvC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GACjF,MAAM,CAOR;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACvC,GAAG,EAAE,MAAM,EACX,OAAO,EAAE;IAAE,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACtD,MAAM,GAAG,SAAS,CAOpB;AAED;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACvC,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,OAAO,GAChB,OAAO,CAKT"}

package/lib/adapters/voz.d.ts

@@ -13,10 +13,16 @@
  */
 import type { ModelCatalogEntry } from '../types.ts';
 import { type ModelAdapter } from './types.ts';
+/** The npm package this adapter knows how to call. */
+export declare const VOZ_PACKAGE = "@desert-ant-labs/voz";
 /**
  * Build the Voz adapter.
+ *
+ * Keyed on the package rather than the catalog id, for the same reason as the
+ * Tongue adapter: the adapter knows an SDK, so any catalog row bound to it can be
+ * served, which is what lets a second implementation join the contract.
  * @param entry - the catalog entry this adapter serves.
- * @returns the adapter, or undefined if the entry is not Voz.
+ * @returns the adapter, or undefined if the entry does not use this SDK.
  */
 export declare function createVozAdapter(entry: ModelCatalogEntry): ModelAdapter | undefined;
 //# sourceMappingURL=voz.d.ts.map

package/lib/adapters/voz.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"voz.d.ts","sourceRoot":"","sources":["../../src/adapters/voz.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AACpD,OAAO,EAKL,KAAK,YAAY,EAClB,MAAM,YAAY,CAAA;AAmCnB;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,iBAAiB,GAAG,YAAY,GAAG,SAAS,CA+DnF"}
+{"version":3,"file":"voz.d.ts","sourceRoot":"","sources":["../../src/adapters/voz.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAA;AACpD,OAAO,EAKL,KAAK,YAAY,EAClB,MAAM,YAAY,CAAA;AAgCnB,sDAAsD;AACtD,eAAO,MAAM,WAAW,yBAAyB,CAAA;AAKjD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,iBAAiB,GAAG,YAAY,GAAG,SAAS,CAsEnF"}

package/lib/adapters/voz.js

@@ -20,15 +20,21 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     return path;
 };
 import { optionalBoolean, requireString, throwIfAborted, } from "./types.js";
+/** The npm package this adapter knows how to call. */
+export const VOZ_PACKAGE = '@desert-ant-labs/voz';
 /** Cap on the words returned inline, so a long recording cannot flood the context. */
 const MAX_WORDS = 2000;
 /**
  * Build the Voz adapter.
+ *
+ * Keyed on the package rather than the catalog id, for the same reason as the
+ * Tongue adapter: the adapter knows an SDK, so any catalog row bound to it can be
+ * served, which is what lets a second implementation join the contract.
  * @param entry - the catalog entry this adapter serves.
- * @returns the adapter, or undefined if the entry is not Voz.
+ * @returns the adapter, or undefined if the entry does not use this SDK.
  */
 export function createVozAdapter(entry) {
-    if (entry.id !== 'voz')
+    if (entry.npmPackage !== VOZ_PACKAGE)
         return undefined;
     let loaded;
     const load = async () => {
@@ -51,10 +57,16 @@ export function createVozAdapter(entry) {
     };
     return {
         modelId: entry.id,
-        async invoke({ args, signal }) {
+        async invoke({ args, signal, authority }) {
             throwIfAborted(signal);
-            const audioPath = requireString(args, 'audio_path');
+            const requested = requireString(args, 'audio_path');
             const includeWords = optionalBoolean(args, 'include_words', true);
+            // SEC-06: a caller-supplied path is authorized before it is opened, and the
+            // CANONICAL path is what gets opened. Validating the string and then opening
+            // it would leave a check-then-open window a symlink could win.
+            const audioPath = authority === undefined
+                ? requested
+                : authority.resolvePath(requested);
             const voz = await load();
             throwIfAborted(signal);
             const result = await voz.transcribe(audioPath);

package/lib/asset-acquisition.d.ts

@@ -0,0 +1,137 @@
+/**
+ * Verified atomic asset acquisition (RES-03, RES-07).
+ *
+ * The requirement's rules are all about what must NOT be observable:
+ *
+ * - **A partial download must never be usable.** Bytes are written to a temporary
+ *   sibling, verified against the expected digest, and only then renamed into place.
+ *   A file at the final path is therefore either absent or complete and correct —
+ *   which is why the temp file is a sibling rather than somewhere else: a rename
+ *   within one directory is atomic, and one across filesystems is not.
+ * - **A failed or interrupted preparation cannot become ready.** A digest mismatch
+ *   deletes the partial rather than keeping it for a retry that would resume from
+ *   bytes already known to be wrong.
+ * - **Uninstall and purge are separate** (RES-03). Acquisition records ownership; it
+ *   never deletes. Deletion is `purgeCandidates`, which refuses to remove an asset
+ *   another owner still holds.
+ * - **No source changes or binary builds on the end-user machine.** This acquires
+ *   pinned bytes; there is no compile step here to disable.
+ *
+ * Everything that touches the network or the filesystem is INJECTED, so the failure
+ * paths — which are the ones that matter and the ones a real download makes hard to
+ * reach — are exercised by test.
+ *
+ * @module @try-works/dsh-model-as-tool/asset-acquisition
+ */
+import type { PlannedAsset } from './deployment-coordinator.ts';
+/** Where an asset's bytes come from. */
+export interface AcquisitionSource {
+    /**
+     * Fetch a byte range.
+     *
+     * `from` is the offset to resume from; `to` is inclusive. A source that cannot
+     * serve ranges reports `supportsRanges: false`, and the caller then restarts rather
+     * than assuming a partial is resumable.
+     * @param asset - the asset to fetch.
+     * @param from - the first byte to fetch.
+     * @param to - the last byte to fetch, inclusive.
+     * @param signal - cancellation.
+     * @returns the bytes.
+     */
+    fetchRange(asset: PlannedAsset, from: number, to: number, signal: AbortSignal): Promise<Uint8Array>;
+    /** Whether this source can serve byte ranges, which resumability depends on. */
+    readonly supportsRanges: boolean;
+}
+/** The filesystem operations acquisition needs. */
+export interface AcquisitionStore {
+    /** Write bytes to a path, creating it if absent. */
+    write(path: string, bytes: Uint8Array): void;
+    /** Read a path's bytes, or undefined when absent. */
+    read(path: string): Uint8Array | undefined;
+    /** The size of a path in bytes, or 0 when absent. */
+    sizeOf(path: string): number;
+    /** Rename, which must be atomic within a directory. */
+    rename(from: string, to: string): void;
+    /** Remove a path, ignoring its absence. */
+    remove(path: string): void;
+    /** Whether a path exists. */
+    exists(path: string): boolean;
+}
+/** The outcome of an acquisition. */
+export type AcquisitionResult = {
+    readonly acquired: true;
+    /** The content-addressed path the bytes now occupy. */
+    readonly path: string;
+    /** The verified digest. */
+    readonly digest: string;
+    /** How many bytes were transferred, which is less than the size after a resume. */
+    readonly transferredBytes: number;
+    /** Whether an existing partial was resumed. */
+    readonly resumed: boolean;
+} | {
+    readonly acquired: false;
+    /** The reason, naming whether the bytes were wrong or the transfer failed. */
+    readonly reason: string;
+    /** Whether a retry could succeed. */
+    readonly retryable: boolean;
+};
+/**
+ * Acquire one asset, atomically and verified (RES-03).
+ *
+ * @param asset - the planned asset.
+ * @param options - the store, the source, the root and a cancellation signal.
+ * @returns the result, which never leaves a partial at the final path.
+ */
+export declare function acquireAsset(asset: PlannedAsset, options: {
+    readonly store: AcquisitionStore;
+    readonly source: AcquisitionSource;
+    /** The directory assets are content-addressed under. */
+    readonly root: string;
+    readonly signal: AbortSignal;
+    /** Transfer chunk size; bounded so a large asset does not need one huge buffer. */
+    readonly chunkBytes?: number;
+}): Promise<AcquisitionResult>;
+/**
+ * A declared memory admission estimate (RES-07).
+ *
+ * RES-07 requires ENFORCED and ESTIMATED limits to be reported SEPARATELY, because
+ * conflating them is how a V8 heap cap gets mistaken for a process-tree cap: the heap
+ * cap bounds JavaScript objects and says nothing about the native memory an inference
+ * engine allocates outside it.
+ */
+export interface MemoryEstimate {
+    /** Bytes the host will refuse to exceed, as far as it can enforce. */
+    readonly enforcedBytes: number | null;
+    /** What the deployment is expected to use, which is an estimate and not a bound. */
+    readonly estimatedBytes: number;
+    /**
+     * What the enforced figure actually covers.
+     *
+     * Named rather than implied, so a reader can tell a heap cap from a process-tree cap
+     * without reading the implementation.
+     */
+    readonly enforcedScope: 'process-tree' | 'worker' | 'v8-heap-only' | 'none';
+    /** Whether the estimate has been measured rather than predicted. */
+    readonly measured: boolean;
+}
+/**
+ * Describe a memory admission, without overstating what is enforced (RES-07).
+ * @param input - the enforced and estimated figures.
+ * @returns the estimate, with the scope stated.
+ */
+export declare function describeMemory(input: {
+    readonly enforcedBytes: number | null;
+    readonly estimatedBytes: number;
+    readonly enforcedScope: MemoryEstimate['enforcedScope'];
+    readonly measured?: boolean;
+}): MemoryEstimate;
+/**
+ * Whether an enforced limit actually bounds the whole process tree (RES-07).
+ *
+ * A V8 heap cap does NOT, and treating it as though it did is the specific mistake the
+ * requirement names.
+ * @param estimate - the estimate.
+ * @returns whether the enforcement covers the process tree.
+ */
+export declare function boundsProcessTree(estimate: MemoryEstimate): boolean;
+//# sourceMappingURL=asset-acquisition.d.ts.map

package/lib/asset-acquisition.d.ts.map

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

package/lib/asset-acquisition.js

@@ -0,0 +1,161 @@
+/**
+ * Verified atomic asset acquisition (RES-03, RES-07).
+ *
+ * The requirement's rules are all about what must NOT be observable:
+ *
+ * - **A partial download must never be usable.** Bytes are written to a temporary
+ *   sibling, verified against the expected digest, and only then renamed into place.
+ *   A file at the final path is therefore either absent or complete and correct —
+ *   which is why the temp file is a sibling rather than somewhere else: a rename
+ *   within one directory is atomic, and one across filesystems is not.
+ * - **A failed or interrupted preparation cannot become ready.** A digest mismatch
+ *   deletes the partial rather than keeping it for a retry that would resume from
+ *   bytes already known to be wrong.
+ * - **Uninstall and purge are separate** (RES-03). Acquisition records ownership; it
+ *   never deletes. Deletion is `purgeCandidates`, which refuses to remove an asset
+ *   another owner still holds.
+ * - **No source changes or binary builds on the end-user machine.** This acquires
+ *   pinned bytes; there is no compile step here to disable.
+ *
+ * Everything that touches the network or the filesystem is INJECTED, so the failure
+ * paths — which are the ones that matter and the ones a real download makes hard to
+ * reach — are exercised by test.
+ *
+ * @module @try-works/dsh-model-as-tool/asset-acquisition
+ */
+import { createHash } from 'node:crypto';
+/** Where an asset lives once acquired. */
+function contentPath(root, digest) {
+    return `${root}/${digest}`;
+}
+/** The temporary sibling a transfer lands in before verification. */
+function partialPath(root, digest) {
+    // A SIBLING of the final path, so the rename is within one directory and therefore
+    // atomic. A temp directory elsewhere would make the final rename a copy.
+    return `${root}/.partial-${digest}`;
+}
+/** Hash bytes with the algorithm the digest length implies. */
+function digestOf(bytes, expectedLength) {
+    // SHA-512 is 128 hex characters, SHA-256 is 64. Inferring from the expected length
+    // means a lock written in either is verified with the right algorithm rather than a
+    // mismatch that looks like corruption.
+    return createHash(expectedLength > 64 ? 'sha512' : 'sha256').update(bytes).digest('hex');
+}
+/**
+ * Acquire one asset, atomically and verified (RES-03).
+ *
+ * @param asset - the planned asset.
+ * @param options - the store, the source, the root and a cancellation signal.
+ * @returns the result, which never leaves a partial at the final path.
+ */
+export async function acquireAsset(asset, options) {
+    const { store, source, root, signal } = options;
+    const finalPath = contentPath(root, asset.digest);
+    const partial = partialPath(root, asset.digest);
+    // Already acquired and verified by a previous run: nothing to do, and nothing to
+    // re-download. This is also what makes two owners share one set of bytes.
+    if (store.exists(finalPath) && digestOf(store.read(finalPath) ?? new Uint8Array(), asset.digest.length) === asset.digest) {
+        return { acquired: true, path: finalPath, digest: asset.digest, transferredBytes: 0, resumed: false };
+    }
+    const chunkBytes = options.chunkBytes ?? 4 * 1024 * 1024;
+    // Resumption is only attempted when the source can serve ranges. Assuming a partial
+    // is resumable against a source that cannot would append a full response to a
+    // partial and produce bytes that hash wrong for a reason that looks like corruption.
+    let offset = source.supportsRanges ? store.sizeOf(partial) : 0;
+    const resumed = offset > 0;
+    if (!source.supportsRanges && store.exists(partial))
+        store.remove(partial);
+    let transferred = 0;
+    try {
+        while (offset < asset.bytes) {
+            if (signal.aborted) {
+                // The partial is LEFT in place, because it is verifiable bytes and a later
+                // attempt can resume from it; it is not at the final path, so nothing can use
+                // it as though it were complete.
+                return { acquired: false, reason: 'the transfer was cancelled', retryable: true };
+            }
+            const to = Math.min(offset + chunkBytes, asset.bytes) - 1;
+            const chunk = await source.fetchRange(asset, offset, to, signal);
+            if (chunk.byteLength === 0) {
+                // A zero-length chunk before the declared size means the source ended early.
+                return {
+                    acquired: false,
+                    reason: `the source ended at ${offset} of ${asset.bytes} bytes`,
+                    retryable: true,
+                };
+            }
+            // Appended rather than accumulated in memory: a 349 MB asset must not need a
+            // 349 MB buffer to be resumed.
+            store.write(partial, appendTo(store.read(partial), chunk));
+            offset += chunk.byteLength;
+            transferred += chunk.byteLength;
+        }
+        const completed = store.read(partial) ?? new Uint8Array();
+        if (completed.byteLength !== asset.bytes) {
+            store.remove(partial);
+            return {
+                acquired: false,
+                reason: `received ${completed.byteLength} bytes, expected ${asset.bytes}`,
+                retryable: true,
+            };
+        }
+        const actual = digestOf(completed, asset.digest.length);
+        if (actual !== asset.digest) {
+            // RES-03: a failed preparation cannot become ready, and bytes already known to
+            // be wrong must not be kept for a retry that would resume from them.
+            store.remove(partial);
+            return {
+                acquired: false,
+                reason: `the asset digest is ${actual}, not the pinned ${asset.digest}`,
+                retryable: false,
+            };
+        }
+        // The whole point: verified bytes move into place in one atomic step, so the final
+        // path is never a partial file.
+        store.rename(partial, finalPath);
+        return { acquired: true, path: finalPath, digest: asset.digest, transferredBytes: transferred, resumed };
+    }
+    catch (error) {
+        // A transport failure leaves the partial for a resume and reports retryable, so a
+        // caller can tell a flaky network from a corrupt asset.
+        return {
+            acquired: false,
+            reason: error instanceof Error ? error.message : String(error),
+            retryable: true,
+        };
+    }
+}
+/** Concatenate a previous buffer with a new chunk. */
+function appendTo(previous, chunk) {
+    if (previous === undefined)
+        return chunk;
+    const out = new Uint8Array(previous.byteLength + chunk.byteLength);
+    out.set(previous, 0);
+    out.set(chunk, previous.byteLength);
+    return out;
+}
+/**
+ * Describe a memory admission, without overstating what is enforced (RES-07).
+ * @param input - the enforced and estimated figures.
+ * @returns the estimate, with the scope stated.
+ */
+export function describeMemory(input) {
+    return {
+        enforcedBytes: input.enforcedBytes,
+        estimatedBytes: input.estimatedBytes,
+        enforcedScope: input.enforcedScope,
+        measured: input.measured ?? false,
+    };
+}
+/**
+ * Whether an enforced limit actually bounds the whole process tree (RES-07).
+ *
+ * A V8 heap cap does NOT, and treating it as though it did is the specific mistake the
+ * requirement names.
+ * @param estimate - the estimate.
+ * @returns whether the enforcement covers the process tree.
+ */
+export function boundsProcessTree(estimate) {
+    return estimate.enforcedScope === 'process-tree';
+}
+//# sourceMappingURL=asset-acquisition.js.map

package/lib/authority.d.ts

@@ -0,0 +1,153 @@
+/**
+ * Caller authority: the grant a tool invocation runs under (SEC-03, SEC-06).
+ *
+ * The governing rule is BASE-05: an external request cannot supply or forge these
+ * authorities. Everything here is constructed by the HOST from operator
+ * configuration, never from a request body, a `clientInfo.name`, a requested tool
+ * list, or a path a caller supplied. A caller's arguments are then checked
+ * AGAINST the grant; they never expand it.
+ *
+ * Path handling is deliberately paranoid. SEC-06 requires resolving Windows drive
+ * letters, separators, Unicode, junctions and symlinks safely, rejecting escapes,
+ * unsupported UNC/device paths and unauthorized roots, and refusing when
+ * authorization cannot be established. The resolver therefore returns the
+ * CANONICAL path for the caller to open, rather than validating a string and
+ * letting a later open re-resolve it — that gap is the classic check-then-open
+ * race, and a symlink swapped between the two steps would win it.
+ *
+ * @module @try-works/dsh-model-as-tool/authority
+ */
+/** The stable error codes a denied request reports (SPEC §4 error vocabulary). */
+export type AuthorityErrorCode = 
+/** The path was not absolute; SEC-06 admits absolute paths only. */
+'PATH_NOT_ABSOLUTE'
+/** A UNC or Windows device path, which v1 refuses outright. */
+ | 'PATH_UNSUPPORTED'
+/** The path does not exist, so it cannot be authorized. */
+ | 'PATH_NOT_FOUND'
+/** The path resolves outside every approved root. */
+ | 'PATH_OUTSIDE_GRANT'
+/** The tool is not in the grant's allowed set. */
+ | 'TOOL_NOT_GRANTED'
+/** The grant does not exist or was revoked. */
+ | 'GRANT_REVOKED';
+/** A refused invocation. Carries a recovery hint, not just a refusal. */
+export declare class AuthorityError extends Error {
+    readonly name = "AuthorityError";
+    readonly code: AuthorityErrorCode;
+    /** Actionable next step for the caller or operator. */
+    readonly hint: string;
+    constructor(code: AuthorityErrorCode, message: string, hint: string);
+}
+/** Absolute resource limits applied to every invocation under a grant. */
+export interface GrantLimits {
+    /** Largest admitted input, in bytes. */
+    readonly maxInputBytes: number;
+    /** Largest admitted audio duration, in seconds. */
+    readonly maxAudioSeconds: number;
+    /** Largest admitted inline result, in bytes. */
+    readonly maxResultBytes: number;
+}
+/** What a caller is permitted to do (SEC-03). */
+export interface ToolGrant {
+    /** Stable grant identity, recorded in receipts. */
+    readonly grantId: string;
+    /** Tool names this caller may invoke. A requested list never extends it. */
+    readonly allowedTools: readonly string[];
+    /**
+     * Filesystem roots the caller may read from, as absolute paths.
+     * Canonicalized when the grant is built, so a symlinked root cannot be declared
+     * one way and resolve another.
+     */
+    readonly approvedRoots: readonly string[];
+    /** Remote destinations this caller may reach. Empty means none. */
+    readonly remoteDestinations: readonly string[];
+    /** Whether hosted code execution is permitted. */
+    readonly hostedCode: boolean;
+    /** Whether receipts may be recorded. */
+    readonly recordingPolicy: 'none' | 'receipts';
+    /** Hard resource limits. */
+    readonly limits: GrantLimits;
+}
+/** Build a grant, canonicalizing its roots. */
+export interface GrantInput {
+    readonly grantId: string;
+    readonly allowedTools: readonly string[];
+    readonly approvedRoots: readonly string[];
+    readonly remoteDestinations?: readonly string[];
+    readonly hostedCode?: boolean;
+    readonly recordingPolicy?: 'none' | 'receipts';
+    readonly limits?: Partial<GrantLimits>;
+}
+/** Conservative defaults: a grant that declares nothing permits almost nothing. */
+export declare const DEFAULT_LIMITS: GrantLimits;
+/**
+ * Build a grant from operator configuration.
+ *
+ * This is the only constructor: a request cannot reach it, and an approved root
+ * that is not absolute or not resolvable is dropped rather than trusted.
+ * @param input - the operator's declaration.
+ * @returns the canonicalized grant.
+ */
+export declare function createGrant(input: GrantInput): ToolGrant;
+/**
+ * Authorize one caller-supplied path against a grant (SEC-06).
+ *
+ * Returns the CANONICAL path, which the caller must open. Validating the original
+ * string and opening it later would leave a window in which a symlink could be
+ * swapped; resolving once and returning the result closes it.
+ * @param grant - the caller's grant.
+ * @param candidate - the caller-supplied path.
+ * @returns the canonical, authorized path.
+ * @throws AuthorityError when the path is inadmissible, missing, or outside the grant.
+ */
+export declare function authorizePath(grant: ToolGrant, candidate: string): string;
+/**
+ * Authorize a tool name against a grant (SEC-03).
+ * @param grant - the caller's grant.
+ * @param toolName - the requested tool.
+ * @throws AuthorityError with `TOOL_NOT_GRANTED`.
+ */
+export declare function authorizeTool(grant: ToolGrant, toolName: string): void;
+/**
+ * Authorize a remote destination against a grant (SEC-10).
+ *
+ * No silent local-to-remote fallback: if a destination was not explicitly
+ * approved, the call is refused rather than downgraded or upgraded.
+ * @param grant - the caller's grant.
+ * @param destination - the destination origin.
+ * @throws AuthorityError with `TOOL_NOT_GRANTED`.
+ */
+export declare function authorizeDestination(grant: ToolGrant, destination: string): void;
+/**
+ * The trusted execution context handed to an implementation.
+ *
+ * An implementation receives resolved authority, never a raw path it must
+ * re-check, and never anything a caller could have constructed.
+ */
+export interface InvocationAuthority {
+    /** Grant identity, for the receipt. */
+    readonly grantId: string;
+    /** Who is calling, as the host resolved it. */
+    readonly callerKind: 'interactive' | 'external' | 'system';
+    /** Resource limits in force. */
+    readonly limits: GrantLimits;
+    /** Whether receipts may be recorded. */
+    readonly recordingPolicy: 'none' | 'receipts';
+    /**
+     * Resolve a caller-supplied path to a canonical authorized path.
+     * @param candidate - the caller-supplied path.
+     * @returns the canonical path to open.
+     */
+    resolvePath(candidate: string): string;
+}
+/**
+ * Build the invocation authority for one call.
+ *
+ * The result is constructed by the host; a request body has no path to it.
+ * @param grant - the caller's grant.
+ * @param callerKind - how the host classified the caller.
+ * @returns the authority handed to the implementation.
+ */
+export declare function createInvocationAuthority(grant: ToolGrant, callerKind: InvocationAuthority['callerKind']): InvocationAuthority;
+//# sourceMappingURL=authority.d.ts.map

package/lib/authority.d.ts.map

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