@aigne/afs-did-space 1.12.0-beta.5

package/dist/inline-content-migration.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"inline-content-migration.mjs","names":[],"sources":["../src/inline-content-migration.ts"],"sourcesContent":["/**\n * inline-content-migration — one-time backfill of the inline `content` column\n * for upload-plane-synced rows that were committed metadata-only\n * (inline-content-commit §7, mechanism A: server paged sweep).\n *\n * The forward fix (Phases 1-2) stops NEW upload-plane commits from dropping the\n * inline copy; this sweep repairs EXISTING `content IS NULL` rows so the\n * collection query (json_extract over the content column) sees them too.\n *\n * Trigger surface (resolved at Phase 6): an OFFLINE script calls\n * {@link backfillInlineContent} — NOT a permanent exec action. The core loop\n * here is backend-agnostic (the SQL lives in {@link InlineBackfillBackend}\n * adapters) so it is unit-testable against a mock D1 + MemoryObjectStore, and a\n * thin script wires the real DB + object store.\n *\n * Invariants:\n *  - **R2 is the only place the bytes live**, so each candidate = 1 R2 GET. Size\n *    the page to the deployment tier (≤40/free, a few hundred/paid) and run it\n *    OFF the hot path, throttled — this is exactly the回源 the commit path\n *    refuses to do (§10).\n *  - **Text judged by `detectMimeType(path)`, NOT the `mime_type` column** — old\n *    upload-plane rows have `mime_type` NULL too (toEntry sent none), so a\n *    column filter would skip the very rows we fix. The mime is backfilled here.\n *  - **Idempotent**: only `content IS NULL` rows are selected, and `backfillRow`\n *    re-checks `content IS NULL`, so a re-run is a no-op. The path cursor\n *    advances past EVERY scanned row (including skips) so a single invocation\n *    can't loop; a fresh invocation re-scans from the start and naturally\n *    re-selects the still-NULL rows a prior pass deferred.\n *  - **Per-row fail-soft**: object 404 → skip + log (never fail the page);\n *    transient R2 error → bounded retry then defer (row stays NULL → re-selected\n *    next pass); cid mismatch → skip (never store bytes that don't hash to cid).\n */\n\nimport type { ObjectStore } from \"@aigne/afs-r2\";\nimport { computeCID } from \"./cid.js\";\nimport { DEFAULT_INLINE_THRESHOLD, decodeInlineText } from \"./inline-content.js\";\nimport { detectMimeType, isTextMime } from \"./mime-utils.js\";\nimport { objectKeyForCid } from \"./object-key.js\";\n\n/** A content-NULL file row eligible for inline backfill. */\nexport interface InlineBackfillCandidate {\n  path: string;\n  cid: string;\n  size: number;\n}\n\n/** Backend-specific SQL for the sweep (D1 vs Node SQLite). */\nexport interface InlineBackfillBackend {\n  /**\n   * Select up to `limit` content-NULL FILE rows with `path > cursor` and\n   * `size <= threshold`, ordered by `path ASC` (the keyset cursor). Empty array\n   * ⇒ no more candidates after `cursor`.\n   */\n  selectCandidates(\n    cursor: string,\n    limit: number,\n    threshold: number,\n  ): Promise<InlineBackfillCandidate[]>;\n  /**\n   * Set `content` + `mime_type` for `path` ONLY IF the row is still\n   * `content IS NULL` (idempotent — a concurrent/earlier fill wins). `mimeType`\n   * is `null` for extensionless / unknown-extension paths — stored as SQL NULL\n   * to match the write path (so `isTextMime(null)` stays true and the read path\n   * still serves the inline copy; an empty string would flip `isTextMime` false).\n   */\n  backfillRow(path: string, content: string, mimeType: string | null): Promise<void>;\n}\n\nexport interface InlineBackfillOptions {\n  /** `size <= threshold` filter (default {@link DEFAULT_INLINE_THRESHOLD} = 2 KB). */\n  threshold?: number;\n  /** Rows per page = R2 GETs per page. Default 40 (free-tier 50-subrequest safe). */\n  pageSize?: number;\n  /** Cap pages this invocation (cross-invocation paging). Default unbounded. */\n  maxPages?: number;\n  /** Sleep (ms) after each R2 read to pace subrequests. Default 0. */\n  throttleMs?: number;\n  /** Bounded retries on a transient R2 error before deferring the row. Default 2. */\n  retries?: number;\n  /** Injectable sleep (tests pass a no-op). */\n  sleep?: (ms: number) => Promise<void>;\n  /** Progress / skip logger. */\n  log?: (msg: string) => void;\n}\n\nexport interface InlineBackfillStats {\n  scanned: number;\n  backfilled: number;\n  skippedNonText: number;\n  skippedMissing: number;\n  skippedMismatch: number;\n  deferredError: number;\n  pages: number;\n  lastCursor: string;\n  /** True when a page came back empty (the sweep reached the end). */\n  done: boolean;\n}\n\nconst defaultSleep = (ms: number) => new Promise<void>((r) => setTimeout(r, ms));\n\n/**\n * Page over content-NULL rows and backfill the inline copy from R2. Returns\n * stats; resumable across invocations (a fresh call re-scans from the start and\n * re-selects whatever is still NULL).\n */\nexport async function backfillInlineContent(\n  backend: InlineBackfillBackend,\n  objectStore: ObjectStore,\n  opts: InlineBackfillOptions = {},\n): Promise<InlineBackfillStats> {\n  const threshold = opts.threshold ?? DEFAULT_INLINE_THRESHOLD;\n  const pageSize = opts.pageSize ?? 40;\n  const maxPages = opts.maxPages ?? Number.POSITIVE_INFINITY;\n  const retries = opts.retries ?? 2;\n  const throttleMs = opts.throttleMs ?? 0;\n  const sleep = opts.sleep ?? defaultSleep;\n  const log = opts.log ?? (() => {});\n\n  const stats: InlineBackfillStats = {\n    scanned: 0,\n    backfilled: 0,\n    skippedNonText: 0,\n    skippedMissing: 0,\n    skippedMismatch: 0,\n    deferredError: 0,\n    pages: 0,\n    lastCursor: \"\",\n    done: false,\n  };\n\n  let cursor = \"\";\n  while (stats.pages < maxPages) {\n    const rows = await backend.selectCandidates(cursor, pageSize, threshold);\n    if (rows.length === 0) {\n      stats.done = true;\n      break;\n    }\n    stats.pages++;\n    for (const row of rows) {\n      stats.scanned++;\n      cursor = row.path; // advance past EVERY scanned row so a single pass can't loop\n      stats.lastCursor = cursor;\n\n      // Text judged by path, NOT the (likely-NULL) mime_type column.\n      const mime = detectMimeType(row.path);\n      if (!isTextMime(mime)) {\n        stats.skippedNonText++;\n        continue;\n      }\n\n      // Read the bytes from R2 (the only place they live). 404 → skip; transient\n      // → bounded retry then defer (stays NULL → re-selected next invocation).\n      let bytes: Uint8Array | null = null;\n      let lastErr: unknown;\n      let absent = false;\n      for (let attempt = 0; attempt <= retries; attempt++) {\n        try {\n          const obj = await objectStore.get(objectKeyForCid(row.cid));\n          if (!obj) {\n            absent = true;\n          } else {\n            bytes = new Uint8Array(await obj.arrayBuffer());\n          }\n          lastErr = undefined;\n          break;\n        } catch (e) {\n          lastErr = e;\n          if (attempt < retries) await sleep(throttleMs || 50);\n        }\n      }\n      if (lastErr !== undefined) {\n        stats.deferredError++;\n        log(`defer ${row.path}: R2 read error ${String(lastErr)}`);\n        continue;\n      }\n      if (absent) {\n        stats.skippedMissing++;\n        log(`skip ${row.path}: object ${row.cid} missing (404)`);\n        continue;\n      }\n\n      // Decode (text-mime + ≤hard-cap + strict UTF-8) — null = not inlinable.\n      const content = decodeInlineText(bytes as Uint8Array, mime ?? undefined);\n      if (content === null) {\n        stats.skippedNonText++;\n        continue;\n      }\n      // Never store bytes that don't hash to the row cid (write-path contract).\n      if ((await computeCID(content)) !== row.cid) {\n        stats.skippedMismatch++;\n        log(`skip ${row.path}: cid mismatch (content hash != ${row.cid})`);\n        continue;\n      }\n\n      await backend.backfillRow(row.path, content, mime ?? null);\n      stats.backfilled++;\n      if (throttleMs > 0) await sleep(throttleMs);\n    }\n  }\n  return stats;\n}\n\nconst SELECT_SQL =\n  \"SELECT path, cid, size FROM ds_entries WHERE scope = ? AND kind = 'file' \" +\n  \"AND content IS NULL AND size <= ? AND path > ? ORDER BY path ASC LIMIT ?\";\nconst UPDATE_SQL =\n  \"UPDATE ds_entries SET content = ?, mime_type = ? WHERE scope = ? AND path = ? AND content IS NULL\";\n\n/** D1 (Cloudflare) backend adapter — the same SQL the index uses. */\nexport function makeD1InlineBackfillBackend(db: D1Database, scope: string): InlineBackfillBackend {\n  return {\n    async selectCandidates(cursor, limit, threshold) {\n      const res = await db.prepare(SELECT_SQL).bind(scope, threshold, cursor, limit).all();\n      return ((res.results ?? []) as Array<Record<string, unknown>>).map((r) => ({\n        path: String(r.path),\n        cid: String(r.cid),\n        size: Number(r.size),\n      }));\n    },\n    async backfillRow(path, content, mimeType) {\n      await db.prepare(UPDATE_SQL).bind(content, mimeType, scope, path).run();\n    },\n  };\n}\n\n/**\n * Minimal libsql client shape the SQLite adapter needs (Node `_metadata.db`).\n * `args` is narrowed to `(string | number)[]` — exactly what the sweep binds —\n * so a real `@libsql/client` `Client` is structurally assignable (a wider\n * `unknown[]` is not assignable to libsql's `InValue[]`).\n */\nexport interface LibsqlLike {\n  execute(stmt: { sql: string; args: (string | number | null)[] }): Promise<{\n    rows: Array<Record<string, unknown>>;\n  }>;\n}\n\n/** Node SQLite (libsql) backend adapter. */\nexport function makeSqliteInlineBackfillBackend(\n  db: LibsqlLike,\n  scope: string,\n): InlineBackfillBackend {\n  return {\n    async selectCandidates(cursor, limit, threshold) {\n      const res = await db.execute({ sql: SELECT_SQL, args: [scope, threshold, cursor, limit] });\n      return res.rows.map((r) => ({\n        path: String(r.path),\n        cid: String(r.cid),\n        size: Number(r.size),\n      }));\n    },\n    async backfillRow(path, content, mimeType) {\n      await db.execute({ sql: UPDATE_SQL, args: [content, mimeType, scope, path] });\n    },\n  };\n}\n\nconst DISTINCT_NULL_SCOPES_SQL =\n  \"SELECT DISTINCT scope FROM ds_entries WHERE kind = 'file' AND content IS NULL AND size <= ?\";\n\n/**\n * CF D1 over the HTTP API (`POST /accounts/{acct}/d1/database/{db}/query`) — the\n * OFFLINE realization of mechanism A for staging/prod CF: a Node process holds a\n * Cloudflare API token with D1-edit and runs the SAME paged sweep SQL the worker\n * would, while reading R2 objects out-of-band (the script supplies the\n * ObjectStore — e.g. R2 presigned GET). `fetchImpl` is injectable for tests.\n */\nexport interface D1HttpConfig {\n  accountId: string;\n  databaseId: string;\n  apiToken: string;\n  scope: string;\n  fetchImpl?: typeof fetch;\n  /**\n   * Bounded retries for TRANSIENT D1 HTTP failures (5xx — incl. the occasional\n   * `code 7500 internal error` — / 429 / network) with exponential backoff. A\n   * one-off CF hiccup must NOT abort a multi-thousand-row sweep. Permanent 4xx\n   * (auth/SQL) throw immediately. Default 4. `sleep` injectable for tests.\n   */\n  maxRetries?: number;\n  sleep?: (ms: number) => Promise<void>;\n}\n\n/** Run one D1 HTTP query (with transient-error retry); returns the rows or throws. */\nasync function d1HttpQuery(\n  cfg: Omit<D1HttpConfig, \"scope\">,\n  sql: string,\n  params: (string | number | null)[],\n): Promise<Array<Record<string, unknown>>> {\n  const f = cfg.fetchImpl ?? fetch;\n  const sleep = cfg.sleep ?? defaultSleep;\n  const maxRetries = cfg.maxRetries ?? 4;\n  const url = `https://api.cloudflare.com/client/v4/accounts/${cfg.accountId}/d1/database/${cfg.databaseId}/query`;\n  for (let attempt = 0; ; attempt++) {\n    let status = 0;\n    let json:\n      | {\n          success?: boolean;\n          errors?: unknown;\n          result?: Array<{ results?: Array<Record<string, unknown>> }>;\n        }\n      | undefined;\n    let networkErr: unknown;\n    try {\n      const res = await f(url, {\n        method: \"POST\",\n        headers: { authorization: `Bearer ${cfg.apiToken}`, \"content-type\": \"application/json\" },\n        body: JSON.stringify({ sql, params }),\n      });\n      status = res.status;\n      json = await res.json();\n    } catch (e) {\n      networkErr = e; // network/parse failure → transient\n    }\n    if (!networkErr && status >= 200 && status < 300 && json?.success !== false) {\n      return json?.result?.[0]?.results ?? [];\n    }\n    // 5xx / 429 / network → transient (retry); 4xx (auth/SQL) → permanent (throw now).\n    const transient = networkErr != null || status >= 500 || status === 429;\n    const msg = networkErr\n      ? `D1 HTTP network error: ${String(networkErr).slice(0, 160)}`\n      : `D1 HTTP ${status}: ${JSON.stringify(json?.errors ?? json).slice(0, 200)}`;\n    if (!transient || attempt >= maxRetries) throw new Error(msg);\n    await sleep(Math.min(2000, 200 * 2 ** attempt));\n  }\n}\n\n/** CF D1 HTTP-API backend adapter (offline mechanism A for staging/prod). */\nexport function makeD1HttpInlineBackfillBackend(cfg: D1HttpConfig): InlineBackfillBackend {\n  return {\n    async selectCandidates(cursor, limit, threshold) {\n      const rows = await d1HttpQuery(cfg, SELECT_SQL, [cfg.scope, threshold, cursor, limit]);\n      return rows.map((r) => ({ path: String(r.path), cid: String(r.cid), size: Number(r.size) }));\n    },\n    async backfillRow(path, content, mimeType) {\n      await d1HttpQuery(cfg, UPDATE_SQL, [content, mimeType, cfg.scope, path]);\n    },\n  };\n}\n\n/**\n * List the distinct scopes that still have content-NULL file rows (≤ threshold)\n * on a CF D1, so a bulk sweep can migrate each scope-aware. One HTTP query.\n */\nexport async function listD1NullContentScopes(\n  cfg: Omit<D1HttpConfig, \"scope\">,\n  threshold: number = DEFAULT_INLINE_THRESHOLD,\n): Promise<string[]> {\n  const rows = await d1HttpQuery(cfg, DISTINCT_NULL_SCOPES_SQL, [threshold]);\n  return rows.map((r) => String(r.scope));\n}\n"],"mappings":"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"}

