agentfootprint 9.20.0 → 9.22.0

package/dist/artifacts/index.js

@@ -0,0 +1,47 @@
+"use strict";
+/**
+ * artifacts — barrel.
+ *
+ * The claim-check store: shapes + the five-verb port (`types`), the ref
+ * grammar (`naming`), the payload laws (`payload`), the eviction law
+ * (`retention`), the shared put pipeline (`minting`), three adapters, the
+ * `ctx.artifacts` capability (`capability`) — and the Phase-2 data legs:
+ * ref arguments at dispatch (`wants`), the hand-to-the-screen verb
+ * (`present`), and the placement threshold (`placement`). See README.md in
+ * this folder for the one-job map and the import direction.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.placedToolResult = exports.placedResultKind = exports.isPlacedToolResult = exports.assertArtifactPlacement = exports.presentArtifact = exports.PRESENT_TOOL_NAME = exports.wantsNeedsStoreRefusal = exports.resolveToolWants = exports.assertToolWants = exports.unconfiguredArtifacts = exports.bindArtifacts = exports.UnreadableArtifactStoreError = exports.sqliteArtifacts = exports.UnreadableArtifactFileError = exports.fileArtifacts = exports.DEFAULT_IN_MEMORY_ARTIFACT_RETENTION = exports.inMemoryArtifacts = exports.mintArtifactRef = exports.isArtifactRef = exports.ARTIFACT_REF_PREFIX = exports.UnknownParentRefError = exports.InvalidArtifactError = exports.ArtifactIntegrityError = void 0;
+var types_js_1 = require("./types.js");
+Object.defineProperty(exports, "ArtifactIntegrityError", { enumerable: true, get: function () { return types_js_1.ArtifactIntegrityError; } });
+Object.defineProperty(exports, "InvalidArtifactError", { enumerable: true, get: function () { return types_js_1.InvalidArtifactError; } });
+Object.defineProperty(exports, "UnknownParentRefError", { enumerable: true, get: function () { return types_js_1.UnknownParentRefError; } });
+var naming_js_1 = require("./naming.js");
+Object.defineProperty(exports, "ARTIFACT_REF_PREFIX", { enumerable: true, get: function () { return naming_js_1.ARTIFACT_REF_PREFIX; } });
+Object.defineProperty(exports, "isArtifactRef", { enumerable: true, get: function () { return naming_js_1.isArtifactRef; } });
+Object.defineProperty(exports, "mintArtifactRef", { enumerable: true, get: function () { return naming_js_1.mintArtifactRef; } });
+var inMemoryArtifacts_js_1 = require("./inMemoryArtifacts.js");
+Object.defineProperty(exports, "inMemoryArtifacts", { enumerable: true, get: function () { return inMemoryArtifacts_js_1.inMemoryArtifacts; } });
+Object.defineProperty(exports, "DEFAULT_IN_MEMORY_ARTIFACT_RETENTION", { enumerable: true, get: function () { return inMemoryArtifacts_js_1.DEFAULT_IN_MEMORY_ARTIFACT_RETENTION; } });
+var fileArtifacts_js_1 = require("./fileArtifacts.js");
+Object.defineProperty(exports, "fileArtifacts", { enumerable: true, get: function () { return fileArtifacts_js_1.fileArtifacts; } });
+Object.defineProperty(exports, "UnreadableArtifactFileError", { enumerable: true, get: function () { return fileArtifacts_js_1.UnreadableArtifactFileError; } });
+var sqliteArtifacts_js_1 = require("./sqliteArtifacts.js");
+Object.defineProperty(exports, "sqliteArtifacts", { enumerable: true, get: function () { return sqliteArtifacts_js_1.sqliteArtifacts; } });
+Object.defineProperty(exports, "UnreadableArtifactStoreError", { enumerable: true, get: function () { return sqliteArtifacts_js_1.UnreadableArtifactStoreError; } });
+var capability_js_1 = require("./capability.js");
+Object.defineProperty(exports, "bindArtifacts", { enumerable: true, get: function () { return capability_js_1.bindArtifacts; } });
+Object.defineProperty(exports, "unconfiguredArtifacts", { enumerable: true, get: function () { return capability_js_1.unconfiguredArtifacts; } });
+var wants_js_1 = require("./wants.js");
+Object.defineProperty(exports, "assertToolWants", { enumerable: true, get: function () { return wants_js_1.assertToolWants; } });
+Object.defineProperty(exports, "resolveToolWants", { enumerable: true, get: function () { return wants_js_1.resolveToolWants; } });
+Object.defineProperty(exports, "wantsNeedsStoreRefusal", { enumerable: true, get: function () { return wants_js_1.wantsNeedsStoreRefusal; } });
+var present_js_1 = require("./present.js");
+Object.defineProperty(exports, "PRESENT_TOOL_NAME", { enumerable: true, get: function () { return present_js_1.PRESENT_TOOL_NAME; } });
+Object.defineProperty(exports, "presentArtifact", { enumerable: true, get: function () { return present_js_1.presentArtifact; } });
+var placement_js_1 = require("./placement.js");
+Object.defineProperty(exports, "assertArtifactPlacement", { enumerable: true, get: function () { return placement_js_1.assertArtifactPlacement; } });
+Object.defineProperty(exports, "isPlacedToolResult", { enumerable: true, get: function () { return placement_js_1.isPlacedToolResult; } });
+Object.defineProperty(exports, "placedResultKind", { enumerable: true, get: function () { return placement_js_1.placedResultKind; } });
+Object.defineProperty(exports, "placedToolResult", { enumerable: true, get: function () { return placement_js_1.placedToolResult; } });
+//# sourceMappingURL=index.js.map

package/dist/artifacts/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/artifacts/index.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;GAUG;;;AAEH,uCAgBoB;AAflB,kHAAA,sBAAsB,OAAA;AACtB,gHAAA,oBAAoB,OAAA;AACpB,iHAAA,qBAAqB,OAAA;AAcvB,yCAAkF;AAAzE,gHAAA,mBAAmB,OAAA;AAAE,0GAAA,aAAa,OAAA;AAAE,4GAAA,eAAe,OAAA;AAE5D,+DAKgC;AAJ9B,yHAAA,iBAAiB,OAAA;AACjB,4IAAA,oCAAoC,OAAA;AAItC,uDAI4B;AAH1B,iHAAA,aAAa,OAAA;AACb,+HAAA,2BAA2B,OAAA;AAG7B,2DAK8B;AAJ5B,qHAAA,eAAe,OAAA;AACf,kIAAA,4BAA4B,OAAA;AAI9B,iDAUyB;AATvB,8GAAA,aAAa,OAAA;AACb,sHAAA,qBAAqB,OAAA;AASvB,uCAOoB;AANlB,2GAAA,eAAe,OAAA;AACf,4GAAA,gBAAgB,OAAA;AAChB,kHAAA,sBAAsB,OAAA;AAKxB,2CAMsB;AALpB,+GAAA,iBAAiB,OAAA;AACjB,6GAAA,eAAe,OAAA;AAKjB,+CAOwB;AANtB,uHAAA,uBAAuB,OAAA;AACvB,kHAAA,kBAAkB,OAAA;AAClB,gHAAA,gBAAgB,OAAA;AAChB,gHAAA,gBAAgB,OAAA"}

package/dist/artifacts/minting.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * artifacts/minting — the shared half of every adapter's `put`.
+ *
+ * Validate the input, prove the parents, measure the bytes, compute the
+ * digest when asked, mint the ref, stamp the meta. Three adapters call this
+ * one pipeline so a put refused by `inMemoryArtifacts` is refused in the same
+ * words by `sqliteArtifacts` — one law, three storage mechanics.
+ *
+ * What stays with the adapter: holding the bytes, applying the retention
+ * plan, answering the other four verbs.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.prepareArtifact = void 0;
+const naming_js_1 = require("./naming.js");
+const payload_js_1 = require("./payload.js");
+const retention_js_1 = require("./retention.js");
+const types_js_1 = require("./types.js");
+/**
+ * Validate a put and build the meta it mints.
+ *
+ * @param input          the caller's put.
+ * @param resolveParent  scope-bound existence check for parent validation.
+ * @param retention      the adapter's policy — stamps `expiresAt` (stated, never sprung).
+ * @param now            the adapter's clock, injected so tests own time.
+ * @throws InvalidArtifactError   for input this library cannot store faithfully.
+ * @throws UnknownParentRefError  for a parent that does not resolve in scope.
+ */
+async function prepareArtifact(input, resolveParent, retention, now) {
+    if (typeof input.kind !== 'string' || input.kind.trim() === '') {
+        throw new types_js_1.InvalidArtifactError(`kind is ${JSON.stringify(input.kind)}. kind is the consumer vocabulary a redeemer ` +
+            `decides from ('dataset/rows', 'chart/spec') — a blank one makes every head() useless. ` +
+            `Name what this artifact IS.`);
+    }
+    if (typeof input.mediaType !== 'string' || input.mediaType.trim() === '') {
+        throw new types_js_1.InvalidArtifactError(`mediaType is ${JSON.stringify(input.mediaType)}. Name the payload's MIME type ` +
+            `('application/json', 'text/csv', …) so a consumer can decode without guessing.`);
+    }
+    if (input.expiresAt !== undefined &&
+        (!Number.isFinite(input.expiresAt) || input.expiresAt <= now)) {
+        throw new types_js_1.InvalidArtifactError(`expiresAt = ${String(input.expiresAt)} is not a future unix-ms timestamp. An artifact ` +
+            `born expired would resolve for nobody; state a future time, or omit the field.`);
+    }
+    if (input.digest !== undefined && input.digest !== 'sha-256') {
+        throw new types_js_1.InvalidArtifactError(`digest = ${JSON.stringify(input.digest)} is not an algorithm this store computes. ` +
+            `'sha-256' is the one shipped; omit the field for no digest.`);
+    }
+    // Parents are FACTS, proven at birth — a foreign key that cannot dangle.
+    if (input.parentRefs !== undefined && input.parentRefs.length > 0) {
+        const unresolved = [];
+        for (const parent of input.parentRefs) {
+            if (!(0, naming_js_1.isArtifactRef)(parent) || !(await resolveParent(parent)))
+                unresolved.push(parent);
+        }
+        if (unresolved.length > 0)
+            throw new types_js_1.UnknownParentRefError(unresolved);
+    }
+    // Measure (and refuse the unserializable) BEFORE minting, so a refused put
+    // never burns a ref.
+    const bytes = (0, payload_js_1.measureArtifactBytes)(input.data);
+    const digest = input.digest === 'sha-256' ? await (0, payload_js_1.computeArtifactDigest)(input.data) : undefined;
+    const expiresAt = (0, retention_js_1.resolveExpiresAt)(input.expiresAt, retention, now);
+    const meta = {
+        ref: (0, naming_js_1.mintArtifactRef)(),
+        kind: input.kind,
+        mediaType: input.mediaType,
+        bytes,
+        createdAt: now,
+        ...(input.label !== undefined && { label: input.label }),
+        ...(digest !== undefined && { digest }),
+        ...(expiresAt !== undefined && { expiresAt }),
+        ...(input.origin !== undefined && { origin: input.origin }),
+        ...(input.parentRefs !== undefined &&
+            input.parentRefs.length > 0 && { parentRefs: [...input.parentRefs] }),
+    };
+    return { meta, bytes };
+}
+exports.prepareArtifact = prepareArtifact;
+//# sourceMappingURL=minting.js.map

