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

package/dist/versioned-content-index.mjs

@@ -0,0 +1,103 @@
+import { computeCID } from "./cid.mjs";
+import { DEFAULT_INLINE_THRESHOLD, INGEST_DEVICE_ID, assertInlineThreshold, utf8ByteLength } from "./inline-content.mjs";
+
+//#region src/versioned-content-index.ts
+/**
+* VersionedContentIndex — a PURE DERIVED INDEX over a TreeIndex (Layer 1
+* machinery; contract in `inline-content.ts` clause 2b + `versioned-scope.ts`).
+*
+* NOT a CAS store: there is no object backend; the inline `content` column IS
+* the primary data and the cid is merely a checksum. The authority is the
+* ingested source (a package's immutable, per-version content) — rebuilding
+* from source is always possible, so:
+*
+*   - writes NEVER touch the changelog (`skipChangelog: true`, enforced HERE,
+*     not at call sites — a derived index has nothing to sync);
+*   - `deviceId` is the fixed sentinel {@link INGEST_DEVICE_ID};
+*   - content is REQUIRED on every write, and content over the threshold is
+*     a HARD ERROR (there is no blob to fall back to);
+*   - the wrapped index MUST be constructed with `inlineCache: "on"` and the
+*     same threshold — the first write VERIFIES the content actually landed
+*     inline and fails loudly on a misconfigured store.
+*
+* Kind-agnostic: this class never interprets what it stores. Consumers pick a
+* scope key via `versionedScope(kind, packageId, versionToken)` and bind the
+* wrapped TreeIndex to that scope; ingest/stale/cleanup live one level up.
+*/
+var VersionedContentIndex = class {
+	index;
+	inlineThreshold;
+	/** First successful write verifies the wrapped index actually inlines. */
+	verifiedInline = false;
+	constructor(opts) {
+		this.index = opts.index;
+		this.inlineThreshold = opts.inlineThreshold ?? DEFAULT_INLINE_THRESHOLD;
+		assertInlineThreshold(this.inlineThreshold);
+	}
+	/** Write one file (idempotent upsert by path). */
+	async put(file, mtime = 0) {
+		await this.putBatch([file], mtime);
+	}
+	/**
+	* Write a batch of files (idempotent upsert by path). Enforces the derived-
+	* index invariants: content required, over-threshold hard error, changelog
+	* skipped, ingest device sentinel.
+	*/
+	async putBatch(files, mtime = 0) {
+		if (files.length === 0) return;
+		const entries = [];
+		for (const file of files) {
+			if (typeof file.content !== "string") throw new Error(`VersionedContentIndex: content is required for "${file.path}"`);
+			if (file.content.includes("\0")) throw new Error(`VersionedContentIndex: "${file.path}" contains an embedded NUL — not storable as derived text content`);
+			const bytes = utf8ByteLength(file.content);
+			if (bytes > this.inlineThreshold) throw new Error(`VersionedContentIndex: "${file.path}" is ${bytes} bytes — over the ${this.inlineThreshold}-byte inline threshold (a derived index has no blob fallback; raise the threshold or shrink the source)`);
+			const cid = await computeCID(file.content);
+			entries.push({
+				path: file.path,
+				entry: {
+					cid,
+					size: bytes,
+					mtime,
+					ctime: mtime,
+					mimeType: file.mimeType,
+					content: file.content
+				}
+			});
+		}
+		await this.index.putBatch(entries, {
+			deviceId: INGEST_DEVICE_ID,
+			skipChangelog: true
+		});
+		if (!this.verifiedInline) {
+			const probe = entries[0];
+			if ((await this.index.get(probe.path))?.content !== probe.entry.content) throw new Error("VersionedContentIndex: wrapped index did not store inline content — construct it with inlineCache: \"on\" and a matching threshold");
+			this.verifiedInline = true;
+		}
+	}
+	/** Read one file's content (null when absent). */
+	async get(path) {
+		return (await this.index.get(path))?.content ?? null;
+	}
+	/** Bulk read — one query, content included. */
+	async listEntries(prefix = "", limit = 1e3) {
+		return this.index.listEntries(prefix, {
+			includeContent: true,
+			limit
+		});
+	}
+	/** Does this scope hold any content? */
+	async hasContent() {
+		return this.index.hasChildren("");
+	}
+	/** Drop every row in the scope (version cleanup = one DELETE). */
+	async deleteAll() {
+		return this.index.deleteByPrefix("", {
+			deviceId: INGEST_DEVICE_ID,
+			skipChangelog: true
+		});
+	}
+};
+
+//#endregion
+export { VersionedContentIndex };
+//# sourceMappingURL=versioned-content-index.mjs.map

