agentfootprint 9.19.0 → 9.21.0

package/AGENTS.md

@@ -475,7 +475,7 @@ Resilience decorators live on the `agentfootprint/resilience` subpath
 (not the main barrel). Each preserves the `LLMProvider` interface and
 stacks freely.
 
-### Observability — 84 typed events across 20 domains
+### Observability — 89 typed events across 21 domains
 
 ```typescript
 agent.on('agentfootprint.context.injected', (e) =>

package/CLAUDE.md

@@ -60,7 +60,7 @@ Traps: `src/observability/` holds the finder IMPLEMENTATIONS (canonical home; `d
 - **Embedder fingerprint** (8.9.0) → `Embedder.id` (optional; every shipped embedder sets one, and NONE include dims — the store appends `@<dims>` itself, so an id carrying its own size double-stamps) + `indexDocuments` defaulting `embedderId` to it + `SqliteVectorStore.reconcileFingerprint` (the only comparison site). Rule: dimensions ALWAYS decide, model ids decide only when BOTH sides named themselves — refusing on an absent name would block the majority of callers who never pass `embedderId`.
 - **Retrieval record** (8.8.0) → FOUR stages write one object in sequence: `loadRelevant` (candidates+scores+threshold verdicts) → `pickByBudget` (re-marks admitted→over-budget/over-max-entries) → `formatDefault` (`promptFragment` + `promptPosition`) → the read mount's outputMapper lifts it to root as `retrievalEvidence_<id>`. `memoryRecallInjections` then splits ONE recall into one ActiveInjection PER CHUNK — guarded by a byte-equality check (`fragments.join('\n\n') === systemContent`) that falls back to the single injection rather than change the prompt. `rank` (score order) and `promptPosition` (picker order) are DIFFERENT and both load-bearing: joining fragments in rank order reproduces the right bytes in a sequence the model never saw.
 - **AgentState** → all 8 stages/ files, both builders' mappers, memory-wire STRING-TYPED keys ('runIdentity'/'turnNumber'/… buildAgentChart.ts:177-180 — not refactor-safe), finalizeResult's `reliabilityFail*`/`policyHalt*` reads (rename silently kills the typed errors).