package/dist/inline-content.cjs

@@ -0,0 +1,145 @@
+const require_rolldown_runtime = require('./_virtual/rolldown_runtime.cjs');
+const require_cid = require('./cid.cjs');
+require('./mime-utils.cjs');
+let _aigne_afs_provider_utils = require("@aigne/afs-provider-utils");
+
+//#region src/inline-content.ts
+/**
+* Inline content — Layer 0 generic TreeIndex capability contract (Phase 0).
+*
+* A TreeIndex row may carry a small inline copy of the file's bytes in a
+* `content` column, eliminating the per-entry object fetch on bulk reads.
+* Four contract clauses (conformance suite:
+* `@aigne/afs-testing` → `suites/inline-content.ts`):
+*
+* 1. **cid-verified** — whenever `content` is present, `hash(content) === cid`
+*    holds. The cid is always computed; writes verify once and REJECT a
+*    mismatched pair. The cid stays the identity; content is just a co-located
+*    copy of the same bytes — it can never go stale and never breaks any
+*    cid-addressed mechanism.
+*
+* 2. **Two store classes** (statically determined at construction — no runtime
+*    probing):
+*    - **CAS store** (object backend present; cid is a public address): the
+*      blob write can NEVER be skipped — that is a type invariant, not a
+*      policy ("skip the blob" does not exist on the interface). The only
+*      switch is the binary `inlineCache: "on" | "off"` constructor option
+*      (mechanism default OFF — unknown callers keep byte-identical
+*      behavior). With `on` (write-through): content ≤ threshold is written
+*      into the index row in the SAME put; over-threshold rows stay NULL and
+*      reads go to objects (NOT an error).
+*      **Read equivalence**: an index-content hit (hash verified) ≡ an
+*      objects read; verification failure falls back to objects (+ repair
+*      log), never surfacing corrupt bytes.
+*    - **Pure derived index** (no object backend): content IS the primary
+*      data; cid is merely a checksum; the authority is the ingested source.
+*      No sync ⇒ every write skips the changelog (enforced by the
+*      constructor, not by call sites) and uses the fixed device sentinel
+*      {@link INGEST_DEVICE_ID}. Over-threshold content is a HARD ERROR
+*      (there is no blob to fall back to).
+*
+* 3. **Projection control** — `listEntries(prefix, { includeContent: true })`;
+*    default OFF: the default SELECT does not touch the content column, so
+*    every existing list path is zero-regression, zero extra bytes.
+*
+* 4. **Two-value threshold** (do not conflate): the app-level
+*    `inlineThreshold` is configurable (default {@link DEFAULT_INLINE_THRESHOLD});
+*    the DDL-level {@link INLINE_CONTENT_HARD_CAP} is a fixed constant baked
+*    into the table CHECK (`CHECK (content IS NULL OR LENGTH(content) <=
+*    <HARD_CAP>)`). A CHECK inside the table schema is not configurable
+*    (SQLite requires a table rebuild to change it) — it is a defensive upper
+*    bound only. Configurability lives ONLY at the app layer; startup asserts
+*    `inlineThreshold <= INLINE_CONTENT_HARD_CAP` via
+*    {@link assertInlineThreshold}.
+*
+* Physical layout is NOT locked by this contract — the conformance suite
+* asserts API behavior only (this plan inlines a column on `entries`; a
+* cid-keyed sibling table would satisfy the same contract).
+*/
+/** DDL-level hard cap for an inline content column, in bytes (fixed constant). */
+const INLINE_CONTENT_HARD_CAP = 64 * 1024;
+/**
+* Default app-level inline threshold, in bytes (configurable per deployment).
+* Mind the two semantics: CAS write-through over-threshold = cache miss
+* (reads fall back to objects); pure derived index over-threshold = HARD
+* ERROR (no blob fallback) — construction sites with bigger payloads pass
+* their own `inlineThreshold`.
+*/
+const DEFAULT_INLINE_THRESHOLD = 2 * 1024;
+/**
+* Fixed `deviceId` sentinel for pure-derived-index writes (`PutOpts.deviceId`
+* is required by the TreeIndex mutation contract, but a derived index has no
+* device — it is rebuilt from source, never synced).
+*/
+const INGEST_DEVICE_ID = "system:ingest";
+/** Normalize constructor options into a validated config (mechanism default OFF). */
+function resolveInlineConfig(opts) {
+	const inlineThreshold = opts?.inlineThreshold ?? DEFAULT_INLINE_THRESHOLD;
+	assertInlineThreshold(inlineThreshold);
+	return {
+		inlineCache: opts?.inlineCache ?? "off",
+		inlineThreshold
+	};
+}
+/** UTF-8 byte length of a string (the threshold/hard-cap unit is bytes). */
+function utf8ByteLength(s) {
+	return new TextEncoder().encode(s).length;
+}
+/**
+* Put-side inline decision shared by all TreeIndex impls.
+*
+* Returns the string to store in the content column, or `null` (store NULL):
+*   - no content supplied / `inlineCache: "off"` → null (legacy behavior)
+*   - content over the threshold → null (CAS semantics: NOT an error — the
+*     object backend is authoritative; pure derived indexes enforce their
+*     hard error one level up, in `VersionedContentIndex`)
+*   - content containing an embedded NUL → null (libsql binds TEXT as a
+*     C string and truncates at the first `\0`, which would break the
+*     read-equivalence invariant; such content stays objects-only —
+*     best-effort semantics make this a legal miss)
+*   - otherwise verify `hash(content) === cid` ONCE at write time; a
+*     mismatched pair is REJECTED (cid-verified contract clause 1).
+*/
+async function resolveInlineContent(entry, config) {
+	if (entry.content === void 0 || config.inlineCache !== "on") return null;
+	if (entry.content.includes("\0")) return null;
+	if (utf8ByteLength(entry.content) > config.inlineThreshold) return null;
+	const actual = await require_cid.computeCID(entry.content);
+	if (actual !== entry.cid) throw new Error(`inline content rejected: hash(content) ${actual} does not match entry cid ${entry.cid}`);
+	return entry.content;
+}
+/**
+* Byte-payload → inline-text candidate for write paths that carry raw bytes
+* (sync/internal writes). Returns the decoded string ONLY when the payload is
+* plausibly inlinable: text mime, within the hard cap, and STRICT UTF-8
+* (fatal decode — a lossy decode would re-encode to different bytes and fail
+* the cid verification anyway). Null = don't offer inline content.
+*/
+function decodeInlineText(bytes, mimeType) {
+	if (bytes.length > INLINE_CONTENT_HARD_CAP) return null;
+	if (!(0, _aigne_afs_provider_utils.isTextMime)(mimeType)) return null;
+	try {
+		return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+	} catch {
+		return null;
+	}
+}
+/**
+* Startup assertion: the configurable app threshold must be a positive
+* integer within the DDL hard cap. Throws on misconfiguration (failing fast
+* beats silently writing rows the CHECK constraint will reject).
+*/
+function assertInlineThreshold(threshold) {
+	if (!Number.isInteger(threshold) || threshold <= 0) throw new Error(`inlineThreshold must be a positive integer, got ${threshold}`);
+	if (threshold > INLINE_CONTENT_HARD_CAP) throw new Error(`inlineThreshold (${threshold}) exceeds the DDL hard cap (${INLINE_CONTENT_HARD_CAP}) — the CHECK constraint would reject inline rows`);
+}
+
+//#endregion
+exports.DEFAULT_INLINE_THRESHOLD = DEFAULT_INLINE_THRESHOLD;
+exports.INGEST_DEVICE_ID = INGEST_DEVICE_ID;
+exports.INLINE_CONTENT_HARD_CAP = INLINE_CONTENT_HARD_CAP;
+exports.assertInlineThreshold = assertInlineThreshold;
+exports.decodeInlineText = decodeInlineText;
+exports.resolveInlineConfig = resolveInlineConfig;
+exports.resolveInlineContent = resolveInlineContent;
+exports.utf8ByteLength = utf8ByteLength;