package/dist/versioned-content-index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"versioned-content-index.mjs","names":[],"sources":["../src/versioned-content-index.ts"],"sourcesContent":["/**\n * VersionedContentIndex — a PURE DERIVED INDEX over a TreeIndex (Layer 1\n * machinery; contract in `inline-content.ts` clause 2b + `versioned-scope.ts`).\n *\n * NOT a CAS store: there is no object backend; the inline `content` column IS\n * the primary data and the cid is merely a checksum. The authority is the\n * ingested source (a package's immutable, per-version content) — rebuilding\n * from source is always possible, so:\n *\n *   - writes NEVER touch the changelog (`skipChangelog: true`, enforced HERE,\n *     not at call sites — a derived index has nothing to sync);\n *   - `deviceId` is the fixed sentinel {@link INGEST_DEVICE_ID};\n *   - content is REQUIRED on every write, and content over the threshold is\n *     a HARD ERROR (there is no blob to fall back to);\n *   - the wrapped index MUST be constructed with `inlineCache: \"on\"` and the\n *     same threshold — the first write VERIFIES the content actually landed\n *     inline and fails loudly on a misconfigured store.\n *\n * Kind-agnostic: this class never interprets what it stores. Consumers pick a\n * scope key via `versionedScope(kind, packageId, versionToken)` and bind the\n * wrapped TreeIndex to that scope; ingest/stale/cleanup live one level up.\n */\n\nimport { computeCID } from \"./cid.js\";\nimport {\n  assertInlineThreshold,\n  DEFAULT_INLINE_THRESHOLD,\n  INGEST_DEVICE_ID,\n  utf8ByteLength,\n} from \"./inline-content.js\";\nimport type { TreeEntry, TreeIndex, TreeIndexListEntriesResult } from \"./tree-index.js\";\n\nexport interface VersionedContentFile {\n  /** Index-relative path (e.g. `general/title.json`). */\n  path: string;\n  /** Primary data — required (this store has no other copy). */\n  content: string;\n  mimeType?: string;\n}\n\nexport interface VersionedContentIndexOptions {\n  /**\n   * Scope-bound TreeIndex over the shared store. MUST be constructed with\n   * `inlineCache: \"on\"` and a threshold ≥ this index's threshold (verified on\n   * first write).\n   */\n  index: TreeIndex;\n  /** Max bytes per file — over it is a HARD ERROR. Default 4KB. */\n  inlineThreshold?: number;\n}\n\nexport class VersionedContentIndex {\n  private readonly index: TreeIndex;\n  private readonly inlineThreshold: number;\n  /** First successful write verifies the wrapped index actually inlines. */\n  private verifiedInline = false;\n\n  constructor(opts: VersionedContentIndexOptions) {\n    this.index = opts.index;\n    this.inlineThreshold = opts.inlineThreshold ?? DEFAULT_INLINE_THRESHOLD;\n    assertInlineThreshold(this.inlineThreshold);\n  }\n\n  /** Write one file (idempotent upsert by path). */\n  async put(file: VersionedContentFile, mtime = 0): Promise<void> {\n    await this.putBatch([file], mtime);\n  }\n\n  /**\n   * Write a batch of files (idempotent upsert by path). Enforces the derived-\n   * index invariants: content required, over-threshold hard error, changelog\n   * skipped, ingest device sentinel.\n   */\n  async putBatch(files: readonly VersionedContentFile[], mtime = 0): Promise<void> {\n    if (files.length === 0) return;\n    const entries: Array<{ path: string; entry: TreeEntry }> = [];\n    for (const file of files) {\n      if (typeof file.content !== \"string\") {\n        throw new Error(`VersionedContentIndex: content is required for \"${file.path}\"`);\n      }\n      if (file.content.includes(\"\\0\")) {\n        // No blob fallback exists here — and TEXT storage cannot hold an\n        // embedded NUL faithfully (see inline-content.ts). Sources are\n        // structured text (JSON/YAML), which never contains a raw NUL.\n        throw new Error(\n          `VersionedContentIndex: \"${file.path}\" contains an embedded NUL — not storable as derived text content`,\n        );\n      }\n      const bytes = utf8ByteLength(file.content);\n      if (bytes > this.inlineThreshold) {\n        throw new Error(\n          `VersionedContentIndex: \"${file.path}\" is ${bytes} bytes — over the ${this.inlineThreshold}-byte inline threshold (a derived index has no blob fallback; raise the threshold or shrink the source)`,\n        );\n      }\n      const cid = await computeCID(file.content);\n      entries.push({\n        path: file.path,\n        entry: {\n          cid,\n          size: bytes,\n          mtime,\n          ctime: mtime,\n          mimeType: file.mimeType,\n          content: file.content,\n        },\n      });\n    }\n    await this.index.putBatch(entries, { deviceId: INGEST_DEVICE_ID, skipChangelog: true });\n\n    if (!this.verifiedInline) {\n      // Loud-failure guard: a wrapped index without `inlineCache: \"on\"` would\n      // silently drop the primary data. Verify the first write round-trips.\n      const probe = entries[0]!;\n      const back = await this.index.get(probe.path);\n      if (back?.content !== probe.entry.content) {\n        throw new Error(\n          'VersionedContentIndex: wrapped index did not store inline content — construct it with inlineCache: \"on\" and a matching threshold',\n        );\n      }\n      this.verifiedInline = true;\n    }\n  }\n\n  /** Read one file's content (null when absent). */\n  async get(path: string): Promise<string | null> {\n    const entry = await this.index.get(path);\n    return entry?.content ?? null;\n  }\n\n  /** Bulk read — one query, content included. */\n  async listEntries(prefix = \"\", limit = 1000): Promise<TreeIndexListEntriesResult> {\n    return this.index.listEntries(prefix, { includeContent: true, limit });\n  }\n\n  /** Does this scope hold any content? */\n  async hasContent(): Promise<boolean> {\n    return this.index.hasChildren(\"\");\n  }\n\n  /** Drop every row in the scope (version cleanup = one DELETE). */\n  async deleteAll(): Promise<number> {\n    return this.index.deleteByPrefix(\"\", { deviceId: INGEST_DEVICE_ID, skipChangelog: true });\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AAmDA,IAAa,wBAAb,MAAmC;CACjC,AAAiB;CACjB,AAAiB;;CAEjB,AAAQ,iBAAiB;CAEzB,YAAY,MAAoC;AAC9C,OAAK,QAAQ,KAAK;AAClB,OAAK,kBAAkB,KAAK,mBAAmB;AAC/C,wBAAsB,KAAK,gBAAgB;;;CAI7C,MAAM,IAAI,MAA4B,QAAQ,GAAkB;AAC9D,QAAM,KAAK,SAAS,CAAC,KAAK,EAAE,MAAM;;;;;;;CAQpC,MAAM,SAAS,OAAwC,QAAQ,GAAkB;AAC/E,MAAI,MAAM,WAAW,EAAG;EACxB,MAAM,UAAqD,EAAE;AAC7D,OAAK,MAAM,QAAQ,OAAO;AACxB,OAAI,OAAO,KAAK,YAAY,SAC1B,OAAM,IAAI,MAAM,mDAAmD,KAAK,KAAK,GAAG;AAElF,OAAI,KAAK,QAAQ,SAAS,KAAK,CAI7B,OAAM,IAAI,MACR,2BAA2B,KAAK,KAAK,mEACtC;GAEH,MAAM,QAAQ,eAAe,KAAK,QAAQ;AAC1C,OAAI,QAAQ,KAAK,gBACf,OAAM,IAAI,MACR,2BAA2B,KAAK,KAAK,OAAO,MAAM,oBAAoB,KAAK,gBAAgB,yGAC5F;GAEH,MAAM,MAAM,MAAM,WAAW,KAAK,QAAQ;AAC1C,WAAQ,KAAK;IACX,MAAM,KAAK;IACX,OAAO;KACL;KACA,MAAM;KACN;KACA,OAAO;KACP,UAAU,KAAK;KACf,SAAS,KAAK;KACf;IACF,CAAC;;AAEJ,QAAM,KAAK,MAAM,SAAS,SAAS;GAAE,UAAU;GAAkB,eAAe;GAAM,CAAC;AAEvF,MAAI,CAAC,KAAK,gBAAgB;GAGxB,MAAM,QAAQ,QAAQ;AAEtB,QADa,MAAM,KAAK,MAAM,IAAI,MAAM,KAAK,GACnC,YAAY,MAAM,MAAM,QAChC,OAAM,IAAI,MACR,qIACD;AAEH,QAAK,iBAAiB;;;;CAK1B,MAAM,IAAI,MAAsC;AAE9C,UADc,MAAM,KAAK,MAAM,IAAI,KAAK,GAC1B,WAAW;;;CAI3B,MAAM,YAAY,SAAS,IAAI,QAAQ,KAA2C;AAChF,SAAO,KAAK,MAAM,YAAY,QAAQ;GAAE,gBAAgB;GAAM;GAAO,CAAC;;;CAIxE,MAAM,aAA+B;AACnC,SAAO,KAAK,MAAM,YAAY,GAAG;;;CAInC,MAAM,YAA6B;AACjC,SAAO,KAAK,MAAM,eAAe,IAAI;GAAE,UAAU;GAAkB,eAAe;GAAM,CAAC"}