-- **events/** → 84 typed events across 20 domains (counts anti-drift-tested against this file — update BOTH when adding events): ALL_EVENT_TYPES exhaustiveness tests, DomainWildcard hand-list, ~42 importers (recorders, strategies, stream, commentary).
+- **events/** → 89 typed events across 21 domains (counts anti-drift-tested against this file — update BOTH when adding events): ALL_EVENT_TYPES exhaustiveness tests, DomainWildcard hand-list, ~42 importers (recorders, strategies, stream, commentary).
 - **adapters/types.ts LLMMessage/LLMRequest** → 62 importers: tool_use round-trip (toolCalls.ts:115-135), wire assembly (callLLM.ts:150-160), providers, cache strategies, security/extractSequence, reliability loop.
 - **Cache** → strategy registration is a MODULE SIDE EFFECT (src/index.ts:15-17); an entry point skipping that import silently falls back to NoOp. Resolved once per Agent at construction (Agent.ts:347).
 - **Injection engine eval semantics** → Evaluate stage cursor keystone (buildInjectionEngineSubflow.ts:214-222), Route stage MIRRORS slot filters (keep in sync with buildSystemPromptSlot), read_skill gate (toolCalls.ts:747). The gate's allowed set is TWO kinds of id (8.4.0): a HOP (`deps.allowedSkillIds` = `graph.reachableSkills(cursor)` — activates AND moves the cursor) ∪ an OPEN skill (`deps.openSkillIds` = `Agent.openSkillIds()`, Agent.ts:1052 — a registered skill whose trigger is `llm-activated` AND that the graph declares no incoming edge to; activates, never moves the cursor). Both clauses are load-bearing: the trigger test is "read_skill can really activate this", the edge test keeps a bare model edge `.route(a,m)` from-gated. **8.5.0** extends the SAME trigger test three ways: a decision `tree()` returns `[]` from `reachableSkills` (leaves compile to `rule` triggers, so a pick could only be accepted then dropped — the gate refuses with a tree-specific message, `deps.skillGraphIsTree`, derived in AgentBuilder from `graph.nodes.some(kind==='predicate')`); `surfaceMode:'tool-only'` is refused at agent build for any skill whose trigger is not `llm-activated` (skillBodyDelivery.ts — the read_skill tool result is the only channel that mode has, and the graph never calls read_skill); and `read_skill`'s DESCRIPTION is rebuilt per iteration from `reachableSkills(cursor) ∪ open` (Agent.readSkillOfferFor → buildToolsSlot's `readSkillFor`). **The read_skill ENUM must stay the full catalog** — `toolArgValidation` defaults to `'enforce'` and runs at toolCalls.ts:570, BEFORE the gate at :765, and sets `error = true` which the gate skips; narrowing the enum silently retires the teaching refusal, `skill.rejected`, routeRecorder's rejection hops and the rejected-cap governor.
@@ -75,6 +75,8 @@ Traps: `src/observability/` holds the finder IMPLEMENTATIONS (canonical home; `d
 - **Permission capability vocabulary** (9.11.0) → `PermissionCapability` = `ToolCapability | 'tool_call' | 'skill_read'`, defined ONCE in adapters/types.ts and imported by events/payloads.ts (`PermissionCheckPayload.capability`) — the two used to be independent copies of the same union. The law is **enforce-when-both-sides-speak**: `Tool.capabilities` (declared, NEVER inferred) × `PermissionChecker.governs` (optional, feature-detected, ABSENCE = NO, `checkerGoverns()` is the one reader). `PermissionPolicy` DERIVES `governs` from its rules bag so "unconfigured" and "never asked" cannot drift. FOUR request sites now: toolCalls' 3 `tool_call` checks + `askCapability` (declared caps + `skill_read`). Memory-pipeline stages still build NO PermissionRequest — say so rather than imply it.
 - **Skill visibility** (9.11.0) → the async half rides the tools slot's Discover stage (the ONE awaitable stage there) into a closure-shared `hiddenSkillIds`, read by the sync Compose stage — the `providerToolCache` pattern exactly. `readSkillFor` now takes `{currentSkillId?, hiddenSkillIds?}`; `ReadSkillOffer.grantable` became OPTIONAL (no graph ⇒ plain filtered catalog) and `hiddenIds` removes rows from BOTH sections. The ENUM stays the full catalog (8.5.0's law — narrowing it turns a policy refusal into a generic schema error that `toolArgValidation` raises before any gate). `skill:<id>` targets have ONE owner: `security/skillTarget.ts`.
 - **Tool-result cap** (9.11.0) → `core/agent/toolResultCap.ts` + `ToolCallsHandlerDeps.maxToolResultChars` + the `capResults` closure applied at all FIVE `tool_end`-emitting dispatch paths in toolCalls.ts (execute, ask-resume, check-in decision, credential-consent resume, pauseHere answer). Both channels are measured separately — `result` (the event) and `modelResult` (history) — because a middleware may have already shrunk one. A new dispatch path MUST call `capResults` or it silently escapes the ceiling.
+- **Refusing result ceiling** (9.20.0) → the PER-TOOL sibling of the cap with the OPPOSITE overflow answer: `Tool.resultCeiling {maxChars, narrowBy?}` (type + `assertResultCeiling` in core/tools.ts; measurement + refusal sentence in `core/agent/resultCeiling.ts`) REFUSES — "No data was returned" + how to narrow — never truncates (truncation reads as complete data ⇒ fabrication). Applied by the `refuseOverCeiling` closure at BOTH execute boundaries (batch loop + `resolveCredentialAndExecute`, covering all four resume paths; the pauseHere answer is a HUMAN's value, deliberately not measured), at the moment the handler's return lands — BEFORE gates/after-tool chain (read_skill-gate precedent). The payload enters NO channel; the record keeps `tools.result_refused {sizeChars, maxChars, narrowBy?, declaredStatus?}`; delivered status = `'invalid'` (routes via `onToolStatus`); an envelope's DECLARED effects are still judged (the effects channel didn't overflow) but its status is overridden; `ceilingRefused` blocks step-pointer advance on every path. Zero-cost: no `resultCeiling` ⇒ one undefined check, byte-identical.
+- **Conjunction matcher** (9.20.0) → `SkillMatch` gains `{all: [...]}` (AND of the SYNC arms only), all inside skillMatch.ts: `compileAllArm` (ONE compilation → AND predicate + flat `{kind:'all', parts}` data; intent member = teaching refusal naming the separate-rule alternative; nested `all` FLATTENED — associativity, the drop-stateful-flags normalize-to-truth precedent; empty refused), `compareWithAll` (shadows-ONLY via `partCoversProvably` part coverage — identical regex / keyword superset; plain-earlier-covers-a-part shadows a later all; NO overlap claims — a conjunction can be unsatisfiable and the specific-first layout is a design), `rawCaption` recursion (parts joined ` AND `, escaped once). Checkup/provenance/toMermaid see through it with zero changes of their own (parts are guaranteed leaves).
 
 ## End-to-end trace (agent.run; 1 tool call then final answer; default reactMode 'dynamic')
 build (once): Agent.create → AgentBuilder.build → Agent ctor → initChart(buildChart) (Agent.ts:429; RunnerBase throws on re-init :256) → buildAgentChart assembles: seed → sf-injection-engine → Context selector (`failFast: true`, selects the 3 slot subflows in parallel) → sf-cache → call-llm → route decider → branches tool-calls (pausable, `{loopTo}`) / [output-retry (7.26, conditional mount, SAME `{loopTo}`)] / final (PrepareFinal → memory writes → BreakFinal `$break`, `propagateBreak: true`).

package/ai-instructions/claude-code/SKILL.md

@@ -379,7 +379,7 @@ if (isPaused(result)) {
 }
 ```
 
-## Observability — 84 typed events × 20 domains
+## Observability — 89 typed events × 21 domains
 
 ```typescript
 agent.on('agentfootprint.context.injected', (e) =>

package/dist/artifacts/capability.js

@@ -0,0 +1,131 @@
+"use strict";
+/**
+ * artifacts/capability — `ctx.artifacts`, the scope-bound door a tool gets.
+ *
+ * Shaped exactly like `ctx.credentials`:
+ *   • ALWAYS present — with no store attached every method is a teaching
+ *     refusal naming how to attach one, so a tool can never silently
+ *     optional-chain past a store that is not there;
+ *   • fail-closed — the refusal throws; `ctx.hasArtifacts` is the fact to
+ *     branch on for an intentional degraded mode;
+ *   • scope composed by the FRAMEWORK from the run's identity/session — the
+ *     capability closes over it, so a tool cannot name, widen or replace the
+ *     scope it resolves under. The five verbs here take no scope argument on
+ *     purpose: that argument was already answered by whoever built the
+ *     context.
+ *
+ * Every hop lands on the record AS IT HAPPENS: this module reports facts to a
+ * neutral sink (a plain callback), and the tool-dispatch layer adapts that
+ * sink onto the typed event channel. Neutral so this folder never imports the
+ * event system or the agent — core wires artifacts, never the reverse.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.unconfiguredArtifacts = exports.bindArtifacts = void 0;
+const types_js_1 = require("./types.js");
+/**
+ * Bind a store to one run's scope — the framework's move, made where the
+ * scope is known and a tool cannot reach.
+ */
+function bindArtifacts(store, scope, options = {}) {
+    const { origin, onEvent } = options;
+    const report = (fact) => {
+        onEvent?.(fact);
+    };
+    return {
+        async put(input) {
+            try {
+                // `origin` is the framework's field: whatever a caller managed to put
+                // there is discarded in favor of the run's own facts.
+                const result = await store.put(scope, {
+                    ...input,
+                    ...(origin !== undefined ? { origin } : {}),
+                });
+                for (const swept of result.swept)
+                    report({ type: 'expired', swept });
+                report({ type: 'minted', meta: result.meta });
+                return result.meta;
+            }
+            catch (err) {
+                if (err instanceof types_js_1.UnknownParentRefError) {
+                    report({ type: 'refused', op: 'put', reason: 'unknown-parent', detail: err.message });
+                }
+                else if (err instanceof types_js_1.InvalidArtifactError) {
+                    report({ type: 'refused', op: 'put', reason: 'invalid-input', detail: err.message });
+                }
+                throw err;
+            }
+        },
+        async head(ref) {
+            const meta = await store.head(scope, ref);
+            if (meta === null) {
+                report({ type: 'refused', op: 'head', reason: 'missing-or-expired', ref });
+                return null;
+            }
+            report({ type: 'resolved', ref: meta.ref, via: 'head', kind: meta.kind, bytes: meta.bytes });
+            return meta;
+        },
+        async get(ref) {
+            let record;
+            try {
+                record = await store.get(scope, ref);
+            }
+            catch (err) {
+                if (err instanceof types_js_1.ArtifactIntegrityError) {
+                    report({
+                        type: 'refused',
+                        op: 'get',
+                        reason: 'digest-mismatch',
+                        ref,
+                        detail: err.message,
+                    });
+                }
+                throw err;
+            }
+            if (record === null) {
+                report({ type: 'refused', op: 'get', reason: 'missing-or-expired', ref });
+                return null;
+            }
+            report({
+                type: 'resolved',
+                ref: record.meta.ref,
+                via: 'get',
+                kind: record.meta.kind,
+                bytes: record.meta.bytes,
+            });
+            return record;
+        },
+        delete(ref) {
+            return store.delete(scope, ref);
+        },
+        list(options) {
+            return store.list(scope, options);
+        },
+    };
+}
+exports.bindArtifacts = bindArtifacts;
+/**
+ * The fail-closed capability used when NO store is attached. Every verb
+ * throws the same teaching refusal — loud, named, and on the record — so
+ * `ctx.artifacts` is never `undefined` and a missing store can never read as
+ * an empty one. Branch on `ctx.hasArtifacts` for an intentional no-store
+ * mode. (The `unconfiguredCredentialProvider` law, verb for verb.)
+ */
+function unconfiguredArtifacts(onEvent) {
+    const refuse = (op, ref) => {
+        onEvent?.({ type: 'refused', op, reason: 'no-store', ...(ref !== undefined && { ref }) });
+        return Promise.reject(new Error(`No artifact store is attached, but this tool called ctx.artifacts.${op}(...). ` +
+            `Pass \`artifacts\` to Agent.create({ ..., artifacts }) — inMemoryArtifacts() for ` +
+            `an in-process store, fileArtifacts({ directory }) or sqliteArtifacts({ file }) for ` +
+            `one that survives a restart. A tool that intentionally supports running without a ` +
+            `store should branch on \`ctx.hasArtifacts\` instead of catching this.`));
+    };
+    return {
+        put: () => refuse('put'),
+        head: (ref) => refuse('head', ref),
+        get: (ref) => refuse('get', ref),
+        delete: (ref) => refuse('delete', ref),
+        list: () => refuse('list'),
+    };
+}
+exports.unconfiguredArtifacts = unconfiguredArtifacts;
+//# sourceMappingURL=capability.js.map