package/dist/artifacts/minting.js.map

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

package/dist/artifacts/naming.js

@@ -0,0 +1,64 @@
+"use strict";
+/**
+ * artifacts/naming — the ONE owner of the ref grammar.
+ *
+ * `art_` + 22 crypto-random base62 chars = 26 chars the model can speak
+ * cheaply and copy reliably. The grammar lives in exactly one module (the
+ * `branchSegment.ts` precedent upstream): mint here, recognize here, and
+ * nowhere else — an adapter that parses refs with its own regex is a design
+ * smell this header exists to refuse.
+ *
+ * NEVER content-addressed. The digest is metadata on {@link ArtifactMeta};
+ * making content the key would collide two tenants' identical bytes into one
+ * object (an isolation bug wearing a dedup win) and could never name two
+ * generations of "the current dataset". Randomness comes from
+ * `globalThis.crypto` — present in every supported Node and every browser —
+ * so minting works wherever the in-memory adapter does.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isArtifactRef = exports.mintArtifactRef = exports.ARTIFACT_REF_PREFIX = void 0;
+/** The prefix every minted ref carries. */
+exports.ARTIFACT_REF_PREFIX = 'art_';
+/** Random chars after the prefix. 62^22 ≈ 2^131 — collision is not a case. */
+const RANDOM_LENGTH = 22;
+const ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+/** The full shape, anchored: `art_` + exactly 22 base62 chars. */
+const REF_PATTERN = /^art_[A-Za-z0-9]{22}$/;
+/**
+ * Mint a fresh, opaque, never-content-derived ref.
+ *
+ * Rejection sampling keeps the distribution uniform (256 % 62 ≠ 0, so a bare
+ * modulo would bias the low end of the alphabet — cosmetically fine,
+ * cryptographically sloppy, and cheap to do right).
+ */
+function mintArtifactRef() {
+    const out = [];
+    const bytes = new Uint8Array(RANDOM_LENGTH * 2);
+    while (out.length < RANDOM_LENGTH) {
+        globalThis.crypto.getRandomValues(bytes);
+        for (const b of bytes) {
+            // 248 = 4 * 62: the largest multiple of 62 below 256. Values at or
+            // above it are re-drawn instead of folded onto the alphabet unevenly.
+            if (b >= 248)
+                continue;
+            out.push(ALPHABET[b % ALPHABET.length]);
+            if (out.length === RANDOM_LENGTH)
+                break;
+        }
+    }
+    return `${exports.ARTIFACT_REF_PREFIX}${out.join('')}`;
+}
+exports.mintArtifactRef = mintArtifactRef;
+/**
+ * Is this string a well-formed artifact ref?
+ *
+ * Structural, total, and the ONLY recognizer. Adapters call it before any
+ * ref touches a filesystem path or a SQL parameter: refs are minted so a
+ * traversal payload cannot arrive by construction — and this asserts it
+ * anyway, because "cannot happen" is a claim, not a defence.
+ */
+function isArtifactRef(candidate) {
+    return typeof candidate === 'string' && REF_PATTERN.test(candidate);
+}
+exports.isArtifactRef = isArtifactRef;
+//# sourceMappingURL=naming.js.map