package/dist/versioned-content-store.cjs

@@ -0,0 +1,121 @@
+const require_inline_content = require('./inline-content.cjs');
+const require_versioned_content_index = require('./versioned-content-index.cjs');
+
+//#region src/versioned-content-store.ts
+/**
+* VersionedContentStore — multi-scope manager over {@link VersionedContentIndex}
+* (Layer 1 machinery: versioned package-content materialization).
+*
+* One store instance manages MANY scopes (`<kind>:<packageId>:<versionToken>`,
+* see `versioned-scope.ts`) inside ONE shared database — Node: a daemon-level
+* SQLite file; CF: the shared D1 binding; tests: in-memory. The machinery is
+* KIND-AGNOSTIC: scope and group are opaque keys; consumers map their source
+* content (via AFS) into `VersionedContentFile[]` and never touch the DB.
+*
+* Ingest contract (idempotent, lazily triggered):
+*   - `ensure(scope)` is a HIT when the scope's metadata row exists (and, when
+*     digest verification is requested, the stored digest matches) — zero
+*     source I/O on the hot path.
+*   - a MISS loads the source files, upserts every row, THEN writes the
+*     metadata row — the metadata row is the completion marker, so a crash
+*     mid-ingest leaves no readable half-scope (next access rebuilds).
+*   - concurrent first-miss within one process is memoized (single build);
+*     cross-process double builds are harmless (pure upserts + idempotent
+*     marker).
+*   - building a scope DELETES sibling scopes of the same `group` (an opaque
+*     `<kind>:<packageId>` prefix key) — version cleanup is one DELETE per
+*     stale scope, no blob GC involved (content is inline, rows ARE the data).
+*   - `seedDigest` lives in the metadata row, NEVER in the key — dev-mode
+*     stale detection compares digests; prod looks up by exact key only.
+*/
+var VersionedContentStore = class {
+	backend;
+	inlineThreshold;
+	log;
+	/** In-process single-flight per scope (concurrent first-miss → one build). */
+	inflight = /* @__PURE__ */ new Map();
+	constructor(opts) {
+		this.backend = opts.backend;
+		this.inlineThreshold = opts.inlineThreshold ?? require_inline_content.DEFAULT_INLINE_THRESHOLD;
+		require_inline_content.assertInlineThreshold(this.inlineThreshold);
+		this.log = opts.log ?? (() => {});
+	}
+	/** Materialize a scope if needed. See {@link EnsureScopeOptions}. */
+	async ensure(opts) {
+		const existing = this.inflight.get(opts.scope);
+		if (existing) return existing;
+		const run = this.ensureInner(opts).finally(() => {
+			this.inflight.delete(opts.scope);
+		});
+		this.inflight.set(opts.scope, run);
+		return run;
+	}
+	async ensureInner(opts) {
+		if (!opts.force) {
+			const meta = await this.backend.getScopeMeta(opts.scope);
+			if (meta) {
+				if (!(opts.verifyDigest && opts.seedDigest !== void 0 && meta.seedDigest !== opts.seedDigest)) return {
+					built: false,
+					fileCount: meta.fileCount
+				};
+				this.log(`[versioned-content] stale digest for ${opts.scope} (${meta.seedDigest} → ${opts.seedDigest}) — rebuilding`);
+			}
+		}
+		return this.build(opts);
+	}
+	async build(opts) {
+		const loaded = await opts.load();
+		const files = Array.isArray(loaded) ? loaded : loaded.files;
+		const loadedDigest = Array.isArray(loaded) ? void 0 : loaded.seedDigest;
+		const index = new require_versioned_content_index.VersionedContentIndex({
+			index: this.backend.makeIndex(opts.scope),
+			inlineThreshold: this.inlineThreshold
+		});
+		await index.deleteAll();
+		if (files.length > 0) await index.putBatch(files);
+		await this.backend.putScopeMeta({
+			scope: opts.scope,
+			scopeGroup: opts.group,
+			seedDigest: opts.seedDigest ?? loadedDigest,
+			ingestedAt: Date.now(),
+			fileCount: files.length
+		});
+		this.log(`[versioned-content] built scope ${opts.scope} (${files.length} files)`);
+		const siblings = await this.backend.listScopeMetaByGroup(opts.group);
+		for (const sibling of siblings) {
+			if (sibling.scope === opts.scope) continue;
+			await this.deleteScope(sibling.scope);
+			this.log(`[versioned-content] deleted superseded scope ${sibling.scope}`);
+		}
+		return {
+			built: true,
+			fileCount: files.length
+		};
+	}
+	/** Is the scope fully materialized (completion marker present)? */
+	async hasScope(scope) {
+		return await this.backend.getScopeMeta(scope) !== null;
+	}
+	/** One-query bulk read of a scope's content. */
+	async listEntries(scope, prefix = "") {
+		return this.backend.makeIndex(scope).listEntries(prefix, {
+			includeContent: true,
+			limit: 1e3
+		});
+	}
+	/** Single-file read (null when absent). */
+	async get(scope, path) {
+		return (await this.backend.makeIndex(scope).get(path))?.content ?? null;
+	}
+	/** Drop a scope entirely (entries + marker). */
+	async deleteScope(scope) {
+		await this.backend.deleteScopeMeta(scope);
+		await this.backend.makeIndex(scope).deleteByPrefix("", {
+			deviceId: require_inline_content.INGEST_DEVICE_ID,
+			skipChangelog: true
+		});
+	}
+};
+
+//#endregion
+exports.VersionedContentStore = VersionedContentStore;

package/dist/versioned-content-store.d.cts

