agentfootprint 9.20.0 → 9.22.0

package/dist/esm/artifacts/inMemoryArtifacts.js

@@ -0,0 +1,161 @@
+/**
+ * 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.
+ */
+import { identityNamespace } from '../memory/identity/index.js';
+import { prepareArtifact } from './minting.js';
+import { isArtifactRef } from './naming.js';
+import { computeArtifactDigest, decodeArtifactData, encodeArtifactData, } from './payload.js';
+import { assertRetention, planRetention, } from './retention.js';
+import { ArtifactIntegrityError, InvalidArtifactError, } from './types.js';
+/** The always-on bounds. Override dials via `retention`; there is no "off". */
+export const 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 });
+ */
+export function inMemoryArtifacts(options = {}) {
+    assertRetention('inMemoryArtifacts', options.retention);
+    const retention = {
+        ...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 = 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 (!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 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 = planRetention(rows, meta.bytes, retention, at);
+            if (plan.refusal !== undefined)
+                throw new InvalidArtifactError(plan.refusal);
+            for (const swept of plan.swept) {
+                held.delete(swept.ref);
+                if (swept.reason !== 'ttl')
+                    dropped++;
+            }
+            held.set(meta.ref, { meta, payload: 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 = decodeArtifactData(row.payload);
+            if (row.meta.digest !== undefined) {
+                const actual = await computeArtifactDigest(data);
+                if (actual !== row.meta.digest) {
+                    throw new 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 (!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) }),
+            };
+        },
+    };
+}
+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/esm/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/esm/artifacts/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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.
+ */
+export { ArtifactIntegrityError, InvalidArtifactError, UnknownParentRefError, type ArtifactListOptions, type ArtifactListResult, type ArtifactMeta, type ArtifactOrigin, type ArtifactPutResult, type ArtifactRecord, type ArtifactRef, type ArtifactScope, type ArtifactStore, type ArtifactSweepReason, type PutArtifactInput, type SweptArtifact, } from './types.js';
+export { ARTIFACT_REF_PREFIX, isArtifactRef, mintArtifactRef } from './naming.js';
+export { type ArtifactRetention } from './retention.js';
+export { inMemoryArtifacts, DEFAULT_IN_MEMORY_ARTIFACT_RETENTION, type InMemoryArtifacts, type InMemoryArtifactsOptions, } from './inMemoryArtifacts.js';
+export { fileArtifacts, UnreadableArtifactFileError, type FileArtifactsOptions, } from './fileArtifacts.js';
+export { sqliteArtifacts, UnreadableArtifactStoreError, type SqliteArtifacts, type SqliteArtifactsOptions, } from './sqliteArtifacts.js';
+export { bindArtifacts, unconfiguredArtifacts, type ArtifactEventFact, type ArtifactEventSink, type ArtifactOp, type ArtifactRefusalReason, type BindArtifactsOptions, type ToolArtifactPutInput, type ToolArtifacts, } from './capability.js';
+export { assertToolWants, resolveToolWants, wantsNeedsStoreRefusal, type ToolWants, type WantsRefusal, type WantsResolution, } from './wants.js';
+export { PRESENT_TOOL_NAME, presentArtifact, type PresentOutcome, type PresentSnapshot, type PresentedResult, } from './present.js';
+export { assertArtifactPlacement, isPlacedToolResult, placedResultKind, placedToolResult, type ArtifactPlacement, type PlacedToolResult, } from './placement.js';

package/dist/esm/artifacts/index.js

@@ -0,0 +1,21 @@
+/**
+ * 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.
+ */
+export { ArtifactIntegrityError, InvalidArtifactError, UnknownParentRefError, } from './types.js';
+export { ARTIFACT_REF_PREFIX, isArtifactRef, mintArtifactRef } from './naming.js';
+export { inMemoryArtifacts, DEFAULT_IN_MEMORY_ARTIFACT_RETENTION, } from './inMemoryArtifacts.js';
+export { fileArtifacts, UnreadableArtifactFileError, } from './fileArtifacts.js';
+export { sqliteArtifacts, UnreadableArtifactStoreError, } from './sqliteArtifacts.js';
+export { bindArtifacts, unconfiguredArtifacts, } from './capability.js';
+export { assertToolWants, resolveToolWants, wantsNeedsStoreRefusal, } from './wants.js';
+export { PRESENT_TOOL_NAME, presentArtifact, } from './present.js';
+export { assertArtifactPlacement, isPlacedToolResult, placedResultKind, placedToolResult, } from './placement.js';
+//# sourceMappingURL=index.js.map

package/dist/esm/artifacts/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/artifacts/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EACL,sBAAsB,EACtB,oBAAoB,EACpB,qBAAqB,GAatB,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,mBAAmB,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAElF,OAAO,EACL,iBAAiB,EACjB,oCAAoC,GAGrC,MAAM,wBAAwB,CAAC;AAChC,OAAO,EACL,aAAa,EACb,2BAA2B,GAE5B,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EACL,eAAe,EACf,4BAA4B,GAG7B,MAAM,sBAAsB,CAAC;AAC9B,OAAO,EACL,aAAa,EACb,qBAAqB,GAQtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,sBAAsB,GAIvB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,iBAAiB,EACjB,eAAe,GAIhB,MAAM,cAAc,CAAC;AACtB,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,GAGjB,MAAM,gBAAgB,CAAC"}

package/dist/esm/artifacts/minting.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 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.
+ */
+import { type ArtifactRetention } from './retention.js';
+import { type ArtifactMeta, type ArtifactRef, type PutArtifactInput } from './types.js';
+/** What an adapter lends the pipeline: "does this ref resolve, in THIS scope?" */
+export type ParentResolver = (ref: ArtifactRef) => boolean | Promise<boolean>;
+/**
+ * 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.
+ */
+export declare function prepareArtifact(input: PutArtifactInput, resolveParent: ParentResolver, retention: ArtifactRetention | undefined, now: number): Promise<{
+    meta: ArtifactMeta;
+    bytes: number;
+}>;

package/dist/esm/artifacts/minting.js

@@ -0,0 +1,75 @@
+/**
+ * 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.
+ */
+import { isArtifactRef, mintArtifactRef } from './naming.js';
+import { computeArtifactDigest, measureArtifactBytes } from './payload.js';
+import { resolveExpiresAt } from './retention.js';
+import { InvalidArtifactError, UnknownParentRefError, } from './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.
+ */
+export async function prepareArtifact(input, resolveParent, retention, now) {
+    if (typeof input.kind !== 'string' || input.kind.trim() === '') {
+        throw new 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 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 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 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 (!isArtifactRef(parent) || !(await resolveParent(parent)))
+                unresolved.push(parent);
+        }
+        if (unresolved.length > 0)
+            throw new UnknownParentRefError(unresolved);
+    }
+    // Measure (and refuse the unserializable) BEFORE minting, so a refused put
+    // never burns a ref.
+    const bytes = measureArtifactBytes(input.data);
+    const digest = input.digest === 'sha-256' ? await computeArtifactDigest(input.data) : undefined;
+    const expiresAt = resolveExpiresAt(input.expiresAt, retention, now);
+    const meta = {
+        ref: 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 };
+}
+//# sourceMappingURL=minting.js.map