package/dist/artifacts/naming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"naming.js","sourceRoot":"","sources":["../../src/artifacts/naming.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;GAeG;;;AAIH,2CAA2C;AAC9B,QAAA,mBAAmB,GAAG,MAAM,CAAC;AAE1C,8EAA8E;AAC9E,MAAM,aAAa,GAAG,EAAE,CAAC;AAEzB,MAAM,QAAQ,GAAG,gEAAgE,CAAC;AAElF,kEAAkE;AAClE,MAAM,WAAW,GAAG,uBAAuB,CAAC;AAE5C;;;;;;GAMG;AACH,SAAgB,eAAe;IAC7B,MAAM,GAAG,GAAa,EAAE,CAAC;IACzB,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,aAAa,GAAG,CAAC,CAAC,CAAC;IAChD,OAAO,GAAG,CAAC,MAAM,GAAG,aAAa,EAAE,CAAC;QAClC,UAAU,CAAC,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;QACzC,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YACtB,mEAAmE;YACnE,sEAAsE;YACtE,IAAI,CAAC,IAAI,GAAG;gBAAE,SAAS;YACvB,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC;YACxC,IAAI,GAAG,CAAC,MAAM,KAAK,aAAa;gBAAE,MAAM;QAC1C,CAAC;IACH,CAAC;IACD,OAAO,GAAG,2BAAmB,GAAG,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;AACjD,CAAC;AAdD,0CAcC;AAED;;;;;;;GAOG;AACH,SAAgB,aAAa,CAAC,SAAkB;IAC9C,OAAO,OAAO,SAAS,KAAK,QAAQ,IAAI,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AACtE,CAAC;AAFD,sCAEC"}

package/dist/artifacts/payload.js

