Fold archive occurrence refs into the compaction archive module

archive-uri.ts owned the archive:// addressing scheme apart from the store that honors it. The ref helpers now live on compaction-archive.ts verbatim; plugins and session importers follow. No behavior change.

Author: TheGreatAxios

src/plugins/evidence-archive-search-plugin.test.ts

@@ -8,9 +8,9 @@ import {
   advertiseArchiveSurface,
   evidenceArchiveSearchPlugin,
 } from "./evidence-archive-search-plugin.js";
-import { formatArchiveRef } from "../session/archive-uri.js";
 import {
   createCompactionArchive,
+  formatArchiveRef,
   type CompactionArchive,
 } from "../session/compaction-archive.js";
 import { CATALOG_TOOL_NAMES, CORE_TOOL_NAMES } from "../agent/tool-search.js";

src/plugins/evidence-archive-search-plugin.ts

@@ -11,7 +11,7 @@ import {
   formatArchiveRef,
   isArchiveLike,
   parseArchiveTarget,
-} from "../session/archive-uri.js";
+} from "../session/compaction-archive.js";
 
 const SEARCH_DEFAULT_MAX = 1000;
 const GREP_DEFAULT_MAX = 500;

src/plugins/path-escape-plugin.ts

@@ -1,7 +1,7 @@
 import { resolve } from "node:path";
 import type { ToolPlugin } from "@intx/tools-posix";
 import { isToolOutputLike } from "../util/tool-output-uri.js";
-import { isArchiveLike } from "../session/archive-uri.js";
+import { isArchiveLike } from "../session/compaction-archive.js";
 import { resolveWorkspacePath } from "../permission/path-restriction.js";
 import type { RootsProvider } from "../permission/worktree-roots.js";
 

src/session/archive-uri.test.ts

@@ -5,7 +5,7 @@ import {
   isArchiveLike,
   parseArchiveRef,
   parseArchiveTarget,
-} from "./archive-uri.js";
+} from "./compaction-archive.js";
 
 describe("archive URI", () => {
   test("formats and parses archive:/// occurrence refs", () => {

src/session/archive-uri.ts

@@ -925,3 +925,39 @@ export function wrapCompactorWithCompletenessGate(
     },
   };
 }
+
+// ---------------------------------------------------------------------------
+// Archive occurrence refs (pure addressing)
+// ---------------------------------------------------------------------------
+// The archive's own addressing scheme: `archive:///<occurrenceId>` refs name
+// where an occurrence's payload bytes live. Kept on the archive module so the
+// URI scheme and the store that honors it cannot drift apart.
+
+/** Prefix for every archive target, including the bare `archive:///` root. */
+export const ARCHIVE_URI_PREFIX = "archive:";
+const ARCHIVE_URI_CANONICAL = "archive:///";
+
+/** Render the canonical ref for an occurrence id. */
+export function formatArchiveRef(occurrenceId: string): string {
+  return `${ARCHIVE_URI_CANONICAL}${occurrenceId}`;
+}
+
+export function isArchiveLike(path: string): boolean {
+  return path.startsWith(ARCHIVE_URI_PREFIX);
+}
+
+/** Accept archive:///occ-… and common slashes; return the occurrence id or undefined. */
+export function parseArchiveRef(value: string): string | undefined {
+  return parseArchiveTarget(value)?.occurrenceId;
+}
+
+/** Root `archive:///` has no occurrenceId; a ref includes one. */
+export function parseArchiveTarget(
+  value: string,
+): { occurrenceId?: string } | undefined {
+  if (!isArchiveLike(value)) return undefined;
+  const rest = value.slice(ARCHIVE_URI_PREFIX.length).replace(/^\/+/, "");
+  const occurrenceId = rest.split(/[/?#]/)[0] ?? "";
+  if (occurrenceId.length === 0) return {};
+  return { occurrenceId };
+}

src/session/compaction-archive.ts

@@ -20,12 +20,14 @@ import {
 } from "@intx/types/runtime";
 import { LOG_NAMESPACE_ROOT } from "../branding.js";
 import { NOOP_TELEMETRY, type Telemetry } from "../telemetry/index.js";
-import type { CompactionArchive } from "./compaction-archive.js";
+import {
+  formatArchiveRef,
+  type CompactionArchive,
+} from "./compaction-archive.js";
 import type {
   ArchiveKind,
   ArchiveOccurrence,
 } from "./compaction-archive-schema.js";
-import { formatArchiveRef } from "./archive-uri.js";
 import { readSourceCredentialMaterial } from "../config/source-credentials.js";
 
 const logger = getLogger([LOG_NAMESPACE_ROOT, "session", "summarizer"]);