@@ -0,0 +1,90 @@
+import { TreeIndex, TreeIndexListEntriesResult } from "./tree-index.cjs";
+import { VersionedContentFile } from "./versioned-content-index.cjs";
+
+//#region src/versioned-content-store.d.ts
+/** Metadata row for one materialized scope (the completion marker). */
+interface VersionedScopeMeta {
+  scope: string;
+  /** Opaque grouping key (same package, any version) for cleanup. */
+  scopeGroup: string;
+  /** Source-content fingerprint (dev-mode stale detection). */
+  seedDigest?: string;
+  ingestedAt: number;
+  fileCount: number;
+}
+/**
+ * Storage backend: binds scopes to TreeIndex instances over the shared DB and
+ * owns the scope-metadata table. Implementations are thin (entries machinery
+ * is the TreeIndex itself).
+ */
+interface VersionedScopeBackend {
+  /** A TreeIndex bound to `scope`, constructed with `inlineCache: "on"`. */
+  makeIndex(scope: string): TreeIndex;
+  getScopeMeta(scope: string): Promise<VersionedScopeMeta | null>;
+  putScopeMeta(meta: VersionedScopeMeta): Promise<void>;
+  deleteScopeMeta(scope: string): Promise<void>;
+  /** Every metadata row in `scopeGroup` (for sibling-version cleanup). */
+  listScopeMetaByGroup(scopeGroup: string): Promise<VersionedScopeMeta[]>;
+}
+/** `load()` result — either bare files or files + their freshly-computed digest. */
+type LoadedScopeContent = VersionedContentFile[] | {
+  files: VersionedContentFile[];
+  seedDigest?: string;
+};
+interface EnsureScopeOptions {
+  /** Exact scope key (`versionedScope(kind, id, token)`). */
+  scope: string;
+  /** Opaque group key — same package across versions (cleanup unit). */
+  group: string;
+  /**
+   * Load the source files (called ONLY on a miss/rebuild). May return a
+   * digest computed from the loaded bytes — stored in the metadata row so the
+   * prod hot path never recomputes it (`seedDigest` 仅在 ingest 时计算).
+   */
+  load: () => Promise<LoadedScopeContent>;
+  /**
+   * Source fingerprint. When supplied WITH `verifyDigest`, a metadata row
+   * whose digest differs triggers a rebuild (dev-mode stale defense). Stored
+   * in the metadata row either way.
+   */
+  seedDigest?: string;
+  /** Compare digests on hit (dev mode). Default false — prod trusts the key. */
+  verifyDigest?: boolean;
+  /** Force a rebuild regardless of the marker (dev "don't trust the cache"). */
+  force?: boolean;
+}
+interface EnsureScopeResult {
+  /** True when this call performed the build (miss/stale/forced). */
+  built: boolean;
+  fileCount: number;
+}
+interface VersionedContentStoreOptions {
+  backend: VersionedScopeBackend;
+  /** Per-file inline ceiling — over it ingest HARD-FAILS. Default 4KB. */
+  inlineThreshold?: number;
+  /** Build/cleanup observability (daemon log). Default: silent. */
+  log?: (line: string) => void;
+}
+declare class VersionedContentStore {
+  private readonly backend;
+  private readonly inlineThreshold;
+  private readonly log;
+  /** In-process single-flight per scope (concurrent first-miss → one build). */
+  private readonly inflight;
+  constructor(opts: VersionedContentStoreOptions);
+  /** Materialize a scope if needed. See {@link EnsureScopeOptions}. */
+  ensure(opts: EnsureScopeOptions): Promise<EnsureScopeResult>;
+  private ensureInner;
+  private build;
+  /** Is the scope fully materialized (completion marker present)? */
+  hasScope(scope: string): Promise<boolean>;
+  /** One-query bulk read of a scope's content. */
+  listEntries(scope: string, prefix?: string): Promise<TreeIndexListEntriesResult>;
+  /** Single-file read (null when absent). */
+  get(scope: string, path: string): Promise<string | null>;
+  /** Drop a scope entirely (entries + marker). */
+  deleteScope(scope: string): Promise<void>;
+}
+//#endregion
+export { EnsureScopeOptions, EnsureScopeResult, LoadedScopeContent, VersionedContentStore, VersionedContentStoreOptions, VersionedScopeBackend, VersionedScopeMeta };
+//# sourceMappingURL=versioned-content-store.d.cts.map

package/dist/versioned-content-store.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"versioned-content-store.d.cts","names":[],"sources":["../src/versioned-content-store.ts"],"mappings":";;;;;UAoCiB,kBAAA;EACf,KAAA;EAiBA;EAfA,UAAA;EAe6B;EAb7B,UAAA;EACA,UAAA;EACA,SAAA;AAAA;;;;;;UAQe,qBAAA;EAO2B;EAL1C,SAAA,CAAU,KAAA,WAAgB,SAAA;EAC1B,YAAA,CAAa,KAAA,WAAgB,OAAA,CAAQ,kBAAA;EACrC,YAAA,CAAa,IAAA,EAAM,kBAAA,GAAqB,OAAA;EACxC,eAAA,CAAgB,KAAA,WAAgB,OAAA;EAMJ;EAJ5B,oBAAA,CAAqB,UAAA,WAAqB,OAAA,CAAQ,kBAAA;AAAA;;KAIxC,kBAAA,GACR,oBAAA;EACE,KAAA,EAAO,oBAAA;EAAwB,UAAA;AAAA;AAAA,UAEpB,kBAAA;EAAA;EAEf,KAAA;;EAEA,KAAA;EAFA;;;;;EAQA,IAAA,QAAY,OAAA,CAAQ,kBAAA;EAQpB;;;;AAKF;EAPE,UAAA;;EAEA,YAAA;EAQS;EANT,KAAA;AAAA;AAAA,UAGe,iBAAA;EAOe;EAL9B,KAAA;EACA,SAAA;AAAA;AAAA,UAGe,4BAAA;EACf,OAAA,EAAS,qBAAA;EAIU;EAFnB,eAAA;EAKW;EAHX,GAAA,IAAO,IAAA;AAAA;AAAA,cAGI,qBAAA;EAAA,iBACM,OAAA;EAAA,iBACA,eAAA;EAAA,iBACA,GAAA;EAyEc;EAAA,iBAvEd,QAAA;cAEL,IAAA,EAAM,4BAAA;EAkFsB;EA1ElC,MAAA,CAAO,IAAA,EAAM,kBAAA,GAAqB,OAAA,CAAQ,iBAAA;EAAA,QAWlC,WAAA;EAAA,QAeA,KAAA;EAxCG;EA2EX,QAAA,CAAS,KAAA,WAAgB,OAAA;EAzEd;EA8EX,WAAA,CAAY,KAAA,UAAe,MAAA,YAAc,OAAA,CAAQ,0BAAA;;EAQjD,GAAA,CAAI,KAAA,UAAe,IAAA,WAAe,OAAA;EAlF5B;EAwFN,WAAA,CAAY,KAAA,WAAgB,OAAA;AAAA"}

package/dist/versioned-content-store.d.mts