@@ -0,0 +1,113 @@
+"use strict";
+/**
+ * artifacts/payload — one owner for how a payload is measured, carried and
+ * digested.
+ *
+ * Three adapters store the same three payload shapes (string, `Uint8Array`,
+ * JSON value). If each measured or serialized on its own, `bytes` on the meta
+ * could disagree with what a digest was computed over, and a digest written by
+ * one adapter would not verify in another. So the laws live once, here:
+ *
+ *   • `measure` — `bytes` is the UTF-8 length of text/JSON, the byteLength of
+ *     binary. The number a consumer decides from, computed one way.
+ *   • `encode/decode` — the durable adapters persist ONE envelope
+ *     (`text` / `binary` base64 / `json`), so a file written by
+ *     `fileArtifacts` is legible to a debugging human and identical in law to
+ *     a row written by `sqliteArtifacts`.
+ *   • `digest` — sha-256 over the SAME canonical bytes `measure` counts, via
+ *     `globalThis.crypto.subtle` (browser + Node, zero dependencies).
+ *
+ * A payload JSON cannot carry (a function, a bigint, `undefined`, a cyclic
+ * object) is refused BY NAME at put — storing an approximation and returning
+ * it later as the real thing is the exact accepted-and-silently-wrong failure
+ * a claim check exists to prevent.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.decodeArtifactData = exports.encodeArtifactData = exports.computeArtifactDigest = exports.measureArtifactBytes = exports.canonicalPayloadBytes = void 0;
+const types_js_1 = require("./types.js");
+const textEncoder = new TextEncoder();
+const textDecoder = new TextDecoder();
+/**
+ * The canonical bytes of a payload — what `bytes` counts and what a digest
+ * is computed over. Throws {@link InvalidArtifactError} for a value that
+ * cannot be carried faithfully.
+ */
+function canonicalPayloadBytes(data) {
+    if (data instanceof Uint8Array)
+        return data;
+    if (typeof data === 'string')
+        return textEncoder.encode(data);
+    let serialized;
+    try {
+        serialized = JSON.stringify(data);
+    }
+    catch (err) {
+        throw new types_js_1.InvalidArtifactError(`the payload cannot be JSON-serialized (${err instanceof Error ? err.message : String(err)}). ` +
+            `Store a string, a Uint8Array, or a JSON-serializable value — an approximation of ` +
+            `anything else would be returned later as if it were the real thing.`);
+    }
+    if (serialized === undefined) {
+        throw new types_js_1.InvalidArtifactError(`the payload serializes to nothing (undefined, a function, or a symbol). ` +
+            `JSON cannot carry it, so the store will not pretend to. Store a string, a ` +
+            `Uint8Array, or a JSON-serializable value.`);
+    }
+    return textEncoder.encode(serialized);
+}
+exports.canonicalPayloadBytes = canonicalPayloadBytes;
+/** Payload size in bytes — UTF-8 for text/JSON, byteLength for binary. */
+function measureArtifactBytes(data) {
+    return canonicalPayloadBytes(data).byteLength;
+}
+exports.measureArtifactBytes = measureArtifactBytes;
+/** `sha-256:<hex>` over the canonical bytes. */
+async function computeArtifactDigest(data) {
+    const bytes = canonicalPayloadBytes(data);
+    // `subtle.digest` wants an ArrayBuffer-backed view; copy defensively so a
+    // Uint8Array over a SharedArrayBuffer cannot reach it.
+    const buffer = new Uint8Array(bytes).buffer;
+    const hash = new Uint8Array(await globalThis.crypto.subtle.digest('SHA-256', buffer));
+    let hex = '';
+    for (const b of hash)
+        hex += b.toString(16).padStart(2, '0');
+    return `sha-256:${hex}`;
+}
+exports.computeArtifactDigest = computeArtifactDigest;
+/** Encode for durable storage. Validates exactly as `measure` does. */
+function encodeArtifactData(data) {
+    if (data instanceof Uint8Array)
+        return { shape: 'binary', value: toBase64(data) };
+    if (typeof data === 'string')
+        return { shape: 'text', value: data };
+    // canonicalPayloadBytes carries the refusal for unserializable values.
+    return { shape: 'json', value: textDecoder.decode(canonicalPayloadBytes(data)) };
+}
+exports.encodeArtifactData = encodeArtifactData;
+/** Decode what {@link encodeArtifactData} wrote. Total over its own output. */
+function decodeArtifactData(encoded) {
+    switch (encoded.shape) {
+        case 'text':
+            return encoded.value;
+        case 'binary':
+            return fromBase64(encoded.value);
+        case 'json':
+            return JSON.parse(encoded.value);
+    }
+}
+exports.decodeArtifactData = decodeArtifactData;
+// Buffer-free base64, so the in-file law works in a browser bundle too.
+function toBase64(bytes) {
+    let binary = '';
+    const CHUNK = 0x8000;
+    for (let i = 0; i < bytes.length; i += CHUNK) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + CHUNK));
+    }
+    return btoa(binary);
+}
+function fromBase64(value) {
+    const binary = atob(value);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++)
+        bytes[i] = binary.charCodeAt(i);
+    return bytes;
+}
+//# sourceMappingURL=payload.js.map