package/dist/artifacts/capability.js.map

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

package/dist/artifacts/fileArtifacts.js

@@ -0,0 +1,230 @@
+"use strict";
+/**
+ * artifacts/fileArtifacts — the claim-check store in a directory.
+ *
+ * One machine, one directory, nothing to install: each artifact is one JSON
+ * envelope at `<dir>/<tenant>/<principal>/<conversation>/<ref>.json`, so an
+ * incident can be inspected with `ls` and `cat` — a store you cannot read
+ * with the tools already on the box is a store you debug by guessing.
+ *
+ * ── Scope-partitioned paths, structurally traversal-proof ──────────────────
+ * The path is built from two kinds of segment and both are closed:
+ *   • the ref — MINTED (`art_` + base62), and `isArtifactRef` is asserted
+ *     before any ref touches a path anyway, because "cannot happen" is a
+ *     claim, not a defence;
+ *   • the scope tuple — caller strings, so each segment is percent-encoded
+ *     before it becomes a directory name: `..`, `/` and `\` arrive as data
+ *     and land as literals, never as navigation.
+ *
+ * ── What this adapter does NOT know ────────────────────────────────────────
+ * A directory cannot cheaply know which artifact was READ last, so budget
+ * evictions here are oldest-first (by mint time) rather than the in-memory
+ * adapter's least-recently-used — stated here so nobody discovers it as a
+ * surprise under pressure. TTL expiry behaves identically everywhere.
+ *
+ * Node-only (`node:fs` via lazy require, the sqliteSessions law) — importing
+ * the barrel costs a browser bundle nothing; constructing one where there is
+ * no filesystem refuses by name.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fileArtifacts = exports.UnreadableArtifactFileError = void 0;
+const lazyRequire_js_1 = require("../lib/lazyRequire.js");
+const minting_js_1 = require("./minting.js");
+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");
+/** What one artifact file holds. `format` is bumped only for a change an
+ *  older reader could not survive; a newer number is refused, never half-read. */
+const FILE_FORMAT = 1;
+/**
+ * Raised when an artifact file EXISTS but this runtime cannot read it — a
+ * different fact from "no artifact", and only one of them is safe to answer
+ * with `null`. (The sqliteSessions law, per file.)
+ */
+class UnreadableArtifactFileError extends Error {
+    code = 'ERR_UNREADABLE_ARTIFACT_FILE';
+    file;
+    constructor(file, detail) {
+        super(`[artifacts] the artifact file at '${file}' cannot be read: ${detail} ` +
+            `An unreadable artifact and a missing one are different facts — this refuses rather ` +
+            `than reporting "no data" over bytes that exist. Move the file aside to release the ref.`);
+        this.name = 'UnreadableArtifactFileError';
+        this.file = file;
+    }
+}
+exports.UnreadableArtifactFileError = UnreadableArtifactFileError;
+/**
+ * A directory-backed artifact store — durable across restarts, legible to a
+ * human, one file per artifact.
+ *
+ * @example
+ *   const store = fileArtifacts({ directory: './artifacts' });
+ *   const agent = Agent.create({ provider, artifacts: store });
+ */
+function fileArtifacts(options) {
+    const { directory, retention } = options;
+    if (typeof directory !== 'string' || directory.trim() === '') {
+        throw new TypeError(`[artifacts] fileArtifacts({ directory: ${JSON.stringify(directory)} }) names no ` +
+            `directory. Give it a path — it will be created if it does not exist.`);
+    }
+    (0, retention_js_1.assertRetention)('fileArtifacts', retention);
+    const now = options._now ?? Date.now;
+    const fs = (0, lazyRequire_js_1.lazyRequire)('node:fs');
+    const path = (0, lazyRequire_js_1.lazyRequire)('node:path');
+    fs.mkdirSync(directory, { recursive: true });
+    /**
+     * One RAW tuple field → one directory name. Encoded from the FIELD, never
+     * from the joined namespace (a tenant containing '/' must not become two
+     * path segments), and with dots encoded too — `encodeURIComponent` leaves
+     * `.` alone, so a tenant of literally `'..'` would otherwise survive as a
+     * real parent-directory hop. After this, `..`, `/` and `\` are inert
+     * directory NAMES (`%2E%2E`, `%2F`, `%5C`). Empty fields collapse to `_`,
+     * mirroring `identityNamespace`'s stable layout.
+     */
+    const segment = (raw) => encodeURIComponent(raw === undefined || raw === '' ? '_' : raw).replace(/\./g, '%2E');
+    const scopeDir = (scope) => path.join(directory, segment(scope.tenant), segment(scope.principal), segment(scope.conversationId));
+    const fileFor = (scope, ref) => path.join(scopeDir(scope), `${ref}.json`);
+    const readEnvelope = (file) => {
+        let raw;
+        try {
+            raw = fs.readFileSync(file, 'utf8');
+        }
+        catch {
+            return undefined; // never written (or already swept) — the null case.
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            throw new UnreadableArtifactFileError(file, 'it is not JSON.');
+        }
+        const candidate = parsed;
+        if (candidate === null ||
+            typeof candidate !== 'object' ||
+            typeof candidate.format !== 'number' ||
+            candidate.meta === undefined ||
+            candidate.payload === undefined) {
+            throw new UnreadableArtifactFileError(file, 'it is not an artifact envelope.');
+        }
+        if (candidate.format > FILE_FORMAT) {
+            throw new UnreadableArtifactFileError(file, `it was written with format ${candidate.format} and this runtime reads format ` +
+                `${FILE_FORMAT}; roll agentfootprint forward rather than half-read it.`);
+        }
+        return candidate;
+    };
+    /** Read a LIVE envelope; sweep the file when the calendar says it is gone. */
+    const liveEnvelope = (scope, ref) => {
+        if (!(0, naming_js_1.isArtifactRef)(ref))
+            return undefined;
+        const file = fileFor(scope, ref);
+        const envelope = readEnvelope(file);
+        if (envelope === undefined)
+            return undefined;
+        if (envelope.meta.expiresAt !== undefined && envelope.meta.expiresAt <= now()) {
+            fs.rmSync(file, { force: true });
+            return undefined;
+        }
+        return envelope;
+    };
+    /** Every live meta in a scope (expired files swept as they are found). */
+    const scopeMetas = (scope) => {
+        const dir = scopeDir(scope);
+        let names;
+        try {
+            names = fs.readdirSync(dir);
+        }
+        catch {
+            return []; // scope never wrote anything.
+        }
+        const at = now();
+        const metas = [];
+        for (const name of names) {
+            if (!name.endsWith('.json'))
+                continue;
+            const ref = name.slice(0, -'.json'.length);
+            if (!(0, naming_js_1.isArtifactRef)(ref))
+                continue; // not ours; leave foreign files alone.
+            const envelope = readEnvelope(path.join(dir, name));
+            if (envelope === undefined)
+                continue;
+            if (envelope.meta.expiresAt !== undefined && envelope.meta.expiresAt <= at) {
+                fs.rmSync(path.join(dir, name), { force: true });
+                continue;
+            }
+            metas.push(envelope.meta);
+        }
+        return metas;
+    };
+    return {
+        async put(scope, input) {
+            const at = now();
+            const { meta } = await (0, minting_js_1.prepareArtifact)(input, (parent) => liveEnvelope(scope, parent) !== undefined, retention, at);
+            const rows = scopeMetas(scope).map((held) => ({
+                ref: held.ref,
+                kind: held.kind,
+                bytes: held.bytes,
+                ...(held.expiresAt !== undefined && { expiresAt: held.expiresAt }),
+                // A directory has no cheap read-recency; oldest-first is the stated law.
+                lastAccessedAt: held.createdAt,
+            }));
+            const plan = (0, retention_js_1.planRetention)(rows, meta.bytes, retention, at);
+            if (plan.refusal !== undefined)
+                throw new types_js_1.InvalidArtifactError(plan.refusal);
+            for (const swept of plan.swept)
+                fs.rmSync(fileFor(scope, swept.ref), { force: true });
+            const envelope = {
+                format: FILE_FORMAT,
+                meta,
+                payload: (0, payload_js_1.encodeArtifactData)(input.data),
+            };
+            fs.mkdirSync(scopeDir(scope), { recursive: true });
+            fs.writeFileSync(fileFor(scope, meta.ref), JSON.stringify(envelope));
+            return { meta, swept: plan.swept };
+        },
+        // eslint-disable-next-line @typescript-eslint/require-await
+        async head(scope, ref) {
+            return liveEnvelope(scope, ref)?.meta ?? null;
+        },
+        async get(scope, ref) {
+            const envelope = liveEnvelope(scope, ref);
+            if (envelope === undefined)
+                return null;
+            const data = (0, payload_js_1.decodeArtifactData)(envelope.payload);
+            if (envelope.meta.digest !== undefined) {
+                const actual = await (0, payload_js_1.computeArtifactDigest)(data);
+                if (actual !== envelope.meta.digest) {
+                    throw new types_js_1.ArtifactIntegrityError(envelope.meta.ref, envelope.meta.digest, actual);
+                }
+            }
+            return { meta: envelope.meta, data };
+        },
+        // eslint-disable-next-line @typescript-eslint/require-await
+        async delete(scope, ref) {
+            if (!(0, naming_js_1.isArtifactRef)(ref))
+                return;
+            fs.rmSync(fileFor(scope, ref), { force: true });
+        },
+        // eslint-disable-next-line @typescript-eslint/require-await
+        async list(scope, listOptions) {
+            const all = scopeMetas(scope).sort((a, b) => b.createdAt - a.createdAt || (a.ref < b.ref ? -1 : 1));
+            const offset = decodeCursor(listOptions?.cursor);
+            const limit = Math.max(1, Math.floor(listOptions?.limit ?? 50));
+            const page = all.slice(offset, offset + limit);
+            const nextOffset = offset + page.length;
+            return {
+                artifacts: page,
+                ...(nextOffset < all.length && { cursor: String(nextOffset) }),
+            };
+        },
+    };
+}
+exports.fileArtifacts = fileArtifacts;
+function decodeCursor(cursor) {
+    if (cursor === undefined)
+        return 0;
+    const parsed = Number(cursor);
+    return Number.isFinite(parsed) && parsed >= 0 ? Math.floor(parsed) : 0;
+}
+//# sourceMappingURL=fileArtifacts.js.map