package/dist/inline-content.d.cts

@@ -0,0 +1,98 @@
+//#region src/inline-content.d.ts
+/**
+ * Inline content — Layer 0 generic TreeIndex capability contract (Phase 0).
+ *
+ * A TreeIndex row may carry a small inline copy of the file's bytes in a
+ * `content` column, eliminating the per-entry object fetch on bulk reads.
+ * Four contract clauses (conformance suite:
+ * `@aigne/afs-testing` → `suites/inline-content.ts`):
+ *
+ * 1. **cid-verified** — whenever `content` is present, `hash(content) === cid`
+ *    holds. The cid is always computed; writes verify once and REJECT a
+ *    mismatched pair. The cid stays the identity; content is just a co-located
+ *    copy of the same bytes — it can never go stale and never breaks any
+ *    cid-addressed mechanism.
+ *
+ * 2. **Two store classes** (statically determined at construction — no runtime
+ *    probing):
+ *    - **CAS store** (object backend present; cid is a public address): the
+ *      blob write can NEVER be skipped — that is a type invariant, not a
+ *      policy ("skip the blob" does not exist on the interface). The only
+ *      switch is the binary `inlineCache: "on" | "off"` constructor option
+ *      (mechanism default OFF — unknown callers keep byte-identical
+ *      behavior). With `on` (write-through): content ≤ threshold is written
+ *      into the index row in the SAME put; over-threshold rows stay NULL and
+ *      reads go to objects (NOT an error).
+ *      **Read equivalence**: an index-content hit (hash verified) ≡ an
+ *      objects read; verification failure falls back to objects (+ repair
+ *      log), never surfacing corrupt bytes.
+ *    - **Pure derived index** (no object backend): content IS the primary
+ *      data; cid is merely a checksum; the authority is the ingested source.
+ *      No sync ⇒ every write skips the changelog (enforced by the
+ *      constructor, not by call sites) and uses the fixed device sentinel
+ *      {@link INGEST_DEVICE_ID}. Over-threshold content is a HARD ERROR
+ *      (there is no blob to fall back to).
+ *
+ * 3. **Projection control** — `listEntries(prefix, { includeContent: true })`;
+ *    default OFF: the default SELECT does not touch the content column, so
+ *    every existing list path is zero-regression, zero extra bytes.
+ *
+ * 4. **Two-value threshold** (do not conflate): the app-level
+ *    `inlineThreshold` is configurable (default {@link DEFAULT_INLINE_THRESHOLD});
+ *    the DDL-level {@link INLINE_CONTENT_HARD_CAP} is a fixed constant baked
+ *    into the table CHECK (`CHECK (content IS NULL OR LENGTH(content) <=
+ *    <HARD_CAP>)`). A CHECK inside the table schema is not configurable
+ *    (SQLite requires a table rebuild to change it) — it is a defensive upper
+ *    bound only. Configurability lives ONLY at the app layer; startup asserts
+ *    `inlineThreshold <= INLINE_CONTENT_HARD_CAP` via
+ *    {@link assertInlineThreshold}.
+ *
+ * Physical layout is NOT locked by this contract — the conformance suite
+ * asserts API behavior only (this plan inlines a column on `entries`; a
+ * cid-keyed sibling table would satisfy the same contract).
+ */
+/** DDL-level hard cap for an inline content column, in bytes (fixed constant). */
+declare const INLINE_CONTENT_HARD_CAP: number;
+/**
+ * Default app-level inline threshold, in bytes (configurable per deployment).
+ * Mind the two semantics: CAS write-through over-threshold = cache miss
+ * (reads fall back to objects); pure derived index over-threshold = HARD
+ * ERROR (no blob fallback) — construction sites with bigger payloads pass
+ * their own `inlineThreshold`.
+ */
+declare const DEFAULT_INLINE_THRESHOLD: number;
+/**
+ * Binary CAS write-through switch. Mechanism default is `"off"`; a store that
+ * wants read acceleration opts in EXPLICITLY at its construction site.
+ */
+type InlineCacheMode = "on" | "off";
+/**
+ * Fixed `deviceId` sentinel for pure-derived-index writes (`PutOpts.deviceId`
+ * is required by the TreeIndex mutation contract, but a derived index has no
+ * device — it is rebuilt from source, never synced).
+ */
+declare const INGEST_DEVICE_ID = "system:ingest";
+/** Construction-time options shared by inline-capable TreeIndex impls. */
+interface InlineContentOptions {
+  /** CAS write-through switch — default `"off"` (no behavior change). */
+  inlineCache?: InlineCacheMode;
+  /** App-level inline threshold in bytes — default {@link DEFAULT_INLINE_THRESHOLD}. */
+  inlineThreshold?: number;
+}
+/**
+ * Byte-payload → inline-text candidate for write paths that carry raw bytes
+ * (sync/internal writes). Returns the decoded string ONLY when the payload is
+ * plausibly inlinable: text mime, within the hard cap, and STRICT UTF-8
+ * (fatal decode — a lossy decode would re-encode to different bytes and fail
+ * the cid verification anyway). Null = don't offer inline content.
+ */
+declare function decodeInlineText(bytes: Uint8Array, mimeType: string | undefined): string | null;
+/**
+ * Startup assertion: the configurable app threshold must be a positive
+ * integer within the DDL hard cap. Throws on misconfiguration (failing fast
+ * beats silently writing rows the CHECK constraint will reject).
+ */
+declare function assertInlineThreshold(threshold: number): void;
+//#endregion
+export { DEFAULT_INLINE_THRESHOLD, INGEST_DEVICE_ID, INLINE_CONTENT_HARD_CAP, InlineCacheMode, InlineContentOptions, assertInlineThreshold, decodeInlineText };
+//# sourceMappingURL=inline-content.d.cts.map