@@ -0,0 +1,90 @@
+import { TreeIndex, TreeIndexListEntriesResult } from "./tree-index.mjs";
+import { VersionedContentFile } from "./versioned-content-index.mjs";
+
+//#region src/versioned-content-store.d.ts
+/** Metadata row for one materialized scope (the completion marker). */
+interface VersionedScopeMeta {
+  scope: string;
+  /** Opaque grouping key (same package, any version) for cleanup. */
+  scopeGroup: string;
+  /** Source-content fingerprint (dev-mode stale detection). */
+  seedDigest?: string;
+  ingestedAt: number;
+  fileCount: number;
+}
+/**
+ * Storage backend: binds scopes to TreeIndex instances over the shared DB and
+ * owns the scope-metadata table. Implementations are thin (entries machinery
+ * is the TreeIndex itself).
+ */
+interface VersionedScopeBackend {
+  /** A TreeIndex bound to `scope`, constructed with `inlineCache: "on"`. */
+  makeIndex(scope: string): TreeIndex;
+  getScopeMeta(scope: string): Promise<VersionedScopeMeta | null>;
+  putScopeMeta(meta: VersionedScopeMeta): Promise<void>;
+  deleteScopeMeta(scope: string): Promise<void>;
+  /** Every metadata row in `scopeGroup` (for sibling-version cleanup). */
+  listScopeMetaByGroup(scopeGroup: string): Promise<VersionedScopeMeta[]>;
+}
+/** `load()` result — either bare files or files + their freshly-computed digest. */
+type LoadedScopeContent = VersionedContentFile[] | {
+  files: VersionedContentFile[];
+  seedDigest?: string;
+};
+interface EnsureScopeOptions {
+  /** Exact scope key (`versionedScope(kind, id, token)`). */
+  scope: string;
+  /** Opaque group key — same package across versions (cleanup unit). */
+  group: string;
+  /**
+   * Load the source files (called ONLY on a miss/rebuild). May return a
+   * digest computed from the loaded bytes — stored in the metadata row so the
+   * prod hot path never recomputes it (`seedDigest` 仅在 ingest 时计算).
+   */
+  load: () => Promise<LoadedScopeContent>;
+  /**
+   * Source fingerprint. When supplied WITH `verifyDigest`, a metadata row
+   * whose digest differs triggers a rebuild (dev-mode stale defense). Stored
+   * in the metadata row either way.
+   */
+  seedDigest?: string;
+  /** Compare digests on hit (dev mode). Default false — prod trusts the key. */
+  verifyDigest?: boolean;
+  /** Force a rebuild regardless of the marker (dev "don't trust the cache"). */
+  force?: boolean;
+}
+interface EnsureScopeResult {
+  /** True when this call performed the build (miss/stale/forced). */
+  built: boolean;
+  fileCount: number;
+}
+interface VersionedContentStoreOptions {
+  backend: VersionedScopeBackend;
+  /** Per-file inline ceiling — over it ingest HARD-FAILS. Default 4KB. */
+  inlineThreshold?: number;
+  /** Build/cleanup observability (daemon log). Default: silent. */
+  log?: (line: string) => void;
+}
+declare class VersionedContentStore {
+  private readonly backend;
+  private readonly inlineThreshold;
+  private readonly log;
+  /** In-process single-flight per scope (concurrent first-miss → one build). */
+  private readonly inflight;
+  constructor(opts: VersionedContentStoreOptions);
+  /** Materialize a scope if needed. See {@link EnsureScopeOptions}. */
+  ensure(opts: EnsureScopeOptions): Promise<EnsureScopeResult>;
+  private ensureInner;
+  private build;
+  /** Is the scope fully materialized (completion marker present)? */
+  hasScope(scope: string): Promise<boolean>;
+  /** One-query bulk read of a scope's content. */
+  listEntries(scope: string, prefix?: string): Promise<TreeIndexListEntriesResult>;
+  /** Single-file read (null when absent). */
+  get(scope: string, path: string): Promise<string | null>;
+  /** Drop a scope entirely (entries + marker). */
+  deleteScope(scope: string): Promise<void>;
+}
+//#endregion
+export { EnsureScopeOptions, EnsureScopeResult, LoadedScopeContent, VersionedContentStore, VersionedContentStoreOptions, VersionedScopeBackend, VersionedScopeMeta };
+//# sourceMappingURL=versioned-content-store.d.mts.map

package/dist/versioned-content-store.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"versioned-content-store.d.mts","names":[],"sources":["../src/versioned-content-store.ts"],"mappings":";;;;;UAoCiB,kBAAA;EACf,KAAA;EAiBA;EAfA,UAAA;EAe6B;EAb7B,UAAA;EACA,UAAA;EACA,SAAA;AAAA;;;;;;UAQe,qBAAA;EAO2B;EAL1C,SAAA,CAAU,KAAA,WAAgB,SAAA;EAC1B,YAAA,CAAa,KAAA,WAAgB,OAAA,CAAQ,kBAAA;EACrC,YAAA,CAAa,IAAA,EAAM,kBAAA,GAAqB,OAAA;EACxC,eAAA,CAAgB,KAAA,WAAgB,OAAA;EAMJ;EAJ5B,oBAAA,CAAqB,UAAA,WAAqB,OAAA,CAAQ,kBAAA;AAAA;;KAIxC,kBAAA,GACR,oBAAA;EACE,KAAA,EAAO,oBAAA;EAAwB,UAAA;AAAA;AAAA,UAEpB,kBAAA;EAAA;EAEf,KAAA;;EAEA,KAAA;EAFA;;;;;EAQA,IAAA,QAAY,OAAA,CAAQ,kBAAA;EAQpB;;;;AAKF;EAPE,UAAA;;EAEA,YAAA;EAQS;EANT,KAAA;AAAA;AAAA,UAGe,iBAAA;EAOe;EAL9B,KAAA;EACA,SAAA;AAAA;AAAA,UAGe,4BAAA;EACf,OAAA,EAAS,qBAAA;EAIU;EAFnB,eAAA;EAKW;EAHX,GAAA,IAAO,IAAA;AAAA;AAAA,cAGI,qBAAA;EAAA,iBACM,OAAA;EAAA,iBACA,eAAA;EAAA,iBACA,GAAA;EAyEc;EAAA,iBAvEd,QAAA;cAEL,IAAA,EAAM,4BAAA;EAkFsB;EA1ElC,MAAA,CAAO,IAAA,EAAM,kBAAA,GAAqB,OAAA,CAAQ,iBAAA;EAAA,QAWlC,WAAA;EAAA,QAeA,KAAA;EAxCG;EA2EX,QAAA,CAAS,KAAA,WAAgB,OAAA;EAzEd;EA8EX,WAAA,CAAY,KAAA,UAAe,MAAA,YAAc,OAAA,CAAQ,0BAAA;;EAQjD,GAAA,CAAI,KAAA,UAAe,IAAA,WAAe,OAAA;EAlF5B;EAwFN,WAAA,CAAY,KAAA,WAAgB,OAAA;AAAA"}

package/dist/versioned-content-store.mjs