package/dist/artifacts/fileArtifacts.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fileArtifacts.js","sourceRoot":"","sources":["../../src/artifacts/fileArtifacts.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;;;AAEH,0DAAoD;AACpD,6CAA+C;AAC/C,2CAA4C;AAC5C,6CAKsB;AACtB,iDAKwB;AACxB,yCAWoB;AAEpB;kFACkF;AAClF,MAAM,WAAW,GAAG,CAAC,CAAC;AAmBtB;;;;GAIG;AACH,MAAa,2BAA4B,SAAQ,KAAK;IAC3C,IAAI,GAAG,8BAAuC,CAAC;IAC/C,IAAI,CAAS;IAEtB,YAAY,IAAY,EAAE,MAAc;QACtC,KAAK,CACH,qCAAqC,IAAI,qBAAqB,MAAM,GAAG;YACrE,qFAAqF;YACrF,yFAAyF,CAC5F,CAAC;QACF,IAAI,CAAC,IAAI,GAAG,6BAA6B,CAAC;QAC1C,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;IACnB,CAAC;CACF;AAbD,kEAaC;AAKD;;;;;;;GAOG;AACH,SAAgB,aAAa,CAAC,OAA6B;IACzD,MAAM,EAAE,SAAS,EAAE,SAAS,EAAE,GAAG,OAAO,CAAC;IACzC,IAAI,OAAO,SAAS,KAAK,QAAQ,IAAI,SAAS,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC7D,MAAM,IAAI,SAAS,CACjB,0CAA0C,IAAI,CAAC,SAAS,CAAC,SAAS,CAAC,eAAe;YAChF,sEAAsE,CACzE,CAAC;IACJ,CAAC;IACD,IAAA,8BAAe,EAAC,eAAe,EAAE,SAAS,CAAC,CAAC;IAC5C,MAAM,GAAG,GAAG,OAAO,CAAC,IAAI,IAAI,IAAI,CAAC,GAAG,CAAC;IACrC,MAAM,EAAE,GAAG,IAAA,4BAAW,EAAW,SAAS,CAAC,CAAC;IAC5C,MAAM,IAAI,GAAG,IAAA,4BAAW,EAAa,WAAW,CAAC,CAAC;IAClD,EAAE,CAAC,SAAS,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAE7C;;;;;;;;OAQG;IACH,MAAM,OAAO,GAAG,CAAC,GAAuB,EAAU,EAAE,CAClD,kBAAkB,CAAC,GAAG,KAAK,SAAS,IAAI,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;IAExF,MAAM,QAAQ,GAAG,CAAC,KAAoB,EAAU,EAAE,CAChD,IAAI,CAAC,IAAI,CACP,SAAS,EACT,OAAO,CAAC,KAAK,CAAC,MAAM,CAAC,EACrB,OAAO,CAAC,KAAK,CAAC,SAAS,CAAC,EACxB,OAAO,CAAC,KAAK,CAAC,cAAc,CAAC,CAC9B,CAAC;IAEJ,MAAM,OAAO,GAAG,CAAC,KAAoB,EAAE,GAAgB,EAAU,EAAE,CACjE,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,CAAC;IAE5C,MAAM,YAAY,GAAG,CAAC,IAAY,EAAgC,EAAE;QAClE,IAAI,GAAW,CAAC;QAChB,IAAI,CAAC;YACH,GAAG,GAAG,EAAE,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACtC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,SAAS,CAAC,CAAC,oDAAoD;QACxE,CAAC;QACD,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC3B,CAAC;QAAC,MAAM,CAAC;YACP,MAAM,IAAI,2BAA2B,CAAC,IAAI,EAAE,iBAAiB,CAAC,CAAC;QACjE,CAAC;QACD,MAAM,SAAS,GAAG,MAA0C,CAAC;QAC7D,IACE,SAAS,KAAK,IAAI;YAClB,OAAO,SAAS,KAAK,QAAQ;YAC7B,OAAO,SAAS,CAAC,MAAM,KAAK,QAAQ;YACpC,SAAS,CAAC,IAAI,KAAK,SAAS;YAC5B,SAAS,CAAC,OAAO,KAAK,SAAS,EAC/B,CAAC;YACD,MAAM,IAAI,2BAA2B,CAAC,IAAI,EAAE,iCAAiC,CAAC,CAAC;QACjF,CAAC;QACD,IAAI,SAAS,CAAC,MAAM,GAAG,WAAW,EAAE,CAAC;YACnC,MAAM,IAAI,2BAA2B,CACnC,IAAI,EACJ,8BAA8B,SAAS,CAAC,MAAM,iCAAiC;gBAC7E,GAAG,WAAW,yDAAyD,CAC1E,CAAC;QACJ,CAAC;QACD,OAAO,SAA6B,CAAC;IACvC,CAAC,CAAC;IAEF,8EAA8E;IAC9E,MAAM,YAAY,GAAG,CAAC,KAAoB,EAAE,GAAgB,EAAgC,EAAE;QAC5F,IAAI,CAAC,IAAA,yBAAa,EAAC,GAAG,CAAC;YAAE,OAAO,SAAS,CAAC;QAC1C,MAAM,IAAI,GAAG,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QACjC,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;QACpC,IAAI,QAAQ,KAAK,SAAS;YAAE,OAAO,SAAS,CAAC;QAC7C,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,IAAI,GAAG,EAAE,EAAE,CAAC;YAC9E,EAAE,CAAC,MAAM,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YACjC,OAAO,SAAS,CAAC;QACnB,CAAC;QACD,OAAO,QAAQ,CAAC;IAClB,CAAC,CAAC;IAEF,0EAA0E;IAC1E,MAAM,UAAU,GAAG,CAAC,KAAoB,EAAkB,EAAE;QAC1D,MAAM,GAAG,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;QAC5B,IAAI,KAAe,CAAC;QACpB,IAAI,CAAC;YACH,KAAK,GAAG,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,CAAC;QAC9B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAC,CAAC,8BAA8B;QAC3C,CAAC;QACD,MAAM,EAAE,GAAG,GAAG,EAAE,CAAC;QACjB,MAAM,KAAK,GAAmB,EAAE,CAAC;QACjC,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;YACzB,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC;gBAAE,SAAS;YACtC,MAAM,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC;YAC3C,IAAI,CAAC,IAAA,yBAAa,EAAC,GAAG,CAAC;gBAAE,SAAS,CAAC,uCAAuC;YAC1E,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,CAAC;YACpD,IAAI,QAAQ,KAAK,SAAS;gBAAE,SAAS;YACrC,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS,IAAI,QAAQ,CAAC,IAAI,CAAC,SAAS,IAAI,EAAE,EAAE,CAAC;gBAC3E,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;gBACjD,SAAS;YACX,CAAC;YACD,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;QAC5B,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC,CAAC;IAEF,OAAO;QACL,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,KAAK;YACpB,MAAM,EAAE,GAAG,GAAG,EAAE,CAAC;YACjB,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,IAAA,4BAAe,EACpC,KAAK,EACL,CAAC,MAAM,EAAE,EAAE,CAAC,YAAY,CAAC,KAAK,EAAE,MAAM,CAAC,KAAK,SAAS,EACrD,SAAS,EACT,EAAE,CACH,CAAC;YACF,MAAM,IAAI,GAAkB,UAAU,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC;gBAC3D,GAAG,EAAE,IAAI,CAAC,GAAG;gBACb,IAAI,EAAE,IAAI,CAAC,IAAI;gBACf,KAAK,EAAE,IAAI,CAAC,KAAK;gBACjB,GAAG,CAAC,IAAI,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC;gBAClE,yEAAyE;gBACzE,cAAc,EAAE,IAAI,CAAC,SAAS;aAC/B,CAAC,CAAC,CAAC;YACJ,MAAM,IAAI,GAAG,IAAA,4BAAa,EAAC,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,CAAC,CAAC;YAC5D,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS;gBAAE,MAAM,IAAI,+BAAoB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;YAC7E,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,KAAK;gBAAE,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,KAAK,CAAC,GAAG,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;YACtF,MAAM,QAAQ,GAAqB;gBACjC,MAAM,EAAE,WAAW;gBACnB,IAAI;gBACJ,OAAO,EAAE,IAAA,+BAAkB,EAAC,KAAK,CAAC,IAAI,CAAC;aACxC,CAAC;YACF,EAAE,CAAC,SAAS,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;YACnD,EAAE,CAAC,aAAa,CAAC,OAAO,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,EAAE,IAAI,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC;YACrE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC;QACrC,CAAC;QAED,4DAA4D;QAC5D,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,GAAG;YACnB,OAAO,YAAY,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,IAAI,IAAI,IAAI,CAAC;QAChD,CAAC;QAED,KAAK,CAAC,GAAG,CAAC,KAAK,EAAE,GAAG;YAClB,MAAM,QAAQ,GAAG,YAAY,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;YAC1C,IAAI,QAAQ,KAAK,SAAS;gBAAE,OAAO,IAAI,CAAC;YACxC,MAAM,IAAI,GAAG,IAAA,+BAAkB,EAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;YAClD,IAAI,QAAQ,CAAC,IAAI,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;gBACvC,MAAM,MAAM,GAAG,MAAM,IAAA,kCAAqB,EAAC,IAAI,CAAC,CAAC;gBACjD,IAAI,MAAM,KAAK,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;oBACpC,MAAM,IAAI,iCAAsB,CAAC,QAAQ,CAAC,IAAI,CAAC,GAAG,EAAE,QAAQ,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;gBACpF,CAAC;YACH,CAAC;YACD,OAAO,EAAE,IAAI,EAAE,QAAQ,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC;QACvC,CAAC;QAED,4DAA4D;QAC5D,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG;YACrB,IAAI,CAAC,IAAA,yBAAa,EAAC,GAAG,CAAC;gBAAE,OAAO;YAChC,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAClD,CAAC;QAED,4DAA4D;QAC5D,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,WAAiC;YACjD,MAAM,GAAG,GAAG,UAAU,CAAC,KAAK,CAAC,CAAC,IAAI,CAChC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,SAAS,GAAG,CAAC,CAAC,SAAS,IAAI,CAAC,CAAC,CAAC,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAChE,CAAC;YACF,MAAM,MAAM,GAAG,YAAY,CAAC,WAAW,EAAE,MAAM,CAAC,CAAC;YACjD,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,CAAC;YAChE,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,CAAC,CAAC;YAC/C,MAAM,UAAU,GAAG,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC;YACxC,OAAO;gBACL,SAAS,EAAE,IAAI;gBACf,GAAG,CAAC,UAAU,GAAG,GAAG,CAAC,MAAM,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC;aAC/D,CAAC;QACJ,CAAC;KACF,CAAC;AACJ,CAAC;AAlLD,sCAkLC;AAED,SAAS,YAAY,CAAC,MAA0B;IAC9C,IAAI,MAAM,KAAK,SAAS;QAAE,OAAO,CAAC,CAAC;IACnC,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,CAAC;IAC9B,OAAO,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,MAAM,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACzE,CAAC"}