package/dist/inline-content.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inline-content.d.cts","names":[],"sources":["../src/inline-content.ts"],"mappings":";;AAyDA;;;;;AASA;;;;;AAMA;;;;;AAOA;;;;;AAGA;;;;;;;;;AA+DA;;;;;;;;;AAeA;;;;;;;;;;;;;;cAvGa,uBAAA;;;;;;;;cASA,wBAAA;;;;;KAMD,eAAA;;;;;;cAOC,gBAAA;;UAGI,oBAAA;;EAEf,WAAA,GAAc,eAAA;;EAEd,eAAA;AAAA;;;;;;;;iBA2Dc,gBAAA,CAAiB,KAAA,EAAO,UAAA,EAAY,QAAA;;;;;;iBAepC,qBAAA,CAAsB,SAAA"}

package/dist/inline-content.d.mts

@@ -0,0 +1,98 @@
+//#region src/inline-content.d.ts
+/**
+ * Inline content — Layer 0 generic TreeIndex capability contract (Phase 0).
+ *
+ * A TreeIndex row may carry a small inline copy of the file's bytes in a
+ * `content` column, eliminating the per-entry object fetch on bulk reads.
+ * Four contract clauses (conformance suite:
+ * `@aigne/afs-testing` → `suites/inline-content.ts`):
+ *
+ * 1. **cid-verified** — whenever `content` is present, `hash(content) === cid`
+ *    holds. The cid is always computed; writes verify once and REJECT a
+ *    mismatched pair. The cid stays the identity; content is just a co-located
+ *    copy of the same bytes — it can never go stale and never breaks any
+ *    cid-addressed mechanism.
+ *
+ * 2. **Two store classes** (statically determined at construction — no runtime
+ *    probing):
+ *    - **CAS store** (object backend present; cid is a public address): the
+ *      blob write can NEVER be skipped — that is a type invariant, not a
+ *      policy ("skip the blob" does not exist on the interface). The only
+ *      switch is the binary `inlineCache: "on" | "off"` constructor option
+ *      (mechanism default OFF — unknown callers keep byte-identical
+ *      behavior). With `on` (write-through): content ≤ threshold is written
+ *      into the index row in the SAME put; over-threshold rows stay NULL and
+ *      reads go to objects (NOT an error).
+ *      **Read equivalence**: an index-content hit (hash verified) ≡ an
+ *      objects read; verification failure falls back to objects (+ repair
+ *      log), never surfacing corrupt bytes.
+ *    - **Pure derived index** (no object backend): content IS the primary
+ *      data; cid is merely a checksum; the authority is the ingested source.
+ *      No sync ⇒ every write skips the changelog (enforced by the
+ *      constructor, not by call sites) and uses the fixed device sentinel
+ *      {@link INGEST_DEVICE_ID}. Over-threshold content is a HARD ERROR
+ *      (there is no blob to fall back to).
+ *
+ * 3. **Projection control** — `listEntries(prefix, { includeContent: true })`;
+ *    default OFF: the default SELECT does not touch the content column, so
+ *    every existing list path is zero-regression, zero extra bytes.
+ *
+ * 4. **Two-value threshold** (do not conflate): the app-level
+ *    `inlineThreshold` is configurable (default {@link DEFAULT_INLINE_THRESHOLD});
+ *    the DDL-level {@link INLINE_CONTENT_HARD_CAP} is a fixed constant baked
+ *    into the table CHECK (`CHECK (content IS NULL OR LENGTH(content) <=
+ *    <HARD_CAP>)`). A CHECK inside the table schema is not configurable
+ *    (SQLite requires a table rebuild to change it) — it is a defensive upper
+ *    bound only. Configurability lives ONLY at the app layer; startup asserts
+ *    `inlineThreshold <= INLINE_CONTENT_HARD_CAP` via
+ *    {@link assertInlineThreshold}.
+ *
+ * Physical layout is NOT locked by this contract — the conformance suite
+ * asserts API behavior only (this plan inlines a column on `entries`; a
+ * cid-keyed sibling table would satisfy the same contract).
+ */
+/** DDL-level hard cap for an inline content column, in bytes (fixed constant). */
+declare const INLINE_CONTENT_HARD_CAP: number;
+/**
+ * Default app-level inline threshold, in bytes (configurable per deployment).
+ * Mind the two semantics: CAS write-through over-threshold = cache miss
+ * (reads fall back to objects); pure derived index over-threshold = HARD
+ * ERROR (no blob fallback) — construction sites with bigger payloads pass
+ * their own `inlineThreshold`.
+ */
+declare const DEFAULT_INLINE_THRESHOLD: number;
+/**
+ * Binary CAS write-through switch. Mechanism default is `"off"`; a store that
+ * wants read acceleration opts in EXPLICITLY at its construction site.
+ */
+type InlineCacheMode = "on" | "off";
+/**
+ * Fixed `deviceId` sentinel for pure-derived-index writes (`PutOpts.deviceId`
+ * is required by the TreeIndex mutation contract, but a derived index has no
+ * device — it is rebuilt from source, never synced).
+ */
+declare const INGEST_DEVICE_ID = "system:ingest";
+/** Construction-time options shared by inline-capable TreeIndex impls. */
+interface InlineContentOptions {
+  /** CAS write-through switch — default `"off"` (no behavior change). */
+  inlineCache?: InlineCacheMode;
+  /** App-level inline threshold in bytes — default {@link DEFAULT_INLINE_THRESHOLD}. */
+  inlineThreshold?: number;
+}
+/**
+ * Byte-payload → inline-text candidate for write paths that carry raw bytes
+ * (sync/internal writes). Returns the decoded string ONLY when the payload is
+ * plausibly inlinable: text mime, within the hard cap, and STRICT UTF-8
+ * (fatal decode — a lossy decode would re-encode to different bytes and fail
+ * the cid verification anyway). Null = don't offer inline content.
+ */
+declare function decodeInlineText(bytes: Uint8Array, mimeType: string | undefined): string | null;
+/**
+ * Startup assertion: the configurable app threshold must be a positive
+ * integer within the DDL hard cap. Throws on misconfiguration (failing fast
+ * beats silently writing rows the CHECK constraint will reject).
+ */
+declare function assertInlineThreshold(threshold: number): void;
+//#endregion
+export { DEFAULT_INLINE_THRESHOLD, INGEST_DEVICE_ID, INLINE_CONTENT_HARD_CAP, InlineCacheMode, InlineContentOptions, assertInlineThreshold, decodeInlineText };
+//# sourceMappingURL=inline-content.d.mts.map