@@ -0,0 +1,122 @@
+import { DEFAULT_INLINE_THRESHOLD, INGEST_DEVICE_ID, assertInlineThreshold } from "./inline-content.mjs";
+import { VersionedContentIndex } from "./versioned-content-index.mjs";
+
+//#region src/versioned-content-store.ts
+/**
+* VersionedContentStore — multi-scope manager over {@link VersionedContentIndex}
+* (Layer 1 machinery: versioned package-content materialization).
+*
+* One store instance manages MANY scopes (`<kind>:<packageId>:<versionToken>`,
+* see `versioned-scope.ts`) inside ONE shared database — Node: a daemon-level
+* SQLite file; CF: the shared D1 binding; tests: in-memory. The machinery is
+* KIND-AGNOSTIC: scope and group are opaque keys; consumers map their source
+* content (via AFS) into `VersionedContentFile[]` and never touch the DB.
+*
+* Ingest contract (idempotent, lazily triggered):
+*   - `ensure(scope)` is a HIT when the scope's metadata row exists (and, when
+*     digest verification is requested, the stored digest matches) — zero
+*     source I/O on the hot path.
+*   - a MISS loads the source files, upserts every row, THEN writes the
+*     metadata row — the metadata row is the completion marker, so a crash
+*     mid-ingest leaves no readable half-scope (next access rebuilds).
+*   - concurrent first-miss within one process is memoized (single build);
+*     cross-process double builds are harmless (pure upserts + idempotent
+*     marker).
+*   - building a scope DELETES sibling scopes of the same `group` (an opaque
+*     `<kind>:<packageId>` prefix key) — version cleanup is one DELETE per
+*     stale scope, no blob GC involved (content is inline, rows ARE the data).
+*   - `seedDigest` lives in the metadata row, NEVER in the key — dev-mode
+*     stale detection compares digests; prod looks up by exact key only.
+*/
+var VersionedContentStore = class {
+	backend;
+	inlineThreshold;
+	log;
+	/** In-process single-flight per scope (concurrent first-miss → one build). */
+	inflight = /* @__PURE__ */ new Map();
+	constructor(opts) {
+		this.backend = opts.backend;
+		this.inlineThreshold = opts.inlineThreshold ?? DEFAULT_INLINE_THRESHOLD;
+		assertInlineThreshold(this.inlineThreshold);
+		this.log = opts.log ?? (() => {});
+	}
+	/** Materialize a scope if needed. See {@link EnsureScopeOptions}. */
+	async ensure(opts) {
+		const existing = this.inflight.get(opts.scope);
+		if (existing) return existing;
+		const run = this.ensureInner(opts).finally(() => {
+			this.inflight.delete(opts.scope);
+		});
+		this.inflight.set(opts.scope, run);
+		return run;
+	}
+	async ensureInner(opts) {
+		if (!opts.force) {
+			const meta = await this.backend.getScopeMeta(opts.scope);
+			if (meta) {
+				if (!(opts.verifyDigest && opts.seedDigest !== void 0 && meta.seedDigest !== opts.seedDigest)) return {
+					built: false,
+					fileCount: meta.fileCount
+				};
+				this.log(`[versioned-content] stale digest for ${opts.scope} (${meta.seedDigest} → ${opts.seedDigest}) — rebuilding`);
+			}
+		}
+		return this.build(opts);
+	}
+	async build(opts) {
+		const loaded = await opts.load();
+		const files = Array.isArray(loaded) ? loaded : loaded.files;
+		const loadedDigest = Array.isArray(loaded) ? void 0 : loaded.seedDigest;
+		const index = new VersionedContentIndex({
+			index: this.backend.makeIndex(opts.scope),
+			inlineThreshold: this.inlineThreshold
+		});
+		await index.deleteAll();
+		if (files.length > 0) await index.putBatch(files);
+		await this.backend.putScopeMeta({
+			scope: opts.scope,
+			scopeGroup: opts.group,
+			seedDigest: opts.seedDigest ?? loadedDigest,
+			ingestedAt: Date.now(),
+			fileCount: files.length
+		});
+		this.log(`[versioned-content] built scope ${opts.scope} (${files.length} files)`);
+		const siblings = await this.backend.listScopeMetaByGroup(opts.group);
+		for (const sibling of siblings) {
+			if (sibling.scope === opts.scope) continue;
+			await this.deleteScope(sibling.scope);
+			this.log(`[versioned-content] deleted superseded scope ${sibling.scope}`);
+		}
+		return {
+			built: true,
+			fileCount: files.length
+		};
+	}
+	/** Is the scope fully materialized (completion marker present)? */
+	async hasScope(scope) {
+		return await this.backend.getScopeMeta(scope) !== null;
+	}
+	/** One-query bulk read of a scope's content. */
+	async listEntries(scope, prefix = "") {
+		return this.backend.makeIndex(scope).listEntries(prefix, {
+			includeContent: true,
+			limit: 1e3
+		});
+	}
+	/** Single-file read (null when absent). */
+	async get(scope, path) {
+		return (await this.backend.makeIndex(scope).get(path))?.content ?? null;
+	}
+	/** Drop a scope entirely (entries + marker). */
+	async deleteScope(scope) {
+		await this.backend.deleteScopeMeta(scope);
+		await this.backend.makeIndex(scope).deleteByPrefix("", {
+			deviceId: INGEST_DEVICE_ID,
+			skipChangelog: true
+		});
+	}
+};
+
+//#endregion
+export { VersionedContentStore };
+//# sourceMappingURL=versioned-content-store.mjs.map