package/dist/artifacts/payload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload.js","sourceRoot":"","sources":["../../src/artifacts/payload.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;;;AAEH,yCAAkD;AAElD,MAAM,WAAW,GAAG,IAAI,WAAW,EAAE,CAAC;AACtC,MAAM,WAAW,GAAG,IAAI,WAAW,EAAE,CAAC;AAEtC;;;;GAIG;AACH,SAAgB,qBAAqB,CAAC,IAAa;IACjD,IAAI,IAAI,YAAY,UAAU;QAAE,OAAO,IAAI,CAAC;IAC5C,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,WAAW,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;IAC9D,IAAI,UAAkB,CAAC;IACvB,IAAI,CAAC;QACH,UAAU,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;IACpC,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,MAAM,IAAI,+BAAoB,CAC5B,0CACE,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CACjD,KAAK;YACH,mFAAmF;YACnF,qEAAqE,CACxE,CAAC;IACJ,CAAC;IACD,IAAI,UAAU,KAAK,SAAS,EAAE,CAAC;QAC7B,MAAM,IAAI,+BAAoB,CAC5B,0EAA0E;YACxE,4EAA4E;YAC5E,2CAA2C,CAC9C,CAAC;IACJ,CAAC;IACD,OAAO,WAAW,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;AACxC,CAAC;AAvBD,sDAuBC;AAED,0EAA0E;AAC1E,SAAgB,oBAAoB,CAAC,IAAa;IAChD,OAAO,qBAAqB,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC;AAChD,CAAC;AAFD,oDAEC;AAED,gDAAgD;AACzC,KAAK,UAAU,qBAAqB,CAAC,IAAa;IACvD,MAAM,KAAK,GAAG,qBAAqB,CAAC,IAAI,CAAC,CAAC;IAC1C,0EAA0E;IAC1E,uDAAuD;IACvD,MAAM,MAAM,GAAG,IAAI,UAAU,CAAC,KAAK,CAAC,CAAC,MAAM,CAAC;IAC5C,MAAM,IAAI,GAAG,IAAI,UAAU,CAAC,MAAM,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC;IACtF,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,MAAM,CAAC,IAAI,IAAI;QAAE,GAAG,IAAI,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC7D,OAAO,WAAW,GAAG,EAAE,CAAC;AAC1B,CAAC;AATD,sDASC;AAWD,uEAAuE;AACvE,SAAgB,kBAAkB,CAAC,IAAa;IAC9C,IAAI,IAAI,YAAY,UAAU;QAAE,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;IAClF,IAAI,OAAO,IAAI,KAAK,QAAQ;QAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IACpE,uEAAuE;IACvE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,CAAC,MAAM,CAAC,qBAAqB,CAAC,IAAI,CAAC,CAAC,EAAE,CAAC;AACnF,CAAC;AALD,gDAKC;AAED,+EAA+E;AAC/E,SAAgB,kBAAkB,CAAC,OAAuB;IACxD,QAAQ,OAAO,CAAC,KAAK,EAAE,CAAC;QACtB,KAAK,MAAM;YACT,OAAO,OAAO,CAAC,KAAK,CAAC;QACvB,KAAK,QAAQ;YACX,OAAO,UAAU,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACnC,KAAK,MAAM;YACT,OAAO,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,KAAK,CAAY,CAAC;IAChD,CAAC;AACH,CAAC;AATD,gDASC;AAED,wEAAwE;AACxE,SAAS,QAAQ,CAAC,KAAiB;IACjC,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,MAAM,KAAK,GAAG,MAAM,CAAC;IACrB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC;QAC7C,MAAM,IAAI,MAAM,CAAC,YAAY,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC;IACjE,CAAC;IACD,OAAO,IAAI,CAAC,MAAM,CAAC,CAAC;AACtB,CAAC;AAED,SAAS,UAAU,CAAC,KAAa;IAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC;IAC3B,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE;QAAE,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IACxE,OAAO,KAAK,CAAC;AACf,CAAC"}

package/dist/artifacts/placement.js

@@ -0,0 +1,86 @@
+"use strict";
+/**
+ * artifacts/placement — the placement threshold (Phase 2, Leg 3).
+ *
+ * An OPTIONAL operator dial on the agent's artifacts wiring:
+ * `Agent.create({ artifacts: { store, placement: { maxInlineChars: N } } })`.
+ * A tool result whose finalized text exceeds the threshold is checked into
+ * the store (kind `tool-result/<toolName>`) and the model receives the claim
+ * ticket instead — a SHORT substitute naming ref + meta + how to consume it.
+ * The whole 879,073-token failure class, retired by configuration.
+ *
+ * PRECEDENCE with the other two ceilings, stated once and owned here:
+ *   1. the tool's own `resultCeiling` (the AUTHOR's refusal) is judged FIRST,
+ *      at the execute boundary — a refused result is a short teaching
+ *      sentence, so placement never sees the payload at all;
+ *   2. placement (the OPERATOR's ref-ing) is judged next, on what the
+ *      after-tool governance chain let through — a rule that already
+ *      summarized a huge result is measured on what it produced;
+ *   3. the agent-level `maxToolResultChars` truncation net runs LAST — with
+ *      placement on it measures the ticket, so it should now rarely fire.
+ *
+ * A placed result is a TICKET, not a refusal: declared effects are still
+ * judged and procedure steps advance normally — the result ARRIVED; it just
+ * travels by reference. The decision is never silent: the mint lands as
+ * `agentfootprint.artifacts.minted` (origin joining it to the tool call) and
+ * the substitution states itself in the result the model reads.
+ *
+ * This module is the PURE half — the dial shape, its build-time refusals,
+ * the measure rule (shared with both ceilings: strings as-is, everything
+ * else `safeStringify`d by the caller), and the substitute composer. The
+ * dispatch layer owns the mint and the events.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.placedToolResult = exports.isPlacedToolResult = exports.placedResultKind = exports.assertArtifactPlacement = void 0;
+/**
+ * Refuse a placement dial this library cannot honor, where it is configured
+ * — never at the first oversized result of the first run.
+ */
+function assertArtifactPlacement(site, placement) {
+    if (placement === undefined)
+        return;
+    const value = placement.maxInlineChars;
+    if (!Number.isFinite(value) || !Number.isInteger(value) || value <= 0) {
+        throw new Error(`${site}: artifacts.placement.maxInlineChars must be a positive whole number of ` +
+            `characters, and ${String(value)} is not one. It is the threshold over which a tool ` +
+            `result is checked into the artifact store and the model reads the claim ticket ` +
+            `instead. To turn placement OFF, omit \`placement\` — absent means results are never ` +
+            `measured and never placed, exactly as before.`);
+    }
+}
+exports.assertArtifactPlacement = assertArtifactPlacement;
+/** The kind vocabulary a placement mint declares: `tool-result/<toolName>`.
+ *  Honest — it says exactly what the payload is and which tool produced it —
+ *  and it is what a `wants` declaration or a `present` call names to consume
+ *  the placed result. */
+function placedResultKind(toolName) {
+    return `tool-result/${toolName}`;
+}
+exports.placedResultKind = placedResultKind;
+/** Type guard for consumers reading `tool_end.result` or a tool message. */
+function isPlacedToolResult(value) {
+    return (typeof value === 'object' &&
+        value !== null &&
+        value.placed === true &&
+        typeof value.ref === 'string' &&
+        typeof value.reason === 'string');
+}
+exports.isPlacedToolResult = isPlacedToolResult;
+/** Compose the ticket from the mint the dispatch layer performed. */
+function placedToolResult(toolName, meta, sizeChars, maxInlineChars) {
+    return {
+        placed: true,
+        ref: meta.ref,
+        kind: meta.kind,
+        mediaType: meta.mediaType,
+        bytes: meta.bytes,
+        reason: `${toolName} returned ${sizeChars} chars, over the ${maxInlineChars}-char placement ` +
+            `threshold, so the full result was stored as artifact '${meta.ref}' ` +
+            `(${meta.kind}) instead of entering this conversation. Route the ref: pass the ` +
+            `string '${meta.ref}' to a tool whose argument wants '${meta.kind}', or call ` +
+            `present({ ref: '${meta.ref}', as: … }) to hand it to the screen. Do not retype or ` +
+            `summarize content you have not read.`,
+    };
+}
+exports.placedToolResult = placedToolResult;
+//# sourceMappingURL=placement.js.map