package/dist/artifacts/inMemoryArtifacts.js

@@ -0,0 +1,165 @@
+"use strict";
+/**
+ * artifacts/inMemoryArtifacts — the claim-check store in a Map.
+ *
+ * For tests, local development, and single-process agents whose artifacts may
+ * die with the process. Exactly as durable as the process — which is the
+ * point of the port: swap the one argument for `fileArtifacts` or
+ * `sqliteArtifacts` and nothing else changes.
+ *
+ * ── Bounded, and counting its drops (the innerRunRecords laws) ─────────────
+ * A retained payload is retained memory, and an agent minting a dataset per
+ * turn for a week would otherwise pin every one of them — the failure would
+ * look like a leak rather than like a feature. So this adapter is ALWAYS
+ * bounded: it has a default byte budget and row budget per scope, an explicit
+ * retention only replaces those dials, and there is deliberately no spelling
+ * for "unbounded" here — a memory store without a ceiling is a leak wearing
+ * configuration. When the budget forces an eviction the least-recently-USED
+ * artifact leaves first (reading refreshes recency, so the dataset a chart is
+ * actively rendered from is not the next casualty), every eviction is
+ * reported by the `put` that caused it, and `dropped` COUNTS them — "we kept
+ * the last 200 of 340" is an answer a debugging session can act on; a
+ * silently missing ref is not.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.inMemoryArtifacts = exports.DEFAULT_IN_MEMORY_ARTIFACT_RETENTION = void 0;
+const index_js_1 = require("../memory/identity/index.js");
+const minting_js_1 = require("./minting.js");
+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");
+/** The always-on bounds. Override dials via `retention`; there is no "off". */
+exports.DEFAULT_IN_MEMORY_ARTIFACT_RETENTION = {
+    /** 32 MiB per scope — a working set, not an archive. */
+    maxBytesPerScope: 32 * 1024 * 1024,
+    /** 256 artifacts per scope. */
+    maxCountPerScope: 256,
+};
+/**
+ * A bounded, drop-counting, per-scope-isolated artifact store in process
+ * memory.
+ *
+ * @example
+ *   const store = inMemoryArtifacts({ retention: { ttlMs: 15 * 60_000 } });
+ *   const agent = Agent.create({ provider, artifacts: store });
+ */
+function inMemoryArtifacts(options = {}) {
+    (0, retention_js_1.assertRetention)('inMemoryArtifacts', options.retention);
+    const retention = {
+        ...exports.DEFAULT_IN_MEMORY_ARTIFACT_RETENTION,
+        ...options.retention,
+    };
+    const now = options._now ?? Date.now;
+    /** namespace → (ref → row). Insertion order is NOT recency; rows carry it. */
+    const scopes = new Map();
+    let dropped = 0;
+    const shelf = (scope) => {
+        const ns = (0, index_js_1.identityNamespace)(scope);
+        let held = scopes.get(ns);
+        if (held === undefined) {
+            held = new Map();
+            scopes.set(ns, held);
+        }
+        return held;
+    };
+    /** Resolve a live row, sweeping it when the calendar says it is gone. */
+    const liveRow = (scope, ref) => {
+        if (!(0, naming_js_1.isArtifactRef)(ref))
+            return undefined;
+        const held = shelf(scope);
+        const row = held.get(ref);
+        if (row === undefined)
+            return undefined;
+        if (row.meta.expiresAt !== undefined && row.meta.expiresAt <= now()) {
+            held.delete(ref);
+            return undefined;
+        }
+        return row;
+    };
+    return {
+        get dropped() {
+            return dropped;
+        },
+        retention,
+        async put(scope, input) {
+            const held = shelf(scope);
+            const at = now();
+            const { meta } = await (0, minting_js_1.prepareArtifact)(input, (parent) => liveRow(scope, parent) !== undefined, retention, at);
+            const rows = [...held.values()].map((row) => ({
+                ref: row.meta.ref,
+                kind: row.meta.kind,
+                bytes: row.meta.bytes,
+                ...(row.meta.expiresAt !== undefined && { expiresAt: row.meta.expiresAt }),
+                lastAccessedAt: row.lastAccessedAt,
+            }));
+            const plan = (0, retention_js_1.planRetention)(rows, meta.bytes, retention, at);
+            if (plan.refusal !== undefined)
+                throw new types_js_1.InvalidArtifactError(plan.refusal);
+            for (const swept of plan.swept) {
+                held.delete(swept.ref);
+                if (swept.reason !== 'ttl')
+                    dropped++;
+            }
+            held.set(meta.ref, { meta, payload: (0, payload_js_1.encodeArtifactData)(input.data), lastAccessedAt: at });
+            return { meta, swept: plan.swept };
+        },
+        // eslint-disable-next-line @typescript-eslint/require-await
+        async head(scope, ref) {
+            const row = liveRow(scope, ref);
+            if (row === undefined)
+                return null;
+            row.lastAccessedAt = now();
+            return row.meta;
+        },
+        async get(scope, ref) {
+            const row = liveRow(scope, ref);
+            if (row === undefined)
+                return null;
+            row.lastAccessedAt = now();
+            const data = (0, payload_js_1.decodeArtifactData)(row.payload);
+            if (row.meta.digest !== undefined) {
+                const actual = await (0, payload_js_1.computeArtifactDigest)(data);
+                if (actual !== row.meta.digest) {
+                    throw new types_js_1.ArtifactIntegrityError(row.meta.ref, row.meta.digest, actual);
+                }
+            }
+            return { meta: row.meta, data };
+        },
+        // eslint-disable-next-line @typescript-eslint/require-await
+        async delete(scope, ref) {
+            if (!(0, naming_js_1.isArtifactRef)(ref))
+                return;
+            shelf(scope).delete(ref);
+        },
+        // eslint-disable-next-line @typescript-eslint/require-await
+        async list(scope, listOptions) {
+            const at = now();
+            const held = shelf(scope);
+            // Sweep-on-access: an expired row is "no data" everywhere, lists included.
+            for (const [ref, row] of held) {
+                if (row.meta.expiresAt !== undefined && row.meta.expiresAt <= at)
+                    held.delete(ref);
+            }
+            const all = [...held.values()]
+                .map((row) => row.meta)
+                .sort((a, b) => b.createdAt - a.createdAt || (a.ref < b.ref ? -1 : 1));
+            const offset = decodeCursor(listOptions?.cursor);
+            const limit = Math.max(1, Math.floor(listOptions?.limit ?? 50));
+            const page = all.slice(offset, offset + limit);
+            const nextOffset = offset + page.length;
+            return {
+                artifacts: page,
+                ...(nextOffset < all.length && { cursor: String(nextOffset) }),
+            };
+        },
+    };
+}
+exports.inMemoryArtifacts = inMemoryArtifacts;
+function decodeCursor(cursor) {
+    if (cursor === undefined)
+        return 0;
+    const parsed = Number(cursor);
+    return Number.isFinite(parsed) && parsed >= 0 ? Math.floor(parsed) : 0;
+}
+//# sourceMappingURL=inMemoryArtifacts.js.map

package/dist/artifacts/inMemoryArtifacts.js.map

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

package/dist/artifacts/index.js

@@ -0,0 +1,33 @@
+"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, and
+ * the `ctx.artifacts` capability (`capability`). See README.md in this
+ * folder for the one-job map and the import direction.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+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; } });
+//# sourceMappingURL=index.js.map