package/dist/versioned-content-store.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"versioned-content-store.mjs","names":[],"sources":["../src/versioned-content-store.ts"],"sourcesContent":["/**\n * VersionedContentStore — multi-scope manager over {@link VersionedContentIndex}\n * (Layer 1 machinery: versioned package-content materialization).\n *\n * One store instance manages MANY scopes (`<kind>:<packageId>:<versionToken>`,\n * see `versioned-scope.ts`) inside ONE shared database — Node: a daemon-level\n * SQLite file; CF: the shared D1 binding; tests: in-memory. The machinery is\n * KIND-AGNOSTIC: scope and group are opaque keys; consumers map their source\n * content (via AFS) into `VersionedContentFile[]` and never touch the DB.\n *\n * Ingest contract (idempotent, lazily triggered):\n *   - `ensure(scope)` is a HIT when the scope's metadata row exists (and, when\n *     digest verification is requested, the stored digest matches) — zero\n *     source I/O on the hot path.\n *   - a MISS loads the source files, upserts every row, THEN writes the\n *     metadata row — the metadata row is the completion marker, so a crash\n *     mid-ingest leaves no readable half-scope (next access rebuilds).\n *   - concurrent first-miss within one process is memoized (single build);\n *     cross-process double builds are harmless (pure upserts + idempotent\n *     marker).\n *   - building a scope DELETES sibling scopes of the same `group` (an opaque\n *     `<kind>:<packageId>` prefix key) — version cleanup is one DELETE per\n *     stale scope, no blob GC involved (content is inline, rows ARE the data).\n *   - `seedDigest` lives in the metadata row, NEVER in the key — dev-mode\n *     stale detection compares digests; prod looks up by exact key only.\n */\n\nimport {\n  assertInlineThreshold,\n  DEFAULT_INLINE_THRESHOLD,\n  INGEST_DEVICE_ID,\n} from \"./inline-content.js\";\nimport type { TreeIndex, TreeIndexListEntriesResult } from \"./tree-index.js\";\nimport { type VersionedContentFile, VersionedContentIndex } from \"./versioned-content-index.js\";\n\n/** Metadata row for one materialized scope (the completion marker). */\nexport interface VersionedScopeMeta {\n  scope: string;\n  /** Opaque grouping key (same package, any version) for cleanup. */\n  scopeGroup: string;\n  /** Source-content fingerprint (dev-mode stale detection). */\n  seedDigest?: string;\n  ingestedAt: number;\n  fileCount: number;\n}\n\n/**\n * Storage backend: binds scopes to TreeIndex instances over the shared DB and\n * owns the scope-metadata table. Implementations are thin (entries machinery\n * is the TreeIndex itself).\n */\nexport interface VersionedScopeBackend {\n  /** A TreeIndex bound to `scope`, constructed with `inlineCache: \"on\"`. */\n  makeIndex(scope: string): TreeIndex;\n  getScopeMeta(scope: string): Promise<VersionedScopeMeta | null>;\n  putScopeMeta(meta: VersionedScopeMeta): Promise<void>;\n  deleteScopeMeta(scope: string): Promise<void>;\n  /** Every metadata row in `scopeGroup` (for sibling-version cleanup). */\n  listScopeMetaByGroup(scopeGroup: string): Promise<VersionedScopeMeta[]>;\n}\n\n/** `load()` result — either bare files or files + their freshly-computed digest. */\nexport type LoadedScopeContent =\n  | VersionedContentFile[]\n  | { files: VersionedContentFile[]; seedDigest?: string };\n\nexport interface EnsureScopeOptions {\n  /** Exact scope key (`versionedScope(kind, id, token)`). */\n  scope: string;\n  /** Opaque group key — same package across versions (cleanup unit). */\n  group: string;\n  /**\n   * Load the source files (called ONLY on a miss/rebuild). May return a\n   * digest computed from the loaded bytes — stored in the metadata row so the\n   * prod hot path never recomputes it (`seedDigest` 仅在 ingest 时计算).\n   */\n  load: () => Promise<LoadedScopeContent>;\n  /**\n   * Source fingerprint. When supplied WITH `verifyDigest`, a metadata row\n   * whose digest differs triggers a rebuild (dev-mode stale defense). Stored\n   * in the metadata row either way.\n   */\n  seedDigest?: string;\n  /** Compare digests on hit (dev mode). Default false — prod trusts the key. */\n  verifyDigest?: boolean;\n  /** Force a rebuild regardless of the marker (dev \"don't trust the cache\"). */\n  force?: boolean;\n}\n\nexport interface EnsureScopeResult {\n  /** True when this call performed the build (miss/stale/forced). */\n  built: boolean;\n  fileCount: number;\n}\n\nexport interface VersionedContentStoreOptions {\n  backend: VersionedScopeBackend;\n  /** Per-file inline ceiling — over it ingest HARD-FAILS. Default 4KB. */\n  inlineThreshold?: number;\n  /** Build/cleanup observability (daemon log). Default: silent. */\n  log?: (line: string) => void;\n}\n\nexport class VersionedContentStore {\n  private readonly backend: VersionedScopeBackend;\n  private readonly inlineThreshold: number;\n  private readonly log: (line: string) => void;\n  /** In-process single-flight per scope (concurrent first-miss → one build). */\n  private readonly inflight = new Map<string, Promise<EnsureScopeResult>>();\n\n  constructor(opts: VersionedContentStoreOptions) {\n    this.backend = opts.backend;\n    this.inlineThreshold = opts.inlineThreshold ?? DEFAULT_INLINE_THRESHOLD;\n    assertInlineThreshold(this.inlineThreshold);\n    this.log = opts.log ?? (() => {});\n  }\n\n  /** Materialize a scope if needed. See {@link EnsureScopeOptions}. */\n  async ensure(opts: EnsureScopeOptions): Promise<EnsureScopeResult> {\n    const existing = this.inflight.get(opts.scope);\n    if (existing) return existing;\n\n    const run = this.ensureInner(opts).finally(() => {\n      this.inflight.delete(opts.scope);\n    });\n    this.inflight.set(opts.scope, run);\n    return run;\n  }\n\n  private async ensureInner(opts: EnsureScopeOptions): Promise<EnsureScopeResult> {\n    if (!opts.force) {\n      const meta = await this.backend.getScopeMeta(opts.scope);\n      if (meta) {\n        const stale =\n          opts.verifyDigest && opts.seedDigest !== undefined && meta.seedDigest !== opts.seedDigest;\n        if (!stale) return { built: false, fileCount: meta.fileCount };\n        this.log(\n          `[versioned-content] stale digest for ${opts.scope} (${meta.seedDigest} → ${opts.seedDigest}) — rebuilding`,\n        );\n      }\n    }\n    return this.build(opts);\n  }\n\n  private async build(opts: EnsureScopeOptions): Promise<EnsureScopeResult> {\n    const loaded = await opts.load();\n    const files = Array.isArray(loaded) ? loaded : loaded.files;\n    const loadedDigest = Array.isArray(loaded) ? undefined : loaded.seedDigest;\n    const index = new VersionedContentIndex({\n      index: this.backend.makeIndex(opts.scope),\n      inlineThreshold: this.inlineThreshold,\n    });\n\n    // Rebuild from scratch: drop any partial/stale rows first, then upsert.\n    // The metadata row is written LAST — it is the completion marker; until it\n    // lands, `ensure` treats the scope as absent (no half-scope is readable).\n    await index.deleteAll();\n    if (files.length > 0) await index.putBatch(files);\n    await this.backend.putScopeMeta({\n      scope: opts.scope,\n      scopeGroup: opts.group,\n      seedDigest: opts.seedDigest ?? loadedDigest,\n      ingestedAt: Date.now(),\n      fileCount: files.length,\n    });\n    this.log(`[versioned-content] built scope ${opts.scope} (${files.length} files)`);\n\n    // Sibling-version cleanup: every other scope in the group is superseded.\n    const siblings = await this.backend.listScopeMetaByGroup(opts.group);\n    for (const sibling of siblings) {\n      if (sibling.scope === opts.scope) continue;\n      await this.deleteScope(sibling.scope);\n      this.log(`[versioned-content] deleted superseded scope ${sibling.scope}`);\n    }\n\n    return { built: true, fileCount: files.length };\n  }\n\n  /** Is the scope fully materialized (completion marker present)? */\n  async hasScope(scope: string): Promise<boolean> {\n    return (await this.backend.getScopeMeta(scope)) !== null;\n  }\n\n  /** One-query bulk read of a scope's content. */\n  async listEntries(scope: string, prefix = \"\"): Promise<TreeIndexListEntriesResult> {\n    return this.backend.makeIndex(scope).listEntries(prefix, {\n      includeContent: true,\n      limit: 1000,\n    });\n  }\n\n  /** Single-file read (null when absent). */\n  async get(scope: string, path: string): Promise<string | null> {\n    const entry = await this.backend.makeIndex(scope).get(path);\n    return entry?.content ?? null;\n  }\n\n  /** Drop a scope entirely (entries + marker). */\n  async deleteScope(scope: string): Promise<void> {\n    // Marker first: a concurrent reader must not see a marked-but-draining scope.\n    await this.backend.deleteScopeMeta(scope);\n    await this.backend\n      .makeIndex(scope)\n      .deleteByPrefix(\"\", { deviceId: INGEST_DEVICE_ID, skipChangelog: true });\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAuGA,IAAa,wBAAb,MAAmC;CACjC,AAAiB;CACjB,AAAiB;CACjB,AAAiB;;CAEjB,AAAiB,2BAAW,IAAI,KAAyC;CAEzE,YAAY,MAAoC;AAC9C,OAAK,UAAU,KAAK;AACpB,OAAK,kBAAkB,KAAK,mBAAmB;AAC/C,wBAAsB,KAAK,gBAAgB;AAC3C,OAAK,MAAM,KAAK,cAAc;;;CAIhC,MAAM,OAAO,MAAsD;EACjE,MAAM,WAAW,KAAK,SAAS,IAAI,KAAK,MAAM;AAC9C,MAAI,SAAU,QAAO;EAErB,MAAM,MAAM,KAAK,YAAY,KAAK,CAAC,cAAc;AAC/C,QAAK,SAAS,OAAO,KAAK,MAAM;IAChC;AACF,OAAK,SAAS,IAAI,KAAK,OAAO,IAAI;AAClC,SAAO;;CAGT,MAAc,YAAY,MAAsD;AAC9E,MAAI,CAAC,KAAK,OAAO;GACf,MAAM,OAAO,MAAM,KAAK,QAAQ,aAAa,KAAK,MAAM;AACxD,OAAI,MAAM;AAGR,QAAI,EADF,KAAK,gBAAgB,KAAK,eAAe,UAAa,KAAK,eAAe,KAAK,YACrE,QAAO;KAAE,OAAO;KAAO,WAAW,KAAK;KAAW;AAC9D,SAAK,IACH,wCAAwC,KAAK,MAAM,IAAI,KAAK,WAAW,KAAK,KAAK,WAAW,gBAC7F;;;AAGL,SAAO,KAAK,MAAM,KAAK;;CAGzB,MAAc,MAAM,MAAsD;EACxE,MAAM,SAAS,MAAM,KAAK,MAAM;EAChC,MAAM,QAAQ,MAAM,QAAQ,OAAO,GAAG,SAAS,OAAO;EACtD,MAAM,eAAe,MAAM,QAAQ,OAAO,GAAG,SAAY,OAAO;EAChE,MAAM,QAAQ,IAAI,sBAAsB;GACtC,OAAO,KAAK,QAAQ,UAAU,KAAK,MAAM;GACzC,iBAAiB,KAAK;GACvB,CAAC;AAKF,QAAM,MAAM,WAAW;AACvB,MAAI,MAAM,SAAS,EAAG,OAAM,MAAM,SAAS,MAAM;AACjD,QAAM,KAAK,QAAQ,aAAa;GAC9B,OAAO,KAAK;GACZ,YAAY,KAAK;GACjB,YAAY,KAAK,cAAc;GAC/B,YAAY,KAAK,KAAK;GACtB,WAAW,MAAM;GAClB,CAAC;AACF,OAAK,IAAI,mCAAmC,KAAK,MAAM,IAAI,MAAM,OAAO,SAAS;EAGjF,MAAM,WAAW,MAAM,KAAK,QAAQ,qBAAqB,KAAK,MAAM;AACpE,OAAK,MAAM,WAAW,UAAU;AAC9B,OAAI,QAAQ,UAAU,KAAK,MAAO;AAClC,SAAM,KAAK,YAAY,QAAQ,MAAM;AACrC,QAAK,IAAI,gDAAgD,QAAQ,QAAQ;;AAG3E,SAAO;GAAE,OAAO;GAAM,WAAW,MAAM;GAAQ;;;CAIjD,MAAM,SAAS,OAAiC;AAC9C,SAAQ,MAAM,KAAK,QAAQ,aAAa,MAAM,KAAM;;;CAItD,MAAM,YAAY,OAAe,SAAS,IAAyC;AACjF,SAAO,KAAK,QAAQ,UAAU,MAAM,CAAC,YAAY,QAAQ;GACvD,gBAAgB;GAChB,OAAO;GACR,CAAC;;;CAIJ,MAAM,IAAI,OAAe,MAAsC;AAE7D,UADc,MAAM,KAAK,QAAQ,UAAU,MAAM,CAAC,IAAI,KAAK,GAC7C,WAAW;;;CAI3B,MAAM,YAAY,OAA8B;AAE9C,QAAM,KAAK,QAAQ,gBAAgB,MAAM;AACzC,QAAM,KAAK,QACR,UAAU,MAAM,CAChB,eAAe,IAAI;GAAE,UAAU;GAAkB,eAAe;GAAM,CAAC"}