package/dist/esm/artifacts/minting.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"minting.js","sourceRoot":"","sources":["../../../src/artifacts/minting.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC7D,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AAC3E,OAAO,EAAE,gBAAgB,EAA0B,MAAM,gBAAgB,CAAC;AAC1E,OAAO,EACL,oBAAoB,EACpB,qBAAqB,GAItB,MAAM,YAAY,CAAC;AAKpB;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,KAAuB,EACvB,aAA6B,EAC7B,SAAwC,EACxC,GAAW;IAEX,IAAI,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QAC/D,MAAM,IAAI,oBAAoB,CAC5B,WAAW,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,CAAC,+CAA+C;YAClF,wFAAwF;YACxF,6BAA6B,CAChC,CAAC;IACJ,CAAC;IACD,IAAI,OAAO,KAAK,CAAC,SAAS,KAAK,QAAQ,IAAI,KAAK,CAAC,SAAS,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE,CAAC;QACzE,MAAM,IAAI,oBAAoB,CAC5B,gBAAgB,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,SAAS,CAAC,iCAAiC;YAC9E,gFAAgF,CACnF,CAAC;IACJ,CAAC;IACD,IACE,KAAK,CAAC,SAAS,KAAK,SAAS;QAC7B,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,SAAS,CAAC,IAAI,KAAK,CAAC,SAAS,IAAI,GAAG,CAAC,EAC7D,CAAC;QACD,MAAM,IAAI,oBAAoB,CAC5B,eAAe,MAAM,CAAC,KAAK,CAAC,SAAS,CAAC,kDAAkD;YACtF,gFAAgF,CACnF,CAAC;IACJ,CAAC;IACD,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC7D,MAAM,IAAI,oBAAoB,CAC5B,YAAY,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,MAAM,CAAC,4CAA4C;YAClF,6DAA6D,CAChE,CAAC;IACJ,CAAC;IAED,yEAAyE;IACzE,IAAI,KAAK,CAAC,UAAU,KAAK,SAAS,IAAI,KAAK,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAClE,MAAM,UAAU,GAAkB,EAAE,CAAC;QACrC,KAAK,MAAM,MAAM,IAAI,KAAK,CAAC,UAAU,EAAE,CAAC;YACtC,IAAI,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,MAAM,aAAa,CAAC,MAAM,CAAC,CAAC;gBAAE,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACxF,CAAC;QACD,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC;YAAE,MAAM,IAAI,qBAAqB,CAAC,UAAU,CAAC,CAAC;IACzE,CAAC;IAED,2EAA2E;IAC3E,qBAAqB;IACrB,MAAM,KAAK,GAAG,oBAAoB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC/C,MAAM,MAAM,GAAG,KAAK,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,MAAM,qBAAqB,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAChG,MAAM,SAAS,GAAG,gBAAgB,CAAC,KAAK,CAAC,SAAS,EAAE,SAAS,EAAE,GAAG,CAAC,CAAC;IAEpE,MAAM,IAAI,GAAiB;QACzB,GAAG,EAAE,eAAe,EAAE;QACtB,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,SAAS,EAAE,KAAK,CAAC,SAAS;QAC1B,KAAK;QACL,SAAS,EAAE,GAAG;QACd,GAAG,CAAC,KAAK,CAAC,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,CAAC;QACxD,GAAG,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,CAAC;QACvC,GAAG,CAAC,SAAS,KAAK,SAAS,IAAI,EAAE,SAAS,EAAE,CAAC;QAC7C,GAAG,CAAC,KAAK,CAAC,MAAM,KAAK,SAAS,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC;QAC3D,GAAG,CAAC,KAAK,CAAC,UAAU,KAAK,SAAS;YAChC,KAAK,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,IAAI,EAAE,UAAU,EAAE,CAAC,GAAG,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC;KACxE,CAAC;IACF,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AACzB,CAAC"}