package/dist/artifacts/placement.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"placement.js","sourceRoot":"","sources":["../../src/artifacts/placement.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;;;AAeH;;;GAGG;AACH,SAAgB,uBAAuB,CACrC,IAAY,EACZ,SAAwC;IAExC,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO;IACpC,MAAM,KAAK,GAAG,SAAS,CAAC,cAAc,CAAC;IACvC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,KAAK,IAAI,CAAC,EAAE,CAAC;QACtE,MAAM,IAAI,KAAK,CACb,GAAG,IAAI,0EAA0E;YAC/E,mBAAmB,MAAM,CAAC,KAAK,CAAC,qDAAqD;YACrF,iFAAiF;YACjF,sFAAsF;YACtF,+CAA+C,CAClD,CAAC;IACJ,CAAC;AACH,CAAC;AAfD,0DAeC;AAED;;;yBAGyB;AACzB,SAAgB,gBAAgB,CAAC,QAAgB;IAC/C,OAAO,eAAe,QAAQ,EAAE,CAAC;AACnC,CAAC;AAFD,4CAEC;AAqBD,4EAA4E;AAC5E,SAAgB,kBAAkB,CAAC,KAAc;IAC/C,OAAO,CACL,OAAO,KAAK,KAAK,QAAQ;QACzB,KAAK,KAAK,IAAI;QACb,KAA8B,CAAC,MAAM,KAAK,IAAI;QAC/C,OAAQ,KAA2B,CAAC,GAAG,KAAK,QAAQ;QACpD,OAAQ,KAA8B,CAAC,MAAM,KAAK,QAAQ,CAC3D,CAAC;AACJ,CAAC;AARD,gDAQC;AAED,qEAAqE;AACrE,SAAgB,gBAAgB,CAC9B,QAAgB,EAChB,IAAkB,EAClB,SAAiB,EACjB,cAAsB;IAEtB,OAAO;QACL,MAAM,EAAE,IAAI;QACZ,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,SAAS,EAAE,IAAI,CAAC,SAAS;QACzB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,MAAM,EACJ,GAAG,QAAQ,aAAa,SAAS,oBAAoB,cAAc,kBAAkB;YACrF,yDAAyD,IAAI,CAAC,GAAG,IAAI;YACrE,IAAI,IAAI,CAAC,IAAI,mEAAmE;YAChF,WAAW,IAAI,CAAC,GAAG,qCAAqC,IAAI,CAAC,IAAI,aAAa;YAC9E,mBAAmB,IAAI,CAAC,GAAG,yDAAyD;YACpF,sCAAsC;KACzC,CAAC;AACJ,CAAC;AApBD,4CAoBC"}

