@try-works/dsh-tool-mode 0.0.0-stage → 0.5.44

package/lib/approval.js

@@ -0,0 +1,510 @@
+/**
+ * SEC-09 — the approval state machine for management-sensitive changes.
+ *
+ * A management-sensitive mutation (enabling a model, installing/replacing an
+ * extension, revoking a credential, changing a model URL or provider, …) must pass an
+ * EXPLICIT operator decision before it happens. This module is the standalone state
+ * machine for that flow; it deliberately owns no host wiring and no I/O:
+ *
+ *   pending ──approve──▶ approved ──commit()──▶ committed   (terminal)
+ *      │                     │
+ *      ├──deny──▶ denied    └── TTL ──▶ expired              (terminal)
+ *      └── TTL ──▶ expired
+ *
+ * Properties this module guarantees:
+ * - **No commit without an approval.** `commit()` on a pending request throws
+ *   `approval/pending` SYNCHRONOUSLY; there is no promise to await, so a deployment
+ *   with no approval UI fails promptly instead of hanging.
+ * - **One-shot commit.** The first successful commit moves the record to
+ *   `committed`; every later commit throws `approval/already-committed`.
+ * - **Idempotent decisions.** Repeating the SAME decision returns the unchanged
+ *   record (including its original decision timestamp); the opposite decision after a
+ *   decision is `approval/already-decided`.
+ * - **Scope-bound.** The request stores the exact decision scope; a commit must name
+ *   exactly that scope. An approval for one extension or one tool cannot authorize
+ *   another.
+ * - **TTL on an injected clock.** Expiry is evaluated lazily on every read/mutation
+ *   against `now()`; tests never depend on wall time.
+ * - **Plain-JSON durable-safe state.** Records contain only strings, numbers, nulls,
+ *   booleans and one nested scope object. Unknown caller fields are dropped, so a
+ *   token or API key passed by mistake is never stored or re-serialized.
+ * - **Deterministic ids.** By default the id is a hash of the request content and the
+ *   injected request time, so the same request at the same instant has the same id.
+ *
+ * @module @try-works/dsh-tool-mode/approval
+ */
+import { createHash } from 'node:crypto';
+/** Every management-sensitive request kind this module admits. */
+export const APPROVAL_KINDS = [
+    'model-enable',
+    'model-disable',
+    'model-reset',
+    'extension-install',
+    'extension-activate',
+    'extension-deactivate',
+    'extension-uninstall',
+    'extension-prepare',
+    'extension-commit',
+    'extension-rollback',
+    'credential-revoke',
+    'model-url-change',
+    'model-provider-change',
+];
+/** The terminal/non-terminal states a record can be in. */
+export const APPROVAL_STATES = ['pending', 'approved', 'denied', 'committed', 'expired'];
+/** What an approval is scoped to. */
+export const APPROVAL_SCOPE_KINDS = ['model', 'extension', 'tool', 'credential', 'provider'];
+/** A refusal with a stable machine-readable code. */
+export class ApprovalError extends Error {
+    /** The stable refusal code. */
+    code;
+    /**
+     * @param code - the stable refusal code.
+     * @param message - the concrete explanation (the code is prefixed).
+     */
+    constructor(code, message) {
+        super(`approval/${code.replace(/^approval\//, '')}: ${message}`);
+        this.name = 'ApprovalError';
+        this.code = code;
+    }
+}
+/** The scope kinds each request kind may cover. */
+const SCOPE_BY_KIND = Object.freeze({
+    'model-enable': ['model', 'tool'],
+    'model-disable': ['model', 'tool'],
+    'model-reset': ['model', 'tool'],
+    'model-url-change': ['model', 'tool'],
+    'model-provider-change': ['model', 'provider', 'tool'],
+    'extension-install': ['extension', 'tool'],
+    'extension-activate': ['extension', 'tool'],
+    'extension-deactivate': ['extension', 'tool'],
+    'extension-uninstall': ['extension', 'tool'],
+    'extension-prepare': ['extension', 'tool'],
+    'extension-commit': ['extension', 'tool'],
+    'extension-rollback': ['extension', 'tool'],
+    'credential-revoke': ['credential'],
+});
+/** Five minutes: long enough for an operator, short enough to age out. */
+const DEFAULT_TTL_MS = 5 * 60 * 1000;
+/** Seven days: an absurd TTL is a configuration mistake, not a longer approval. */
+const MAX_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+const MAX_ID_LENGTH = 200;
+const MAX_OPERATOR_LENGTH = 200;
+const MAX_REASON_LENGTH = 2000;
+const MAX_SCOPE_ID_LENGTH = 200;
+const ID_PATTERN = /^apr_[0-9a-f]{16}$/;
+/** A plain object (arrays and null excluded). */
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** A finite timestamp. */
+function isTimestamp(value) {
+    return typeof value === 'number' && Number.isFinite(value);
+}
+/** Trim and bound one required text field. */
+function requireText(value, field, maxLength) {
+    if (typeof value !== 'string') {
+        throw new ApprovalError('approval/invalid-request', `${field} must be a string`);
+    }
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+        throw new ApprovalError('approval/invalid-request', `${field} must not be empty`);
+    }
+    if (trimmed.length > maxLength) {
+        throw new ApprovalError('approval/invalid-request', `${field} must be at most ${String(maxLength)} characters`);
+    }
+    return trimmed;
+}
+/** Validate and normalise one scope. */
+function normalizeScope(value, field = 'scope') {
+    if (!isRecord(value)) {
+        throw new ApprovalError('approval/invalid-request', `${field} must be an object`);
+    }
+    const kind = value['kind'];
+    // SAFETY: the value is a plain string and the membership test below proves it is
+    // one of the literal scope kinds before the assertion is reached.
+    const scopeKinds = APPROVAL_SCOPE_KINDS;
+    if (typeof kind !== 'string' || !scopeKinds.includes(kind)) {
+        throw new ApprovalError('approval/invalid-request', `${field}.kind must be one of ${APPROVAL_SCOPE_KINDS.join(', ')}`);
+    }
+    const id = requireText(value['id'], `${field}.id`, MAX_SCOPE_ID_LENGTH);
+    // SAFETY: membership in APPROVAL_SCOPE_KINDS was established immediately above.
+    return { kind: kind, id };
+}
+/** Validate one request kind and its scope together. */
+function normalizeKindAndScope(kindValue, scopeValue) {
+    const kind = kindValue;
+    // SAFETY: the value is a plain string and the membership test below proves it is
+    // one of the literal approval kinds before any assertion is reached.
+    const approvalKinds = APPROVAL_KINDS;
+    if (typeof kind !== 'string' || !approvalKinds.includes(kind)) {
+        throw new ApprovalError('approval/invalid-request', `kind must be one of ${APPROVAL_KINDS.join(', ')}`);
+    }
+    const scope = normalizeScope(scopeValue);
+    // SAFETY: membership in APPROVAL_KINDS was established immediately above.
+    const permitted = SCOPE_BY_KIND[kind];
+    if (!permitted.includes(scope.kind)) {
+        throw new ApprovalError('approval/invalid-request', `${kind} cannot be scoped to ${scope.kind}; permitted scope kinds are ${permitted.join(', ')}`);
+    }
+    // SAFETY: membership in APPROVAL_KINDS was established immediately above.
+    return { kind: kind, scope };
+}
+/** Validate a TTL, or return undefined when absent. */
+function normalizeTtl(value) {
+    if (value === undefined)
+        return undefined;
+    if (!isTimestamp(value) || value <= 0 || value > MAX_TTL_MS) {
+        throw new ApprovalError('approval/invalid-request', `ttlMs must be a positive number no greater than ${String(MAX_TTL_MS)}`);
+    }
+    return Math.floor(value);
+}
+/** The deterministic default id: request content + request time. */
+function defaultIdFactory(input, requestedAt) {
+    const digest = createHash('sha256')
+        .update(JSON.stringify([input.kind, input.scope.kind, input.scope.id, input.operator, input.reason, requestedAt]))
+        .digest('hex');
+    return `apr_${digest.slice(0, 16)}`;
+}
+/** Validate a restored record; unknown keys are dropped by construction. */
+function restoreRecord(value, index) {
+    const where = `records[${String(index)}]`;
+    if (!isRecord(value))
+        throw new ApprovalError('approval/invalid-serialization', `${where} must be an object`);
+    const id = value['id'];
+    if (typeof id !== 'string' || id.length === 0 || id.length > MAX_ID_LENGTH) {
+        throw new ApprovalError('approval/invalid-serialization', `${where}.id must be a non-empty bounded string`);
+    }
+    const { kind, scope } = (() => {
+        try {
+            return normalizeKindAndScope(value['kind'], value['scope']);
+        }
+        catch (error) {
+            throw new ApprovalError('approval/invalid-serialization', `${where} has an invalid kind/scope: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    })();
+    const operator = (() => {
+        try {
+            return requireText(value['operator'], `${where}.operator`, MAX_OPERATOR_LENGTH);
+        }
+        catch (error) {
+            throw new ApprovalError('approval/invalid-serialization', error instanceof Error ? error.message : String(error));
+        }
+    })();
+    const reason = (() => {
+        try {
+            return requireText(value['reason'], `${where}.reason`, MAX_REASON_LENGTH);
+        }
+        catch (error) {
+            throw new ApprovalError('approval/invalid-serialization', error instanceof Error ? error.message : String(error));
+        }
+    })();
+    const requestedAt = value['requestedAt'];
+    const expiresAt = value['expiresAt'];
+    if (!isTimestamp(requestedAt) || !isTimestamp(expiresAt) || expiresAt <= requestedAt) {
+        throw new ApprovalError('approval/invalid-serialization', `${where} has invalid timestamps`);
+    }
+    const state = value['state'];
+    // SAFETY: the value is a plain string and the membership test below proves it is a
+    // declared approval state before the assertion is reached.
+    const states = APPROVAL_STATES;
+    if (typeof state !== 'string' || !states.includes(state)) {
+        throw new ApprovalError('approval/invalid-serialization', `${where}.state must be one of ${APPROVAL_STATES.join(', ')}`);
+    }
+    const decidedAt = value['decidedAt'];
+    const decidedBy = value['decidedBy'];
+    const decisionReason = value['decisionReason'];
+    const committedAt = value['committedAt'];
+    if (!(decidedAt === null || isTimestamp(decidedAt))) {
+        throw new ApprovalError('approval/invalid-serialization', `${where}.decidedAt must be a timestamp or null`);
+    }
+    if (!(decidedBy === null || (typeof decidedBy === 'string' && decidedBy.length > 0))) {
+        throw new ApprovalError('approval/invalid-serialization', `${where}.decidedBy must be a non-empty string or null`);
+    }
+    if ((decidedAt === null) !== (decidedBy === null)) {
+        throw new ApprovalError('approval/invalid-serialization', `${where} must carry decidedAt and decidedBy together`);
+    }
+    if (!(decisionReason === null || typeof decisionReason === 'string')) {
+        throw new ApprovalError('approval/invalid-serialization', `${where}.decisionReason must be a string or null`);
+    }
+    if (!(committedAt === null || isTimestamp(committedAt))) {
+        throw new ApprovalError('approval/invalid-serialization', `${where}.committedAt must be a timestamp or null`);
+    }
+    if (state === 'committed' && committedAt === null) {
+        throw new ApprovalError('approval/invalid-serialization', `${where} is committed without a commit time`);
+    }
+    if (state !== 'committed' && committedAt !== null) {
+        throw new ApprovalError('approval/invalid-serialization', `${where} has a commit time but is not committed`);
+    }
+    if ((state === 'approved' || state === 'denied' || state === 'committed') && decidedAt === null) {
+        throw new ApprovalError('approval/invalid-serialization', `${where} is ${state} without a decision`);
+    }
+    if (state === 'pending' && decidedAt !== null) {
+        throw new ApprovalError('approval/invalid-serialization', `${where} is pending but already has a decision`);
+    }
+    // SAFETY: membership in APPROVAL_STATES was established above; the state-dependent
+    // invariants below are checked before this record is returned.
+    return {
+        id,
+        kind,
+        scope,
+        operator,
+        reason,
+        requestedAt,
+        expiresAt,
+        state: state,
+        decidedAt,
+        decidedBy,
+        decisionReason,
+        committedAt,
+    };
+}
+/**
+ * The in-memory approval store. One instance per host process, restored from its
+ * snapshot at boot (see the wiring contract in the task report).
+ */
+export class ApprovalStore {
+    #now;
+    #defaultTtlMs;
+    #idFactory;
+    #records = new Map();
+    /**
+     * @param options - clock, default TTL and id derivation (all injectable).
+     */
+    constructor(options = {}) {
+        const now = options.now ?? Date.now;
+        if (typeof now !== 'function')
+            throw new ApprovalError('approval/invalid-request', 'now must be a function');
+        this.#now = now;
+        const ttl = options.defaultTtlMs ?? DEFAULT_TTL_MS;
+        if (!isTimestamp(ttl) || ttl <= 0 || ttl > MAX_TTL_MS) {
+            throw new ApprovalError('approval/invalid-request', `defaultTtlMs must be positive and no greater than ${String(MAX_TTL_MS)}`);
+        }
+        this.#defaultTtlMs = Math.floor(ttl);
+        this.#idFactory = options.idFactory ?? defaultIdFactory;
+    }
+    /** The default lifetime new requests receive. */
+    get defaultTtlMs() {
+        return this.#defaultTtlMs;
+    }
+    /**
+     * Record a pending request.
+     *
+     * A repeated request (same content at the same injected instant) returns the
+     * EXISTING record rather than resetting its TTL or decision.
+     * @param input - the request facts (kind, scope, operator, reason, optional TTL).
+     * @returns the pending record (a plain-JSON copy).
+     */
+    request(input) {
+        if (!isRecord(input))
+            throw new ApprovalError('approval/invalid-request', 'a request must be an object');
+        const { kind, scope } = normalizeKindAndScope(input.kind, input.scope);
+        const operator = requireText(input.operator, 'operator', MAX_OPERATOR_LENGTH);
+        const reason = requireText(input.reason, 'reason', MAX_REASON_LENGTH);
+        const ttl = normalizeTtl(input.ttlMs) ?? this.#defaultTtlMs;
+        const requestedAt = this.#now();
+        if (!isTimestamp(requestedAt))
+            throw new ApprovalError('approval/invalid-request', 'now() must return a finite timestamp');
+        const id = this.#idFactory({ kind, scope, operator, reason }, requestedAt);
+        if (typeof id !== 'string' || id.length === 0 || id.length > MAX_ID_LENGTH) {
+            throw new ApprovalError('approval/invalid-request', 'the id factory must return a non-empty bounded string');
+        }
+        const existing = this.#records.get(id);
+        if (existing !== undefined)
+            return this.#view(existing);
+        const record = {
+            id,
+            kind,
+            scope,
+            operator,
+            reason,
+            requestedAt,
+            expiresAt: requestedAt + ttl,
+            state: 'pending',
+            decidedAt: null,
+            decidedBy: null,
+            decisionReason: null,
+            committedAt: null,
+        };
+        this.#records.set(id, record);
+        return this.#view(record);
+    }
+    /**
+     * Read one record, applying lazy TTL expiry.
+     * @param id - the approval id.
+     * @returns the record (a plain-JSON copy).
+     */
+    describe(id) {
+        return this.#view(this.#require(id));
+    }
+    /** Every record, oldest first (expiry applied). */
+    list() {
+        return [...this.#records.values()]
+            .map(record => this.#view(record))
+            .sort((left, right) => left.requestedAt - right.requestedAt || left.id.localeCompare(right.id));
+    }
+    /**
+     * Apply an explicit operator decision.
+     *
+     * Repeating the SAME decision is idempotent and returns the unchanged record; the
+     * opposite decision after a decision is `approval/already-decided`.
+     * @param id - the approval id.
+     * @param decision - approve/deny, the decider and an optional note.
+     * @returns the decided record.
+     */
+    decide(id, decision) {
+        const record = this.#require(id);
+        this.#expire(record);
+        if (!isRecord(decision) || typeof decision.approve !== 'boolean') {
+            throw new ApprovalError('approval/invalid-request', 'a decision must carry a boolean approve');
+        }
+        if (record.state === 'expired') {
+            throw new ApprovalError('approval/expired', `request ${record.id} expired at ${String(record.expiresAt)}; it cannot be decided`);
+        }
+        if (record.state === 'committed') {
+            throw new ApprovalError('approval/already-committed', `request ${record.id} was already committed at ${String(record.committedAt)}; it cannot be decided`);
+        }
+        const wanted = decision.approve ? 'approved' : 'denied';
+        if (record.state === wanted)
+            return this.#copy(record);
+        if (record.state === 'approved' || record.state === 'denied') {
+            throw new ApprovalError('approval/already-decided', `request ${record.id} is already ${record.state}; the opposite decision is refused`);
+        }
+        const decidedBy = requireText(decision.decidedBy, 'decidedBy', MAX_OPERATOR_LENGTH);
+        const decisionReason = decision.reason === undefined ? null : requireText(decision.reason, 'decision reason', MAX_REASON_LENGTH);
+        const decidedAt = this.#now();
+        if (!isTimestamp(decidedAt))
+            throw new ApprovalError('approval/invalid-request', 'now() must return a finite timestamp');
+        record.state = wanted;
+        record.decidedAt = decidedAt;
+        record.decidedBy = decidedBy;
+        record.decisionReason = decisionReason;
+        return this.#copy(record);
+    }
+    /**
+     * Consume an approved request for exactly its recorded scope.
+     *
+     * One-shot: the first successful call commits; every later call (and any call on a
+     * pending, denied or expired record) throws a named error WITHOUT waiting.
+     * @param id - the approval id.
+     * @param scope - the exact subject the caller is about to mutate.
+     * @returns the committed record.
+     */
+    commit(id, scope) {
+        const record = this.#require(id);
+        this.#expire(record);
+        if (record.state === 'pending') {
+            throw new ApprovalError('approval/pending', `request ${record.id} is pending; no operator has approved it`);
+        }
+        if (record.state === 'denied') {
+            throw new ApprovalError('approval/denied', `request ${record.id} was denied by ${String(record.decidedBy)}`);
+        }
+        if (record.state === 'expired') {
+            throw new ApprovalError('approval/expired', `request ${record.id} expired at ${String(record.expiresAt)}; it cannot be committed`);
+        }
+        if (record.state === 'committed') {
+            throw new ApprovalError('approval/already-committed', `request ${record.id} was already committed at ${String(record.committedAt)}`);
+        }
+        const requested = normalizeScope(scope, 'commit scope');
+        if (requested.kind !== record.scope.kind || requested.id !== record.scope.id) {
+            throw new ApprovalError('approval/scope-mismatch', `request ${record.id} is approved for ${record.scope.kind} ${record.scope.id}, not ${requested.kind} ${requested.id}`);
+        }
+        const committedAt = this.#now();
+        if (!isTimestamp(committedAt))
+            throw new ApprovalError('approval/invalid-request', 'now() must return a finite timestamp');
+        record.state = 'committed';
+        record.committedAt = committedAt;
+        return this.#copy(record);
+    }
+    /**
+     * The durable snapshot. Only the declared fields are serialized, so a caller that
+     * passed a token by mistake cannot leak it through this channel.
+     * @returns a plain-JSON snapshot.
+     */
+    toJSON() {
+        return {
+            version: 1,
+            defaultTtlMs: this.#defaultTtlMs,
+            records: this.list().map(record => this.#copy(record)),
+        };
+    }
+    /**
+     * Restore a store from {@link toJSON} output.
+     * @param value - the parsed snapshot.
+     * @param options - clock, optional TTL override and optional id factory.
+     * @returns the restored store.
+     */
+    static fromJSON(value, options = {}) {
+        if (!isRecord(value)) {
+            throw new ApprovalError('approval/invalid-serialization', 'snapshot must be an object with version 1 and a records array');
+        }
+        const version = value['version'];
+        const rawRecords = value['records'];
+        const snapshotTtl = value['defaultTtlMs'];
+        if (version !== 1 || !Array.isArray(rawRecords)) {
+            throw new ApprovalError('approval/invalid-serialization', 'snapshot must be an object with version 1 and a records array');
+        }
+        if (!isTimestamp(snapshotTtl) || snapshotTtl <= 0 || snapshotTtl > MAX_TTL_MS) {
+            throw new ApprovalError('approval/invalid-serialization', 'snapshot defaultTtlMs must be a valid TTL');
+        }
+        let store;
+        try {
+            store = new ApprovalStore({ ...options, defaultTtlMs: options.defaultTtlMs ?? snapshotTtl });
+        }
+        catch (error) {
+            throw new ApprovalError('approval/invalid-serialization', error instanceof Error ? error.message : String(error));
+        }
+        for (const [index, raw] of rawRecords.entries()) {
+            const record = restoreRecord(raw, index);
+            if (store.#records.has(record.id)) {
+                throw new ApprovalError('approval/invalid-serialization', `duplicate record id ${record.id}`);
+            }
+            store.#records.set(record.id, record);
+        }
+        return store;
+    }
+    /** Look up a record or throw the named unknown-id refusal. */
+    #require(id) {
+        if (typeof id !== 'string' || id.length === 0) {
+            throw new ApprovalError('approval/invalid-request', 'an approval id must be a non-empty string');
+        }
+        const record = this.#records.get(id);
+        if (record === undefined)
+            throw new ApprovalError('approval/unknown-id', `no approval record has id ${id}`);
+        return record;
+    }
+    /** Apply lazy TTL expiry to pending/approved records. */
+    #expire(record) {
+        if (record.state !== 'pending' && record.state !== 'approved')
+            return;
+        const now = this.#now();
+        if (isTimestamp(now) && now >= record.expiresAt)
+            record.state = 'expired';
+    }
+    /** A plain-JSON view, with expiry applied. */
+    #view(record) {
+        this.#expire(record);
+        return this.#copy(record);
+    }
+    /** A deep, plain-JSON copy of one record. */
+    #copy(record) {
+        return {
+            id: record.id,
+            kind: record.kind,
+            scope: { kind: record.scope.kind, id: record.scope.id },
+            operator: record.operator,
+            reason: record.reason,
+            requestedAt: record.requestedAt,
+            expiresAt: record.expiresAt,
+            state: record.state,
+            decidedAt: record.decidedAt,
+            decidedBy: record.decidedBy,
+            decisionReason: record.decisionReason,
+            committedAt: record.committedAt,
+        };
+    }
+}
+/** Whether a restored/default id has the module's deterministic shape. */
+export function isDeterministicApprovalId(id) {
+    return typeof id === 'string' && ID_PATTERN.test(id);
+}
+//# sourceMappingURL=approval.js.map

package/lib/asset-acquisition.d.ts

@@ -0,0 +1,149 @@
+/**
+ * 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-tool-mode/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;
+};
+/**
+ * Whether two hex digests name the same content.
+ *
+ * HEX CASE IS NOT SEMANTIC. `crypto` emits lower case, while an extension lock may
+ * record either case (Laya's records upper case). Comparing the raw strings rejected
+ * a correctly seeded blob, so the acquisition fell through to the lock's prose source
+ * and failed with `Failed to parse URL` even though the verified bytes were on disk.
+ * @param left - one hex digest.
+ * @param right - the other hex digest.
+ * @returns true when they differ only in case.
+ */
+export declare function sameDigest(left: string, right: string): 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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"}