package/dist/esm/artifacts/naming.d.ts

@@ -0,0 +1,36 @@
+/**
+ * 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.
+ */
+import type { ArtifactRef } from './types.js';
+/** The prefix every minted ref carries. */
+export declare const ARTIFACT_REF_PREFIX = "art_";
+/**
+ * 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).
+ */
+export declare function mintArtifactRef(): ArtifactRef;
+/**
+ * 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.
+ */
+export declare function isArtifactRef(candidate: unknown): candidate is ArtifactRef;

package/dist/esm/artifacts/naming.js

@@ -0,0 +1,59 @@
+/**
+ * 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.
+ */
+/** The prefix every minted ref carries. */
+export const 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).
+ */
+export 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 `${ARTIFACT_REF_PREFIX}${out.join('')}`;
+}
+/**
+ * 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.
+ */
+export function isArtifactRef(candidate) {
+    return typeof candidate === 'string' && REF_PATTERN.test(candidate);
+}
+//# sourceMappingURL=naming.js.map

package/dist/esm/artifacts/naming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"naming.js","sourceRoot":"","sources":["../../../src/artifacts/naming.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAIH,2CAA2C;AAC3C,MAAM,CAAC,MAAM,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,MAAM,UAAU,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,mBAAmB,GAAG,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC;AACjD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,aAAa,CAAC,SAAkB;IAC9C,OAAO,OAAO,SAAS,KAAK,QAAQ,IAAI,WAAW,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;AACtE,CAAC"}