package/dist/versioned-scope.cjs

@@ -0,0 +1,39 @@
+
+//#region src/versioned-scope.ts
+/** Separator-escape: `%` → `%25`, `:` → `%3A`, `/` → `%2F`. */
+function escapeComponent(raw, name) {
+	if (typeof raw !== "string" || raw.length === 0) throw new Error(`versionedScope: ${name} must be a non-empty string`);
+	return raw.replaceAll("%", "%25").replaceAll(":", "%3A").replaceAll("/", "%2F");
+}
+/**
+* Build the canonical `<kind>:<packageId>:<versionToken>` scope key.
+* Components are escaped so a separator INSIDE a component can never collide
+* with the separator BETWEEN components. Throws on empty/non-string input.
+*/
+function versionedScope(kind, packageId, versionToken) {
+	return `${escapeComponent(kind, "kind")}:${escapeComponent(packageId, "packageId")}:${escapeComponent(versionToken, "versionToken")}`;
+}
+/**
+* Build the group key for a (kind, packageId) pair — the same escaped prefix
+* a {@link versionedScope} key starts with, WITHOUT the version token. Used
+* as the opaque cleanup unit: building a new version's scope supersedes every
+* sibling scope sharing this group.
+*/
+function versionedScopeGroup(kind, packageId) {
+	return `${escapeComponent(kind, "kind")}:${escapeComponent(packageId, "packageId")}`;
+}
+/**
+* Resolve the version token for a package: `manifest.version` when present,
+* else the content digest. Throws when neither exists — an empty or
+* `"undefined"` token would collide every unversioned package into one scope.
+*/
+function resolveVersionToken(identity, seedDigest) {
+	if (identity.version) return identity.version;
+	if (seedDigest) return seedDigest;
+	throw new Error(`versionedScope: package "${identity.id}" has neither manifest.version nor a content digest — refusing to build an ambiguous scope key`);
+}
+
+//#endregion
+exports.resolveVersionToken = resolveVersionToken;
+exports.versionedScope = versionedScope;
+exports.versionedScopeGroup = versionedScopeGroup;