package/dist/inline-content.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inline-content.d.mts","names":[],"sources":["../src/inline-content.ts"],"mappings":";;AAyDA;;;;;AASA;;;;;AAMA;;;;;AAOA;;;;;AAGA;;;;;;;;;AA+DA;;;;;;;;;AAeA;;;;;;;;;;;;;;cAvGa,uBAAA;;;;;;;;cASA,wBAAA;;;;;KAMD,eAAA;;;;;;cAOC,gBAAA;;UAGI,oBAAA;;EAEf,WAAA,GAAc,eAAA;;EAEd,eAAA;AAAA;;;;;;;;iBA2Dc,gBAAA,CAAiB,KAAA,EAAO,UAAA,EAAY,QAAA;;;;;;iBAepC,qBAAA,CAAsB,SAAA"}

package/dist/inline-content.mjs

@@ -0,0 +1,137 @@
+import { computeCID } from "./cid.mjs";
+import { isTextMime } from "./mime-utils.mjs";
+
+//#region src/inline-content.ts
+/**
+* Inline content — Layer 0 generic TreeIndex capability contract (Phase 0).
+*
+* A TreeIndex row may carry a small inline copy of the file's bytes in a
+* `content` column, eliminating the per-entry object fetch on bulk reads.
+* Four contract clauses (conformance suite:
+* `@aigne/afs-testing` → `suites/inline-content.ts`):
+*
+* 1. **cid-verified** — whenever `content` is present, `hash(content) === cid`
+*    holds. The cid is always computed; writes verify once and REJECT a
+*    mismatched pair. The cid stays the identity; content is just a co-located
+*    copy of the same bytes — it can never go stale and never breaks any
+*    cid-addressed mechanism.
+*
+* 2. **Two store classes** (statically determined at construction — no runtime
+*    probing):
+*    - **CAS store** (object backend present; cid is a public address): the
+*      blob write can NEVER be skipped — that is a type invariant, not a
+*      policy ("skip the blob" does not exist on the interface). The only
+*      switch is the binary `inlineCache: "on" | "off"` constructor option
+*      (mechanism default OFF — unknown callers keep byte-identical
+*      behavior). With `on` (write-through): content ≤ threshold is written
+*      into the index row in the SAME put; over-threshold rows stay NULL and
+*      reads go to objects (NOT an error).
+*      **Read equivalence**: an index-content hit (hash verified) ≡ an
+*      objects read; verification failure falls back to objects (+ repair
+*      log), never surfacing corrupt bytes.
+*    - **Pure derived index** (no object backend): content IS the primary
+*      data; cid is merely a checksum; the authority is the ingested source.
+*      No sync ⇒ every write skips the changelog (enforced by the
+*      constructor, not by call sites) and uses the fixed device sentinel
+*      {@link INGEST_DEVICE_ID}. Over-threshold content is a HARD ERROR
+*      (there is no blob to fall back to).
+*
+* 3. **Projection control** — `listEntries(prefix, { includeContent: true })`;
+*    default OFF: the default SELECT does not touch the content column, so
+*    every existing list path is zero-regression, zero extra bytes.
+*
+* 4. **Two-value threshold** (do not conflate): the app-level
+*    `inlineThreshold` is configurable (default {@link DEFAULT_INLINE_THRESHOLD});
+*    the DDL-level {@link INLINE_CONTENT_HARD_CAP} is a fixed constant baked
+*    into the table CHECK (`CHECK (content IS NULL OR LENGTH(content) <=
+*    <HARD_CAP>)`). A CHECK inside the table schema is not configurable
+*    (SQLite requires a table rebuild to change it) — it is a defensive upper
+*    bound only. Configurability lives ONLY at the app layer; startup asserts
+*    `inlineThreshold <= INLINE_CONTENT_HARD_CAP` via
+*    {@link assertInlineThreshold}.
+*
+* Physical layout is NOT locked by this contract — the conformance suite
+* asserts API behavior only (this plan inlines a column on `entries`; a
+* cid-keyed sibling table would satisfy the same contract).
+*/
+/** DDL-level hard cap for an inline content column, in bytes (fixed constant). */
+const INLINE_CONTENT_HARD_CAP = 64 * 1024;
+/**
+* Default app-level inline threshold, in bytes (configurable per deployment).
+* Mind the two semantics: CAS write-through over-threshold = cache miss
+* (reads fall back to objects); pure derived index over-threshold = HARD
+* ERROR (no blob fallback) — construction sites with bigger payloads pass
+* their own `inlineThreshold`.
+*/
+const DEFAULT_INLINE_THRESHOLD = 2 * 1024;
+/**
+* Fixed `deviceId` sentinel for pure-derived-index writes (`PutOpts.deviceId`
+* is required by the TreeIndex mutation contract, but a derived index has no
+* device — it is rebuilt from source, never synced).
+*/
+const INGEST_DEVICE_ID = "system:ingest";
+/** Normalize constructor options into a validated config (mechanism default OFF). */
+function resolveInlineConfig(opts) {
+	const inlineThreshold = opts?.inlineThreshold ?? DEFAULT_INLINE_THRESHOLD;
+	assertInlineThreshold(inlineThreshold);
+	return {
+		inlineCache: opts?.inlineCache ?? "off",
+		inlineThreshold
+	};
+}
+/** UTF-8 byte length of a string (the threshold/hard-cap unit is bytes). */
+function utf8ByteLength(s) {
+	return new TextEncoder().encode(s).length;
+}
+/**
+* Put-side inline decision shared by all TreeIndex impls.
+*
+* Returns the string to store in the content column, or `null` (store NULL):
+*   - no content supplied / `inlineCache: "off"` → null (legacy behavior)
+*   - content over the threshold → null (CAS semantics: NOT an error — the
+*     object backend is authoritative; pure derived indexes enforce their
+*     hard error one level up, in `VersionedContentIndex`)
+*   - content containing an embedded NUL → null (libsql binds TEXT as a
+*     C string and truncates at the first `\0`, which would break the
+*     read-equivalence invariant; such content stays objects-only —
+*     best-effort semantics make this a legal miss)
+*   - otherwise verify `hash(content) === cid` ONCE at write time; a
+*     mismatched pair is REJECTED (cid-verified contract clause 1).
+*/
+async function resolveInlineContent(entry, config) {
+	if (entry.content === void 0 || config.inlineCache !== "on") return null;
+	if (entry.content.includes("\0")) return null;
+	if (utf8ByteLength(entry.content) > config.inlineThreshold) return null;
+	const actual = await computeCID(entry.content);
+	if (actual !== entry.cid) throw new Error(`inline content rejected: hash(content) ${actual} does not match entry cid ${entry.cid}`);
+	return entry.content;
+}
+/**
+* Byte-payload → inline-text candidate for write paths that carry raw bytes
+* (sync/internal writes). Returns the decoded string ONLY when the payload is
+* plausibly inlinable: text mime, within the hard cap, and STRICT UTF-8
+* (fatal decode — a lossy decode would re-encode to different bytes and fail
+* the cid verification anyway). Null = don't offer inline content.
+*/
+function decodeInlineText(bytes, mimeType) {
+	if (bytes.length > INLINE_CONTENT_HARD_CAP) return null;
+	if (!isTextMime(mimeType)) return null;
+	try {
+		return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+	} catch {
+		return null;
+	}
+}
+/**
+* Startup assertion: the configurable app threshold must be a positive
+* integer within the DDL hard cap. Throws on misconfiguration (failing fast
+* beats silently writing rows the CHECK constraint will reject).
+*/
+function assertInlineThreshold(threshold) {
+	if (!Number.isInteger(threshold) || threshold <= 0) throw new Error(`inlineThreshold must be a positive integer, got ${threshold}`);
+	if (threshold > INLINE_CONTENT_HARD_CAP) throw new Error(`inlineThreshold (${threshold}) exceeds the DDL hard cap (${INLINE_CONTENT_HARD_CAP}) — the CHECK constraint would reject inline rows`);
+}
+
+//#endregion
+export { DEFAULT_INLINE_THRESHOLD, INGEST_DEVICE_ID, INLINE_CONTENT_HARD_CAP, assertInlineThreshold, decodeInlineText, resolveInlineConfig, resolveInlineContent, utf8ByteLength };
+//# sourceMappingURL=inline-content.mjs.map