package/dist/esm/artifacts/payload.d.ts

@@ -0,0 +1,43 @@
+/**
+ * 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.
+ */
+/**
+ * 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.
+ */
+export declare function canonicalPayloadBytes(data: unknown): Uint8Array;
+/** Payload size in bytes — UTF-8 for text/JSON, byteLength for binary. */
+export declare function measureArtifactBytes(data: unknown): number;
+/** `sha-256:<hex>` over the canonical bytes. */
+export declare function computeArtifactDigest(data: unknown): Promise<string>;
+/** How a payload rides a file or a SQL TEXT column. One shape, two adapters. */
+export interface EncodedPayload {
+    readonly shape: 'text' | 'binary' | 'json';
+    /** `text`: the string. `binary`: base64. `json`: the JSON serialization. */
+    readonly value: string;
+}
+/** Encode for durable storage. Validates exactly as `measure` does. */
+export declare function encodeArtifactData(data: unknown): EncodedPayload;
+/** Decode what {@link encodeArtifactData} wrote. Total over its own output. */
+export declare function decodeArtifactData(encoded: EncodedPayload): unknown;

package/dist/esm/artifacts/payload.js

@@ -0,0 +1,105 @@
+/**
+ * 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.
+ */
+import { InvalidArtifactError } from './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.
+ */
+export 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 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 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);
+}
+/** Payload size in bytes — UTF-8 for text/JSON, byteLength for binary. */
+export function measureArtifactBytes(data) {
+    return canonicalPayloadBytes(data).byteLength;
+}
+/** `sha-256:<hex>` over the canonical bytes. */
+export 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}`;
+}
+/** Encode for durable storage. Validates exactly as `measure` does. */
+export 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)) };
+}
+/** Decode what {@link encodeArtifactData} wrote. Total over its own output. */
+export function decodeArtifactData(encoded) {
+    switch (encoded.shape) {
+        case 'text':
+            return encoded.value;
+        case 'binary':
+            return fromBase64(encoded.value);
+        case 'json':
+            return JSON.parse(encoded.value);
+    }
+}
+// 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/esm/artifacts/payload.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payload.js","sourceRoot":"","sources":["../../../src/artifacts/payload.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAElD,MAAM,WAAW,GAAG,IAAI,WAAW,EAAE,CAAC;AACtC,MAAM,WAAW,GAAG,IAAI,WAAW,EAAE,CAAC;AAEtC;;;;GAIG;AACH,MAAM,UAAU,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,oBAAoB,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,oBAAoB,CAC5B,0EAA0E;YACxE,4EAA4E;YAC5E,2CAA2C,CAC9C,CAAC;IACJ,CAAC;IACD,OAAO,WAAW,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC;AACxC,CAAC;AAED,0EAA0E;AAC1E,MAAM,UAAU,oBAAoB,CAAC,IAAa;IAChD,OAAO,qBAAqB,CAAC,IAAI,CAAC,CAAC,UAAU,CAAC;AAChD,CAAC;AAED,gDAAgD;AAChD,MAAM,CAAC,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;AAWD,uEAAuE;AACvE,MAAM,UAAU,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;AAED,+EAA+E;AAC/E,MAAM,UAAU,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;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"}