package/dist/artifacts/present.js

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * artifacts/present — the hand-to-the-screen verb (Phase 2, Leg 2).
+ *
+ * `present({ ref, as, label? })` is how the model finishes an analytics
+ * answer WITHOUT serializing what the screen will show: it names the ticket
+ * (`ref`), the consumer vocabulary for how to render it (`as: 'bar-chart'`,
+ * `'table'`, …), and optionally the human title. The framework `head`s the
+ * ref under the run's own scope and the RESULT carries a DESCRIPTION
+ * SNAPSHOT — `{ kind, mediaType, bytes, label }` — so the claim ticket
+ * describes the parcel: a conversation reloaded after the artifact expired
+ * can still render an honest placeholder from history alone ("Chart —
+ * 'Q3 sales by region' (bar-chart, 41 KB) — expired; re-run to regenerate"),
+ * because the snapshot lives INSIDE the tool result, the one thing provider
+ * message history keeps typed and durable. Never a blank pane.
+ *
+ * `as` is deliberately NOT validated against a component registry — that
+ * registry is a later phase (the frontend leg); until then the value is
+ * stored as data and travels on the `artifacts.presented` event exactly as
+ * spoken.
+ *
+ * This module is the PURE half — the tool's name/schema constants, the
+ * snapshot shape, and the resolution over the five-verb port. The tool SHELL
+ * (a placeholder whose result the agent loop overwrites — the `skip_step`
+ * pattern) lives in core, which is also where the typed
+ * `agentfootprint.artifacts.presented` event is emitted. Core wires
+ * artifacts; never the reverse.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.presentArtifact = exports.PRESENT_TOOL_NAME = void 0;
+/**
+ * The reserved name of the auto-attached tool. Reserved ONLY when a store is
+ * attached (the `read_skill` seam): a storeless agent may keep its own
+ * `present`, because the framework attaches nothing there.
+ */
+exports.PRESENT_TOOL_NAME = 'present';
+/** How many live refs a miss refusal lists. A lesson, not a catalog. */
+const PRESENT_LIST_LIMIT = 10;
+/** `art_h7Kq… [chart/spec · 41210 bytes · 'Q3 sales']` — one listed ref. */
+function describeRef(meta) {
+    return `${meta.ref} [${meta.kind} · ${meta.bytes} bytes${meta.label !== undefined ? ` · '${meta.label}'` : ''}]`;
+}
+/**
+ * Resolve one `present` call over the port — ONE law for every dispatch
+ * door. `head`, never `get`: presenting is the render-by-ref decision, and
+ * the screen pays for the bytes later, under its own identity.
+ */
+async function presentArtifact(store, scope, args) {
+    const ref = args.ref;
+    const as = args.as;
+    if (typeof ref !== 'string' || ref.trim().length === 0) {
+        return {
+            ok: false,
+            refusal: `present needs \`ref\` — the art_… ticket of the artifact to hand to the screen. ` +
+                `Store the data first (a tool that mints, or the placement threshold), then present ` +
+                `its ref.`,
+        };
+    }
+    if (typeof as !== 'string' || as.trim().length === 0) {
+        return {
+            ok: false,
+            refusal: `present needs \`as\` — the consumer vocabulary for how the screen should render ` +
+                `'${ref}' (e.g. 'bar-chart', 'table', 'image'). Say what it is; the screen picks ` +
+                `the renderer.`,
+        };
+    }
+    const meta = await store.head(scope, ref);
+    if (meta === null) {
+        const page = await store.list(scope, { limit: PRESENT_LIST_LIMIT });
+        const listing = page.artifacts.length === 0
+            ? `Nothing is live in this run's scope right now — store the data first, then present ` +
+                `its ref.`
+            : `Live refs in scope: ${page.artifacts.map(describeRef).join(', ')}.`;
+        return {
+            ok: false,
+            missedRef: ref,
+            refusal: `present('${ref}') found nothing under that ref in this run's scope — expired, ` +
+                `swept, or never stored here. Nothing was presented. ${listing}`,
+        };
+    }
+    const label = typeof args.label === 'string' && args.label.trim().length > 0 ? args.label : meta.label;
+    return {
+        ok: true,
+        result: {
+            presented: true,
+            ref: meta.ref,
+            as,
+            snapshot: {
+                kind: meta.kind,
+                mediaType: meta.mediaType,
+                bytes: meta.bytes,
+                ...(label !== undefined && { label }),
+            },
+        },
+    };
+}
+exports.presentArtifact = presentArtifact;
+//# sourceMappingURL=present.js.map

package/dist/artifacts/present.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"present.js","sourceRoot":"","sources":["../../src/artifacts/present.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;;;AAIH;;;;GAIG;AACU,QAAA,iBAAiB,GAAG,SAAS,CAAC;AAyC3C,wEAAwE;AACxE,MAAM,kBAAkB,GAAG,EAAE,CAAC;AAE9B,4EAA4E;AAC5E,SAAS,WAAW,CAAC,IAAkB;IACrC,OAAO,GAAG,IAAI,CAAC,GAAG,KAAK,IAAI,CAAC,IAAI,MAAM,IAAI,CAAC,KAAK,SAC9C,IAAI,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,OAAO,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,EACpD,GAAG,CAAC;AACN,CAAC;AAED;;;;GAIG;AACI,KAAK,UAAU,eAAe,CACnC,KAAoB,EACpB,KAAoB,EACpB,IAAuC;IAEvC,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,CAAC;IACrB,MAAM,EAAE,GAAG,IAAI,CAAC,EAAE,CAAC;IACnB,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACvD,OAAO;YACL,EAAE,EAAE,KAAK;YACT,OAAO,EACL,kFAAkF;gBAClF,qFAAqF;gBACrF,UAAU;SACb,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,EAAE,KAAK,QAAQ,IAAI,EAAE,CAAC,IAAI,EAAE,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QACrD,OAAO;YACL,EAAE,EAAE,KAAK;YACT,OAAO,EACL,kFAAkF;gBAClF,IAAI,GAAG,2EAA2E;gBAClF,eAAe;SAClB,CAAC;IACJ,CAAC;IACD,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;IAC1C,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;QAClB,MAAM,IAAI,GAAG,MAAM,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,kBAAkB,EAAE,CAAC,CAAC;QACpE,MAAM,OAAO,GACX,IAAI,CAAC,SAAS,CAAC,MAAM,KAAK,CAAC;YACzB,CAAC,CAAC,qFAAqF;gBACrF,UAAU;YACZ,CAAC,CAAC,uBAAuB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;QAC3E,OAAO;YACL,EAAE,EAAE,KAAK;YACT,SAAS,EAAE,GAAG;YACd,OAAO,EACL,YAAY,GAAG,iEAAiE;gBAChF,uDAAuD,OAAO,EAAE;SACnE,CAAC;IACJ,CAAC;IACD,MAAM,KAAK,GACT,OAAO,IAAI,CAAC,KAAK,KAAK,QAAQ,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC;IAC3F,OAAO;QACL,EAAE,EAAE,IAAI;QACR,MAAM,EAAE;YACN,SAAS,EAAE,IAAI;YACf,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,EAAE;YACF,QAAQ,EAAE;gBACR,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,SAAS,EAAE,IAAI,CAAC,SAAS;gBACzB,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,GAAG,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,CAAC;aACtC;SACF;KACF,CAAC;AACJ,CAAC;AAzDD,0CAyDC"}

package/dist/artifacts/retention.js

@@ -0,0 +1,121 @@
+"use strict";
+/**
+ * artifacts/retention — the one owner of the eviction law.
+ *
+ * Three adapters, one rule for what leaves a scope and why. Each adapter
+ * supplies its rows; this module decides — a pure plan over plain facts, so
+ * the law is testable without a store and cannot fork into three dialects.
+ *
+ * The policy is three independent dials, all per scope:
+ *   • `ttlMs`           — every artifact gets `expiresAt = createdAt + ttl`
+ *                         stamped AT MINT (expiry is stated, never sprung),
+ *                         and expired rows are swept when the scope is next
+ *                         touched by a put.
+ *   • `maxBytesPerScope`— a byte budget; least-recently-ACCESSED leaves first
+ *                         (an artifact under active render must not be the
+ *                         next one evicted — the innerRunRecords recency law).
+ *   • `maxCountPerScope`— a row budget, same eviction order.
+ *
+ * Every eviction is a FACT the plan returns ({@link SweptArtifact}), because
+ * the put that triggered it reports them upward and the capability layer puts
+ * each one on the record. A store that made room silently would be lying by
+ * omission.
+ *
+ * A payload bigger than the whole byte budget is REFUSED at the door (the
+ * plan says so; the adapter throws by name) — evicting an entire scope to
+ * admit one oversized object would trade everything for something that may
+ * itself not fit.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveExpiresAt = exports.planRetention = exports.assertRetention = void 0;
+/**
+ * Validate a retention policy at construction — a dial that cannot bind
+ * (zero, negative, NaN) is refused where it was written, not discovered as
+ * an always-empty store at the first put.
+ */
+function assertRetention(adapter, retention) {
+    if (retention === undefined)
+        return;
+    const dials = [
+        ['ttlMs', retention.ttlMs],
+        ['maxBytesPerScope', retention.maxBytesPerScope],
+        ['maxCountPerScope', retention.maxCountPerScope],
+    ];
+    for (const [name, value] of dials) {
+        if (value === undefined)
+            continue;
+        if (!Number.isFinite(value) || value <= 0) {
+            throw new TypeError(`[artifacts] ${adapter}: retention.${name} = ${String(value)} cannot bind. ` +
+                `Each dial is a positive number, or absent — omitting it is how "no limit" is said.`);
+        }
+    }
+}
+exports.assertRetention = assertRetention;
+/**
+ * Plan what must leave a scope so that `incomingBytes` may enter.
+ *
+ * Pure: reads rows, returns facts, mutates nothing. Rows may arrive in any
+ * order; eviction order here is least-recently-accessed first.
+ */
+function planRetention(rows, incomingBytes, retention, now) {
+    const swept = [];
+    const sweep = (row, reason) => {
+        swept.push({ ref: row.ref, reason, kind: row.kind, bytes: row.bytes });
+    };
+    // 1 — the calendar: expired rows leave regardless of budgets.
+    const live = [];
+    for (const row of rows) {
+        if (row.expiresAt !== undefined && row.expiresAt <= now)
+            sweep(row, 'ttl');
+        else
+            live.push(row);
+    }
+    if (retention === undefined)
+        return { swept };
+    const { maxBytesPerScope, maxCountPerScope } = retention;
+    if (maxBytesPerScope !== undefined && incomingBytes > maxBytesPerScope) {
+        return {
+            swept,
+            refusal: `the payload is ${incomingBytes} bytes and this store's byte budget per scope is ` +
+                `${maxBytesPerScope}. Evicting everything else would not make it fit, so it is ` +
+                `refused instead of admitted by force. Store something smaller, or build the ` +
+                `store with a larger maxBytesPerScope.`,
+        };
+    }
+    // Least-recently-accessed first — ties broken by ref for determinism.
+    live.sort((a, b) => a.lastAccessedAt - b.lastAccessedAt || (a.ref < b.ref ? -1 : 1));
+    // 2 — the row budget (the incoming row occupies one slot).
+    if (maxCountPerScope !== undefined) {
+        let count = live.length + 1;
+        while (count > maxCountPerScope && live.length > 0) {
+            sweep(live.shift(), 'max-count');
+            count--;
+        }
+    }
+    // 3 — the byte budget (the incoming bytes already proved they can fit).
+    if (maxBytesPerScope !== undefined) {
+        let total = live.reduce((sum, row) => sum + row.bytes, 0) + incomingBytes;
+        while (total > maxBytesPerScope && live.length > 0) {
+            const evicted = live.shift();
+            sweep(evicted, 'max-bytes');
+            total -= evicted.bytes;
+        }
+    }
+    return { swept };
+}
+exports.planRetention = planRetention;
+/**
+ * The `expiresAt` a mint gets: the caller's own statement and the store's
+ * ttl, whichever comes SOONER. A store may tighten a promise, never extend
+ * one — extending would overrule the only party who knows the data.
+ */
+function resolveExpiresAt(callerExpiresAt, retention, now) {
+    const fromTtl = retention?.ttlMs !== undefined ? now + retention.ttlMs : undefined;
+    if (callerExpiresAt === undefined)
+        return fromTtl;
+    if (fromTtl === undefined)
+        return callerExpiresAt;
+    return Math.min(callerExpiresAt, fromTtl);
+}
+exports.resolveExpiresAt = resolveExpiresAt;
+//# sourceMappingURL=retention.js.map