package/dist/inline-content.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"inline-content.mjs","names":[],"sources":["../src/inline-content.ts"],"sourcesContent":["/**\n * Inline content — Layer 0 generic TreeIndex capability contract (Phase 0).\n *\n * A TreeIndex row may carry a small inline copy of the file's bytes in a\n * `content` column, eliminating the per-entry object fetch on bulk reads.\n * Four contract clauses (conformance suite:\n * `@aigne/afs-testing` → `suites/inline-content.ts`):\n *\n * 1. **cid-verified** — whenever `content` is present, `hash(content) === cid`\n *    holds. The cid is always computed; writes verify once and REJECT a\n *    mismatched pair. The cid stays the identity; content is just a co-located\n *    copy of the same bytes — it can never go stale and never breaks any\n *    cid-addressed mechanism.\n *\n * 2. **Two store classes** (statically determined at construction — no runtime\n *    probing):\n *    - **CAS store** (object backend present; cid is a public address): the\n *      blob write can NEVER be skipped — that is a type invariant, not a\n *      policy (\"skip the blob\" does not exist on the interface). The only\n *      switch is the binary `inlineCache: \"on\" | \"off\"` constructor option\n *      (mechanism default OFF — unknown callers keep byte-identical\n *      behavior). With `on` (write-through): content ≤ threshold is written\n *      into the index row in the SAME put; over-threshold rows stay NULL and\n *      reads go to objects (NOT an error).\n *      **Read equivalence**: an index-content hit (hash verified) ≡ an\n *      objects read; verification failure falls back to objects (+ repair\n *      log), never surfacing corrupt bytes.\n *    - **Pure derived index** (no object backend): content IS the primary\n *      data; cid is merely a checksum; the authority is the ingested source.\n *      No sync ⇒ every write skips the changelog (enforced by the\n *      constructor, not by call sites) and uses the fixed device sentinel\n *      {@link INGEST_DEVICE_ID}. Over-threshold content is a HARD ERROR\n *      (there is no blob to fall back to).\n *\n * 3. **Projection control** — `listEntries(prefix, { includeContent: true })`;\n *    default OFF: the default SELECT does not touch the content column, so\n *    every existing list path is zero-regression, zero extra bytes.\n *\n * 4. **Two-value threshold** (do not conflate): the app-level\n *    `inlineThreshold` is configurable (default {@link DEFAULT_INLINE_THRESHOLD});\n *    the DDL-level {@link INLINE_CONTENT_HARD_CAP} is a fixed constant baked\n *    into the table CHECK (`CHECK (content IS NULL OR LENGTH(content) <=\n *    <HARD_CAP>)`). A CHECK inside the table schema is not configurable\n *    (SQLite requires a table rebuild to change it) — it is a defensive upper\n *    bound only. Configurability lives ONLY at the app layer; startup asserts\n *    `inlineThreshold <= INLINE_CONTENT_HARD_CAP` via\n *    {@link assertInlineThreshold}.\n *\n * Physical layout is NOT locked by this contract — the conformance suite\n * asserts API behavior only (this plan inlines a column on `entries`; a\n * cid-keyed sibling table would satisfy the same contract).\n */\n\nimport { computeCID } from \"./cid.js\";\nimport { isTextMime } from \"./mime-utils.js\";\n\n/** DDL-level hard cap for an inline content column, in bytes (fixed constant). */\nexport const INLINE_CONTENT_HARD_CAP = 64 * 1024;\n\n/**\n * Default app-level inline threshold, in bytes (configurable per deployment).\n * Mind the two semantics: CAS write-through over-threshold = cache miss\n * (reads fall back to objects); pure derived index over-threshold = HARD\n * ERROR (no blob fallback) — construction sites with bigger payloads pass\n * their own `inlineThreshold`.\n */\nexport const DEFAULT_INLINE_THRESHOLD = 2 * 1024;\n\n/**\n * Binary CAS write-through switch. Mechanism default is `\"off\"`; a store that\n * wants read acceleration opts in EXPLICITLY at its construction site.\n */\nexport type InlineCacheMode = \"on\" | \"off\";\n\n/**\n * Fixed `deviceId` sentinel for pure-derived-index writes (`PutOpts.deviceId`\n * is required by the TreeIndex mutation contract, but a derived index has no\n * device — it is rebuilt from source, never synced).\n */\nexport const INGEST_DEVICE_ID = \"system:ingest\";\n\n/** Construction-time options shared by inline-capable TreeIndex impls. */\nexport interface InlineContentOptions {\n  /** CAS write-through switch — default `\"off\"` (no behavior change). */\n  inlineCache?: InlineCacheMode;\n  /** App-level inline threshold in bytes — default {@link DEFAULT_INLINE_THRESHOLD}. */\n  inlineThreshold?: number;\n}\n\n/** Resolved (defaulted + validated) inline configuration of a TreeIndex impl. */\nexport interface ResolvedInlineConfig {\n  inlineCache: InlineCacheMode;\n  inlineThreshold: number;\n}\n\n/** Normalize constructor options into a validated config (mechanism default OFF). */\nexport function resolveInlineConfig(opts?: InlineContentOptions): ResolvedInlineConfig {\n  const inlineThreshold = opts?.inlineThreshold ?? DEFAULT_INLINE_THRESHOLD;\n  assertInlineThreshold(inlineThreshold);\n  return { inlineCache: opts?.inlineCache ?? \"off\", inlineThreshold };\n}\n\n/** UTF-8 byte length of a string (the threshold/hard-cap unit is bytes). */\nexport function utf8ByteLength(s: string): number {\n  return new TextEncoder().encode(s).length;\n}\n\n/**\n * Put-side inline decision shared by all TreeIndex impls.\n *\n * Returns the string to store in the content column, or `null` (store NULL):\n *   - no content supplied / `inlineCache: \"off\"` → null (legacy behavior)\n *   - content over the threshold → null (CAS semantics: NOT an error — the\n *     object backend is authoritative; pure derived indexes enforce their\n *     hard error one level up, in `VersionedContentIndex`)\n *   - content containing an embedded NUL → null (libsql binds TEXT as a\n *     C string and truncates at the first `\\0`, which would break the\n *     read-equivalence invariant; such content stays objects-only —\n *     best-effort semantics make this a legal miss)\n *   - otherwise verify `hash(content) === cid` ONCE at write time; a\n *     mismatched pair is REJECTED (cid-verified contract clause 1).\n */\nexport async function resolveInlineContent(\n  entry: { cid: string; content?: string },\n  config: ResolvedInlineConfig,\n): Promise<string | null> {\n  if (entry.content === undefined || config.inlineCache !== \"on\") return null;\n  if (entry.content.includes(\"\\0\")) return null;\n  if (utf8ByteLength(entry.content) > config.inlineThreshold) return null;\n  const actual = await computeCID(entry.content);\n  if (actual !== entry.cid) {\n    throw new Error(\n      `inline content rejected: hash(content) ${actual} does not match entry cid ${entry.cid}`,\n    );\n  }\n  return entry.content;\n}\n\n/**\n * Byte-payload → inline-text candidate for write paths that carry raw bytes\n * (sync/internal writes). Returns the decoded string ONLY when the payload is\n * plausibly inlinable: text mime, within the hard cap, and STRICT UTF-8\n * (fatal decode — a lossy decode would re-encode to different bytes and fail\n * the cid verification anyway). Null = don't offer inline content.\n */\nexport function decodeInlineText(bytes: Uint8Array, mimeType: string | undefined): string | null {\n  if (bytes.length > INLINE_CONTENT_HARD_CAP) return null;\n  if (!isTextMime(mimeType)) return null;\n  try {\n    return new TextDecoder(\"utf-8\", { fatal: true }).decode(bytes);\n  } catch {\n    return null;\n  }\n}\n\n/**\n * Startup assertion: the configurable app threshold must be a positive\n * integer within the DDL hard cap. Throws on misconfiguration (failing fast\n * beats silently writing rows the CHECK constraint will reject).\n */\nexport function assertInlineThreshold(threshold: number): void {\n  if (!Number.isInteger(threshold) || threshold <= 0) {\n    throw new Error(`inlineThreshold must be a positive integer, got ${threshold}`);\n  }\n  if (threshold > INLINE_CONTENT_HARD_CAP) {\n    throw new Error(\n      `inlineThreshold (${threshold}) exceeds the DDL hard cap (${INLINE_CONTENT_HARD_CAP}) — the CHECK constraint would reject inline rows`,\n    );\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyDA,MAAa,0BAA0B,KAAK;;;;;;;;AAS5C,MAAa,2BAA2B,IAAI;;;;;;AAa5C,MAAa,mBAAmB;;AAiBhC,SAAgB,oBAAoB,MAAmD;CACrF,MAAM,kBAAkB,MAAM,mBAAmB;AACjD,uBAAsB,gBAAgB;AACtC,QAAO;EAAE,aAAa,MAAM,eAAe;EAAO;EAAiB;;;AAIrE,SAAgB,eAAe,GAAmB;AAChD,QAAO,IAAI,aAAa,CAAC,OAAO,EAAE,CAAC;;;;;;;;;;;;;;;;;AAkBrC,eAAsB,qBACpB,OACA,QACwB;AACxB,KAAI,MAAM,YAAY,UAAa,OAAO,gBAAgB,KAAM,QAAO;AACvE,KAAI,MAAM,QAAQ,SAAS,KAAK,CAAE,QAAO;AACzC,KAAI,eAAe,MAAM,QAAQ,GAAG,OAAO,gBAAiB,QAAO;CACnE,MAAM,SAAS,MAAM,WAAW,MAAM,QAAQ;AAC9C,KAAI,WAAW,MAAM,IACnB,OAAM,IAAI,MACR,0CAA0C,OAAO,4BAA4B,MAAM,MACpF;AAEH,QAAO,MAAM;;;;;;;;;AAUf,SAAgB,iBAAiB,OAAmB,UAA6C;AAC/F,KAAI,MAAM,SAAS,wBAAyB,QAAO;AACnD,KAAI,CAAC,WAAW,SAAS,CAAE,QAAO;AAClC,KAAI;AACF,SAAO,IAAI,YAAY,SAAS,EAAE,OAAO,MAAM,CAAC,CAAC,OAAO,MAAM;SACxD;AACN,SAAO;;;;;;;;AASX,SAAgB,sBAAsB,WAAyB;AAC7D,KAAI,CAAC,OAAO,UAAU,UAAU,IAAI,aAAa,EAC/C,OAAM,IAAI,MAAM,mDAAmD,YAAY;AAEjF,KAAI,YAAY,wBACd,OAAM,IAAI,MACR,oBAAoB,UAAU,8BAA8B,wBAAwB,mDACrF"}