@aigne/aos 0.2.0-beta

package/dist/session/replication-resolver.mjs

@@ -0,0 +1,323 @@
+import { roleLevel } from "./role-level.mjs";
+import { AFSForbiddenError } from "@aigne/afs";
+
+//#region src/session/replication-resolver.ts
+/**
+* Compute the overlay mount prefix for a set of replicated collections.
+* Returns the LCP (longest common prefix) of the "pre-collection" segments
+* (everything before the collection-name segment, which sits just before `*`)
+* across all canonical patterns. This is the path at which a single
+* ReplicationResolver overlay is mounted in SessionUserAFS.
+*
+* Examples:
+*   { notes: { canonical: "instance/notes/*" } }
+*     → "instance"   (pre-collection = ["instance"])
+*   { posts: "instance/app/posts/*", comments: "instance/app/comments/*" }
+*     → "instance/app"  (LCP of ["instance","app"] and ["instance","app"])
+*   { notes: "instance/notes/*", posts: "instance/app/posts/*" }
+*     → "instance"  (LCP of ["instance"] and ["instance","app"])
+*/
+function computeReplicationMountPrefix(collections) {
+	const entries = Object.values(collections);
+	if (entries.length === 0) throw new Error("No replicated collections declared");
+	const parents = entries.map(({ canonical }) => {
+		const segs = canonical.split("/").filter((s) => s.length > 0);
+		const starIdx = segs.indexOf("*");
+		if (starIdx < 1) throw new Error(`Invalid canonical pattern (no * or too short): ${canonical}`);
+		return segs.slice(0, starIdx - 1);
+	});
+	const first = parents[0];
+	let lcpLen = first.length;
+	for (let k = 1; k < parents.length; k++) {
+		const p = parents[k];
+		let len = 0;
+		while (len < lcpLen && len < p.length && first[len] === p[len]) len++;
+		lcpLen = len;
+	}
+	return first.slice(0, lcpLen).join("/") || "instance";
+}
+/**
+* Derive the sidecar path for a given item path, using the pattern to determine
+* the injection point. Injects `.provenance/` before the collection segment
+* (segment at firstStarIndex - 1 of the pattern).
+*
+* Examples:
+*   pattern="instance/app/posts/*",         item="/instance/app/posts/p1"
+*     → "/instance/app/.provenance/posts/p1"
+*   pattern="instance/app/posts/{star}/comments/{star}", item="/instance/app/posts/p1/comments/c1"
+*     → "/instance/app/.provenance/posts/p1/comments/c1"
+*   Works for copy paths too: item="/user/app/posts/p1"
+*     → "/user/app/.provenance/posts/p1"
+*/
+function deriveSidecarPath(pattern, fullItemPath) {
+	const patternSegs = pattern.split("/").filter((s) => s.length > 0);
+	const firstStarIdx = patternSegs.indexOf("*");
+	if (firstStarIdx < 1) throw new Error(`Invalid pattern (no * or too short): ${pattern}`);
+	const preCollectionLen = firstStarIdx - 1;
+	const collectionSeg = patternSegs[firstStarIdx - 1];
+	const itemSegs = fullItemPath.replace(/^\//, "").split("/").filter((s) => s.length > 0);
+	const itemTail = itemSegs.slice(firstStarIdx);
+	return `/${[
+		...itemSegs.slice(0, preCollectionLen),
+		".provenance",
+		collectionSeg,
+		...itemTail
+	].join("/")}`;
+}
+/**
+* Find the best-matching collection for a given (normalized, no-leading-slash) item path.
+* Uses longest-match: the pattern that consumes the most path segments with static segments wins.
+* Returns null if no collection matches.
+*/
+function matchCollections(collections, normalizedPath) {
+	const itemSegs = normalizedPath.replace(/^\//, "").split("/").filter((s) => s.length > 0);
+	let best = null;
+	for (const [name, collection] of Object.entries(collections)) {
+		const score = tryMatchPattern(collection.canonical.split("/").filter((s) => s.length > 0), itemSegs);
+		if (score !== null && (best === null || score > best.score)) best = {
+			name,
+			collection,
+			score
+		};
+	}
+	return best ? {
+		name: best.name,
+		collection: best.collection
+	} : null;
+}
+/**
+* Try to match a pattern (segment array) against an item path (segment array).
+* Returns a score (higher = more specific) on match, or null on mismatch.
+* Rules:
+*   - Static segments must match exactly.
+*   - Non-terminal `*` matches exactly one segment.
+*   - Terminal `*` matches one or more remaining segments (item + subtree).
+*/
+function tryMatchPattern(patternSegs, itemSegs) {
+	let pIdx = 0;
+	let iIdx = 0;
+	let score = 0;
+	while (pIdx < patternSegs.length) {
+		const pSeg = patternSegs[pIdx];
+		if (pSeg === "*") {
+			if (pIdx === patternSegs.length - 1) {
+				if (iIdx >= itemSegs.length) return null;
+				score += 10 + (itemSegs.length - iIdx - 1);
+				return score;
+			}
+			if (iIdx >= itemSegs.length) return null;
+			iIdx++;
+			score += 100;
+		} else {
+			if (iIdx >= itemSegs.length || itemSegs[iIdx] !== pSeg) return null;
+			iIdx++;
+			score += 1e3;
+		}
+		pIdx++;
+	}
+	return null;
+}
+/**
+* Match a path against canonical collection patterns OR their derived sidecar
+* mirror patterns (`.provenance/` prefixed). Used for the read gate (P2).
+*
+* Sidecar matching: strips the `.provenance` segment from the path and checks
+* the resulting path against the canonical patterns.
+*/
+function matchCollectionsForRead(collections, normalizedPath) {
+	const direct = matchCollections(collections, normalizedPath);
+	if (direct) return direct;
+	const segs = normalizedPath.split("/").filter((s) => s.length > 0);
+	const provenanceIdx = segs.indexOf(".provenance");
+	if (provenanceIdx < 0) return null;
+	return matchCollections(collections, [...segs.slice(0, provenanceIdx), ...segs.slice(provenanceIdx + 1)].join("/"));
+}
+/**
+* Check that a path contains no `..` or empty segments (path safety).
+* Returns the normalized path (no leading `/`) on success.
+* Throws AFSForbiddenError on suspicious input.
+*/
+function assertPathSafe(path) {
+	const norm = path.replace(/^\//, "");
+	const segs = norm.split("/");
+	for (const seg of segs) if (seg === "" || seg === "..") throw new AFSForbiddenError(path, `path contains unsafe segment: "${seg === "" ? "(empty)" : seg}"`);
+	return norm;
+}
+/**
+* Convert a canonical `/instance/...` path to the author-copy `/user/...` path.
+* Replaces the first segment (`instance`) with `user`.
+* Returns the VIEW path (prefixed with /user) — callers must strip /user before
+* passing to userBackend, since userBackend operates at provider-relative paths.
+*/
+function canonicalToViewCopyPath(canonicalPath) {
+	const norm = canonicalPath.replace(/^\//, "");
+	const slashIdx = norm.indexOf("/");
+	if (slashIdx < 0) return "/user";
+	return `/user${norm.slice(slashIdx)}`;
+}
+/**
+* Strip the `/user` view prefix from a copy view path to get the
+* provider-relative path for userBackend calls.
+*/
+function copyViewToProviderPath(viewPath) {
+	if (viewPath === "/user") return "/";
+	if (viewPath.startsWith("/user/")) return viewPath.slice(5);
+	return viewPath;
+}
+/**
+* ReplicationResolver intercepts writes and deletes to replicated-collection
+* paths, enforces role gates, and fans out to both canonical (instanceBackend)
+* and author copy (userBackend) with provenance sidecars.
+*
+* Mounted as a SessionUserAFS overlay at `/${mountPrefix}` (typically
+* /instance). Receives SUB-PATHS (after prefix stripping by the overlay
+* system) and reconstructs full paths internally using mountPrefix.
+*
+* P1: write + delete implemented.
+* P2: read gate (readRole) + createSessionView wiring.
+*/
+var ReplicationResolver = class {
+	name;
+	mountPrefix;
+	constructor(opts) {
+		this.opts = opts;
+		this.name = `replication-resolver:${opts.sessionId}`;
+		this.mountPrefix = opts.mountPrefix ?? computeReplicationMountPrefix(opts.collections);
+	}
+	/**
+	* Reconstruct the full canonical path from the sub-path the overlay delivers.
+	* The overlay at `/${mountPrefix}` strips the prefix, leaving e.g. `/notes/n1`
+	* from `/instance/notes/n1`. We prepend mountPrefix to restore the full path.
+	*/
+	toFullPath(sub) {
+		const s = sub.startsWith("/") ? sub : `/${sub}`;
+		return `/${this.mountPrefix}${s}`;
+	}
+	async getEffectiveMinRole(collectionName, collection) {
+		if (this.opts.settingsResolver) try {
+			const v = (await this.opts.settingsResolver.read(`/${collectionName}/minRole.json/value`)).data?.content;
+			if (typeof v === "string" && v.length > 0) return v;
+		} catch {}
+		return collection.minRole ?? "member";
+	}
+	async getEffectiveReadRole(collectionName, collection) {
+		if (this.opts.settingsResolver) try {
+			const v = (await this.opts.settingsResolver.read(`/${collectionName}/readRole.json/value`)).data?.content;
+			if (typeof v === "string" && v.length > 0) return v;
+		} catch {}
+		return collection.readRole ?? "guest";
+	}
+	async read(path, options) {
+		const fullPath = this.toFullPath(path);
+		const normPath = assertPathSafe(fullPath);
+		const match = matchCollectionsForRead(this.opts.collections, normPath);
+		if (match) {
+			const effectiveReadRole = await this.getEffectiveReadRole(match.name, match.collection);
+			if (roleLevel(this.opts.callerRole) < roleLevel(effectiveReadRole)) throw new AFSForbiddenError(fullPath, `role '${this.opts.callerRole ?? "guest"}' is below readRole '${effectiveReadRole}'`);
+		}
+		if (!this.opts.instanceBackend.read) throw new AFSForbiddenError(fullPath, "instanceBackend does not support read");
+		return this.opts.instanceBackend.read(fullPath, options);
+	}
+	async list(path, options) {
+		const fullPath = this.toFullPath(path);
+		const normPath = assertPathSafe(fullPath);
+		const match = matchCollectionsForRead(this.opts.collections, normPath);
+		if (match) {
+			const effectiveReadRole = await this.getEffectiveReadRole(match.name, match.collection);
+			if (roleLevel(this.opts.callerRole) < roleLevel(effectiveReadRole)) throw new AFSForbiddenError(fullPath, `role '${this.opts.callerRole ?? "guest"}' is below readRole '${effectiveReadRole}'`);
+		}
+		if (!this.opts.instanceBackend.list) throw new AFSForbiddenError(fullPath, "instanceBackend does not support list");
+		return this.opts.instanceBackend.list(fullPath, options);
+	}
+	async stat(path, options) {
+		const fullPath = this.toFullPath(path);
+		const normPath = assertPathSafe(fullPath);
+		const match = matchCollectionsForRead(this.opts.collections, normPath);
+		if (match) {
+			const effectiveReadRole = await this.getEffectiveReadRole(match.name, match.collection);
+			if (roleLevel(this.opts.callerRole) < roleLevel(effectiveReadRole)) throw new AFSForbiddenError(fullPath, `role '${this.opts.callerRole ?? "guest"}' is below readRole '${effectiveReadRole}'`);
+		}
+		if (!this.opts.instanceBackend.stat) throw new AFSForbiddenError(fullPath, "instanceBackend does not support stat");
+		return this.opts.instanceBackend.stat(fullPath, options);
+	}
+	async search(path, query, options) {
+		const fullPath = this.toFullPath(path);
+		const normPath = assertPathSafe(fullPath);
+		const match = matchCollectionsForRead(this.opts.collections, normPath);
+		if (match) {
+			const effectiveReadRole = await this.getEffectiveReadRole(match.name, match.collection);
+			if (roleLevel(this.opts.callerRole) < roleLevel(effectiveReadRole)) throw new AFSForbiddenError(fullPath, `role '${this.opts.callerRole ?? "guest"}' is below readRole '${effectiveReadRole}'`);
+		}
+		if (!this.opts.instanceBackend.search) throw new AFSForbiddenError(fullPath, "instanceBackend does not support search");
+		return this.opts.instanceBackend.search(fullPath, query, options);
+	}
+	async write(path, content, options) {
+		const fullPath = this.toFullPath(path);
+		const normPath = assertPathSafe(fullPath);
+		const match = matchCollections(this.opts.collections, normPath);
+		if (!match) {
+			if ((options?.context)?.callerOrigin === "network") throw new AFSForbiddenError(fullPath, "network clients cannot write non-replicated instance paths");
+			if (!this.opts.instanceBackend.write) throw new AFSForbiddenError(fullPath, "instanceBackend does not support write");
+			return this.opts.instanceBackend.write(fullPath, content, options);
+		}
+		const { name: collectionName, collection } = match;
+		const effectiveMinRole = await this.getEffectiveMinRole(collectionName, collection);
+		if (roleLevel(this.opts.callerRole) < roleLevel(effectiveMinRole)) throw new AFSForbiddenError(fullPath, `role '${this.opts.callerRole ?? "guest"}' is below minRole '${effectiveMinRole}'`);
+		const authorDid = this.opts.callerDid ?? null;
+		const publishedAt = (/* @__PURE__ */ new Date()).toISOString();
+		if ((collection.copy ?? "mirror") !== "none" && this.opts.userBackend !== null && this.opts.userBackend.write) {
+			const copyViewPath = canonicalToViewCopyPath(fullPath);
+			const copyProviderPath = copyViewToProviderPath(copyViewPath);
+			await this.opts.userBackend.write(copyProviderPath, content);
+			const copySidecarProviderPath = copyViewToProviderPath(deriveSidecarPath(collection.canonical, copyViewPath));
+			const copySidecar = {
+				canonical_ref: {
+					instance_did: this.opts.instanceDid ?? "",
+					path: normPath.replace(/^instance\//, "")
+				},
+				published_at: publishedAt
+			};
+			await this.opts.userBackend.write(copySidecarProviderPath, { content: JSON.stringify(copySidecar) });
+		}
+		if (!this.opts.instanceBackend.write) throw new AFSForbiddenError(fullPath, "instanceBackend does not support write");
+		const result = await this.opts.instanceBackend.write(fullPath, content, options);
+		const canonicalSidecarPath = deriveSidecarPath(collection.canonical, fullPath);
+		const canonicalSidecar = {
+			author_did: authorDid,
+			published_at: publishedAt
+		};
+		await this.opts.instanceBackend.write(canonicalSidecarPath, { content: JSON.stringify(canonicalSidecar) });
+		return result;
+	}
+	async delete(path, options) {
+		const fullPath = this.toFullPath(path);
+		const normPath = assertPathSafe(fullPath);
+		const match = matchCollections(this.opts.collections, normPath);
+		if (!match) {
+			if (!this.opts.instanceBackend.delete) return {};
+			return this.opts.instanceBackend.delete(fullPath, options);
+		}
+		const { collection } = match;
+		const canonicalSidecarPath = deriveSidecarPath(collection.canonical, fullPath);
+		let provenanceAuthorDid = null;
+		if (this.opts.instanceBackend.read) try {
+			const raw = (await this.opts.instanceBackend.read(canonicalSidecarPath)).data?.content;
+			if (typeof raw === "string") provenanceAuthorDid = JSON.parse(raw).author_did ?? null;
+		} catch {}
+		const callerDid = this.opts.callerDid;
+		const anyItemRoleStr = collection.delete?.anyItem ?? "admin";
+		const isOwnItem = callerDid != null && provenanceAuthorDid != null && callerDid === provenanceAuthorDid;
+		const hasAnyItemRole = roleLevel(this.opts.callerRole) >= roleLevel(anyItemRoleStr);
+		if (!isOwnItem && !hasAnyItemRole) throw new AFSForbiddenError(fullPath, `insufficient permission to delete: role='${this.opts.callerRole ?? "guest"}'`);
+		if (!this.opts.instanceBackend.delete) return {};
+		const result = await this.opts.instanceBackend.delete(fullPath, options);
+		try {
+			await this.opts.instanceBackend.delete(canonicalSidecarPath);
+		} catch {}
+		return result;
+	}
+};
+
+//#endregion
+export { ReplicationResolver, computeReplicationMountPrefix };
+//# sourceMappingURL=replication-resolver.mjs.map

package/dist/session/replication-resolver.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"replication-resolver.mjs","names":[],"sources":["../../src/session/replication-resolver.ts"],"sourcesContent":["/**\n * ReplicationResolver — per-session replicated-collection fan-out gate.\n *\n * P1: write fan-out (role gate + copy + canonical + provenance sidecar) +\n *     delete gate (ownItem/anyItem + no cascade).\n * P2: read gate (readRole) + createSessionView wiring.\n *\n * See planning/did-integration/data-ownership-models/tasks.md §Phase 1/2.\n */\n\nimport type {\n  AFSContext,\n  AFSDeleteOptions,\n  AFSDeleteResult,\n  AFSListOptions,\n  AFSListResult,\n  AFSModule,\n  AFSReadOptions,\n  AFSReadResult,\n  AFSRoot,\n  AFSSearchOptions,\n  AFSSearchResult,\n  AFSStatOptions,\n  AFSStatResult,\n  AFSWriteEntryPayload,\n  AFSWriteOptions,\n  AFSWriteResult,\n  ReplicatedCollection,\n} from \"@aigne/afs\";\nimport { AFSForbiddenError } from \"@aigne/afs\";\nimport { roleLevel } from \"./role-level.js\";\nimport type { SettingsResolver } from \"./settings-resolver.js\";\n\n/**\n * Construction options for ReplicationResolver.\n * Injected at createSessionView (P2), not pre-built upstream.\n */\nexport interface ReplicationResolverOptions {\n  /**\n   * Parsed replicated-collection declarations from the blocklet manifest.\n   * Key = logical collection name; value = validated ReplicatedCollection.\n   */\n  collections: Record<string, ReplicatedCollection>;\n  /** The canonical backend (instance space, role:system). */\n  instanceBackend: AFSRoot;\n  /** The author-copy backend (user space, role:user), or null for anonymous callers. */\n  userBackend: AFSModule | null;\n  /** SettingsResolver reference for reading effective minRole/readRole overrides. */\n  settingsResolver: SettingsResolver | null;\n  /** Verified caller DID (from AFSContext.caller.did, never client-supplied). */\n  callerDid: string | undefined;\n  /** Caller role (daemon-folded single string from getCallerForSession). */\n  callerRole: string | undefined;\n  /** Owning session id — for event origin tagging in P2+. */\n  sessionId: string;\n  /** Instance DID used in copy-side sidecar canonical_ref. */\n  instanceDid?: string;\n  /**\n   * The path prefix this resolver is mounted at, WITHOUT leading slash.\n   * e.g. \"instance\" when mounted at /instance. Used to reconstruct the full\n   * canonical path from the sub-path the overlay system delivers.\n   * When omitted, computed automatically via computeReplicationMountPrefix().\n   */\n  mountPrefix?: string;\n}\n\n// ── Pure helper functions (exported for unit-testing) ──────────────────────\n\n/**\n * Compute the overlay mount prefix for a set of replicated collections.\n * Returns the LCP (longest common prefix) of the \"pre-collection\" segments\n * (everything before the collection-name segment, which sits just before `*`)\n * across all canonical patterns. This is the path at which a single\n * ReplicationResolver overlay is mounted in SessionUserAFS.\n *\n * Examples:\n *   { notes: { canonical: \"instance/notes/*\" } }\n *     → \"instance\"   (pre-collection = [\"instance\"])\n *   { posts: \"instance/app/posts/*\", comments: \"instance/app/comments/*\" }\n *     → \"instance/app\"  (LCP of [\"instance\",\"app\"] and [\"instance\",\"app\"])\n *   { notes: \"instance/notes/*\", posts: \"instance/app/posts/*\" }\n *     → \"instance\"  (LCP of [\"instance\"] and [\"instance\",\"app\"])\n */\nexport function computeReplicationMountPrefix(\n  collections: Record<string, ReplicatedCollection>,\n): string {\n  const entries = Object.values(collections);\n  if (entries.length === 0) throw new Error(\"No replicated collections declared\");\n\n  const parents: string[][] = entries.map(({ canonical }) => {\n    const segs = canonical.split(\"/\").filter((s) => s.length > 0);\n    const starIdx = segs.indexOf(\"*\");\n    if (starIdx < 1) throw new Error(`Invalid canonical pattern (no * or too short): ${canonical}`);\n    // Everything before the collection segment (at starIdx - 1)\n    return segs.slice(0, starIdx - 1);\n  });\n\n  const first = parents[0]!;\n  let lcpLen = first.length;\n  for (let k = 1; k < parents.length; k++) {\n    const p = parents[k]!;\n    let len = 0;\n    while (len < lcpLen && len < p.length && first[len] === p[len]) len++;\n    lcpLen = len;\n  }\n\n  // Must resolve to at least \"instance\"\n  const prefix = first.slice(0, lcpLen).join(\"/\");\n  return prefix || \"instance\";\n}\n\n/**\n * Derive the sidecar path for a given item path, using the pattern to determine\n * the injection point. Injects `.provenance/` before the collection segment\n * (segment at firstStarIndex - 1 of the pattern).\n *\n * Examples:\n *   pattern=\"instance/app/posts/*\",         item=\"/instance/app/posts/p1\"\n *     → \"/instance/app/.provenance/posts/p1\"\n *   pattern=\"instance/app/posts/{star}/comments/{star}\", item=\"/instance/app/posts/p1/comments/c1\"\n *     → \"/instance/app/.provenance/posts/p1/comments/c1\"\n *   Works for copy paths too: item=\"/user/app/posts/p1\"\n *     → \"/user/app/.provenance/posts/p1\"\n */\nexport function deriveSidecarPath(pattern: string, fullItemPath: string): string {\n  const patternSegs = pattern.split(\"/\").filter((s) => s.length > 0);\n  const firstStarIdx = patternSegs.indexOf(\"*\");\n  if (firstStarIdx < 1) throw new Error(`Invalid pattern (no * or too short): ${pattern}`);\n\n  // segments before the first * = static prefix\n  // e.g. [\"instance\",\"app\",\"posts\"] for \"instance/app/posts/*\"\n  const preCollectionLen = firstStarIdx - 1; // count of segments before collection\n  const collectionSeg = patternSegs[firstStarIdx - 1]; // e.g. \"posts\"\n\n  const normPath = fullItemPath.replace(/^\\//, \"\");\n  const itemSegs = normPath.split(\"/\").filter((s) => s.length > 0);\n\n  // Everything from firstStarIdx onwards is the item tail\n  const itemTail = itemSegs.slice(firstStarIdx);\n  // Segments from the actual path before the collection (may be \"user\" or \"instance\")\n  const preCollectionFromPath = itemSegs.slice(0, preCollectionLen);\n\n  return `/${[...preCollectionFromPath, \".provenance\", collectionSeg, ...itemTail].join(\"/\")}`;\n}\n\n/**\n * Find the best-matching collection for a given (normalized, no-leading-slash) item path.\n * Uses longest-match: the pattern that consumes the most path segments with static segments wins.\n * Returns null if no collection matches.\n */\nexport function matchCollections(\n  collections: Record<string, ReplicatedCollection>,\n  normalizedPath: string,\n): { name: string; collection: ReplicatedCollection } | null {\n  const itemSegs = normalizedPath\n    .replace(/^\\//, \"\")\n    .split(\"/\")\n    .filter((s) => s.length > 0);\n\n  let best: { name: string; collection: ReplicatedCollection; score: number } | null = null;\n\n  for (const [name, collection] of Object.entries(collections)) {\n    const patternSegs = collection.canonical.split(\"/\").filter((s) => s.length > 0);\n    const score = tryMatchPattern(patternSegs, itemSegs);\n    if (score !== null && (best === null || score > best.score)) {\n      best = { name, collection, score };\n    }\n  }\n\n  return best ? { name: best.name, collection: best.collection } : null;\n}\n\n/**\n * Try to match a pattern (segment array) against an item path (segment array).\n * Returns a score (higher = more specific) on match, or null on mismatch.\n * Rules:\n *   - Static segments must match exactly.\n *   - Non-terminal `*` matches exactly one segment.\n *   - Terminal `*` matches one or more remaining segments (item + subtree).\n */\nfunction tryMatchPattern(patternSegs: string[], itemSegs: string[]): number | null {\n  let pIdx = 0;\n  let iIdx = 0;\n  let score = 0;\n\n  while (pIdx < patternSegs.length) {\n    const pSeg = patternSegs[pIdx];\n\n    if (pSeg === \"*\") {\n      if (pIdx === patternSegs.length - 1) {\n        // Terminal *: must have at least one remaining item segment\n        if (iIdx >= itemSegs.length) return null;\n        // Score: +100 per non-star segment already consumed, +10 for the star\n        score += 10 + (itemSegs.length - iIdx - 1);\n        return score;\n      }\n      // Non-terminal *: match exactly one item segment\n      if (iIdx >= itemSegs.length) return null;\n      iIdx++;\n      score += 100;\n    } else {\n      // Static segment: exact match required\n      if (iIdx >= itemSegs.length || itemSegs[iIdx] !== pSeg) return null;\n      iIdx++;\n      score += 1000;\n    }\n    pIdx++;\n  }\n\n  return null; // valid patterns always end with *, so this is unreachable\n}\n\n/**\n * Match a path against canonical collection patterns OR their derived sidecar\n * mirror patterns (`.provenance/` prefixed). Used for the read gate (P2).\n *\n * Sidecar matching: strips the `.provenance` segment from the path and checks\n * the resulting path against the canonical patterns.\n */\nfunction matchCollectionsForRead(\n  collections: Record<string, ReplicatedCollection>,\n  normalizedPath: string,\n): { name: string; collection: ReplicatedCollection } | null {\n  // 1. Direct canonical match\n  const direct = matchCollections(collections, normalizedPath);\n  if (direct) return direct;\n\n  // 2. Sidecar match: strip `.provenance` segment and retry\n  const segs = normalizedPath.split(\"/\").filter((s) => s.length > 0);\n  const provenanceIdx = segs.indexOf(\".provenance\");\n  if (provenanceIdx < 0) return null;\n  const withoutProvenance = [\n    ...segs.slice(0, provenanceIdx),\n    ...segs.slice(provenanceIdx + 1),\n  ].join(\"/\");\n  return matchCollections(collections, withoutProvenance);\n}\n\n/**\n * Check that a path contains no `..` or empty segments (path safety).\n * Returns the normalized path (no leading `/`) on success.\n * Throws AFSForbiddenError on suspicious input.\n */\nfunction assertPathSafe(path: string): string {\n  const norm = path.replace(/^\\//, \"\");\n  const segs = norm.split(\"/\");\n  for (const seg of segs) {\n    if (seg === \"\" || seg === \"..\") {\n      throw new AFSForbiddenError(\n        path,\n        `path contains unsafe segment: \"${seg === \"\" ? \"(empty)\" : seg}\"`,\n      );\n    }\n  }\n  return norm;\n}\n\n/**\n * Convert a canonical `/instance/...` path to the author-copy `/user/...` path.\n * Replaces the first segment (`instance`) with `user`.\n * Returns the VIEW path (prefixed with /user) — callers must strip /user before\n * passing to userBackend, since userBackend operates at provider-relative paths.\n */\nfunction canonicalToViewCopyPath(canonicalPath: string): string {\n  const norm = canonicalPath.replace(/^\\//, \"\");\n  const slashIdx = norm.indexOf(\"/\");\n  if (slashIdx < 0) return \"/user\";\n  return `/user${norm.slice(slashIdx)}`;\n}\n\n/**\n * Strip the `/user` view prefix from a copy view path to get the\n * provider-relative path for userBackend calls.\n */\nfunction copyViewToProviderPath(viewPath: string): string {\n  if (viewPath === \"/user\") return \"/\";\n  if (viewPath.startsWith(\"/user/\")) return viewPath.slice(\"/user\".length);\n  return viewPath;\n}\n\n// ── ReplicationResolver ────────────────────────────────────────────────────\n\n/**\n * ReplicationResolver intercepts writes and deletes to replicated-collection\n * paths, enforces role gates, and fans out to both canonical (instanceBackend)\n * and author copy (userBackend) with provenance sidecars.\n *\n * Mounted as a SessionUserAFS overlay at `/${mountPrefix}` (typically\n * /instance). Receives SUB-PATHS (after prefix stripping by the overlay\n * system) and reconstructs full paths internally using mountPrefix.\n *\n * P1: write + delete implemented.\n * P2: read gate (readRole) + createSessionView wiring.\n */\nexport class ReplicationResolver implements AFSModule {\n  readonly name: string;\n  private readonly mountPrefix: string;\n\n  constructor(private readonly opts: ReplicationResolverOptions) {\n    this.name = `replication-resolver:${opts.sessionId}`;\n    this.mountPrefix = opts.mountPrefix ?? computeReplicationMountPrefix(opts.collections);\n  }\n\n  // ── Path helpers ──────────────────────────────────────────────────────────\n\n  /**\n   * Reconstruct the full canonical path from the sub-path the overlay delivers.\n   * The overlay at `/${mountPrefix}` strips the prefix, leaving e.g. `/notes/n1`\n   * from `/instance/notes/n1`. We prepend mountPrefix to restore the full path.\n   */\n  private toFullPath(sub: string): string {\n    const s = sub.startsWith(\"/\") ? sub : `/${sub}`;\n    return `/${this.mountPrefix}${s}`;\n  }\n\n  // ── Helpers ──────────────────────────────────────────────────────────────\n\n  private async getEffectiveMinRole(\n    collectionName: string,\n    collection: ReplicatedCollection,\n  ): Promise<string> {\n    if (this.opts.settingsResolver) {\n      try {\n        const result = await this.opts.settingsResolver.read(\n          `/${collectionName}/minRole.json/value`,\n        );\n        const v = result.data?.content;\n        if (typeof v === \"string\" && v.length > 0) return v;\n      } catch {\n        // No operator override — fall through to manifest default\n      }\n    }\n    return collection.minRole ?? \"member\";\n  }\n\n  private async getEffectiveReadRole(\n    collectionName: string,\n    collection: ReplicatedCollection,\n  ): Promise<string> {\n    if (this.opts.settingsResolver) {\n      try {\n        const result = await this.opts.settingsResolver.read(\n          `/${collectionName}/readRole.json/value`,\n        );\n        const v = result.data?.content;\n        if (typeof v === \"string\" && v.length > 0) return v;\n      } catch {\n        // No operator override — fall through to manifest default\n      }\n    }\n    return collection.readRole ?? \"guest\";\n  }\n\n  // ── AFSModule.read ────────────────────────────────────────────────────────\n\n  async read(path: string, options?: AFSReadOptions): Promise<AFSReadResult> {\n    const fullPath = this.toFullPath(path);\n    const normPath = assertPathSafe(fullPath);\n\n    // Check if the path matches a replicated collection (canonical or sidecar)\n    const match = matchCollectionsForRead(this.opts.collections, normPath);\n    if (match) {\n      const effectiveReadRole = await this.getEffectiveReadRole(match.name, match.collection);\n      // guest (default) → roleLevel 0 ≤ any caller level → zero-overhead pass-through\n      if (roleLevel(this.opts.callerRole) < roleLevel(effectiveReadRole)) {\n        throw new AFSForbiddenError(\n          fullPath,\n          `role '${this.opts.callerRole ?? \"guest\"}' is below readRole '${effectiveReadRole}'`,\n        );\n      }\n    }\n    // Both matching (passed gate) and non-matching paths delegate to instanceBackend\n    if (!this.opts.instanceBackend.read) {\n      throw new AFSForbiddenError(fullPath, \"instanceBackend does not support read\");\n    }\n    return this.opts.instanceBackend.read(fullPath, options);\n  }\n\n  // ── AFSModule.list ────────────────────────────────────────────────────────\n\n  async list(path: string, options?: AFSListOptions): Promise<AFSListResult> {\n    const fullPath = this.toFullPath(path);\n    const normPath = assertPathSafe(fullPath);\n\n    const match = matchCollectionsForRead(this.opts.collections, normPath);\n    if (match) {\n      const effectiveReadRole = await this.getEffectiveReadRole(match.name, match.collection);\n      if (roleLevel(this.opts.callerRole) < roleLevel(effectiveReadRole)) {\n        throw new AFSForbiddenError(\n          fullPath,\n          `role '${this.opts.callerRole ?? \"guest\"}' is below readRole '${effectiveReadRole}'`,\n        );\n      }\n    }\n    if (!this.opts.instanceBackend.list) {\n      throw new AFSForbiddenError(fullPath, \"instanceBackend does not support list\");\n    }\n    return this.opts.instanceBackend.list(fullPath, options);\n  }\n\n  // ── AFSModule.stat ────────────────────────────────────────────────────────\n\n  async stat(path: string, options?: AFSStatOptions): Promise<AFSStatResult> {\n    const fullPath = this.toFullPath(path);\n    const normPath = assertPathSafe(fullPath);\n\n    const match = matchCollectionsForRead(this.opts.collections, normPath);\n    if (match) {\n      const effectiveReadRole = await this.getEffectiveReadRole(match.name, match.collection);\n      if (roleLevel(this.opts.callerRole) < roleLevel(effectiveReadRole)) {\n        throw new AFSForbiddenError(\n          fullPath,\n          `role '${this.opts.callerRole ?? \"guest\"}' is below readRole '${effectiveReadRole}'`,\n        );\n      }\n    }\n    if (!this.opts.instanceBackend.stat) {\n      throw new AFSForbiddenError(fullPath, \"instanceBackend does not support stat\");\n    }\n    return this.opts.instanceBackend.stat(fullPath, options);\n  }\n\n  // ── AFSModule.search ──────────────────────────────────────────────────────\n\n  async search(path: string, query: string, options?: AFSSearchOptions): Promise<AFSSearchResult> {\n    const fullPath = this.toFullPath(path);\n    const normPath = assertPathSafe(fullPath);\n\n    const match = matchCollectionsForRead(this.opts.collections, normPath);\n    if (match) {\n      const effectiveReadRole = await this.getEffectiveReadRole(match.name, match.collection);\n      if (roleLevel(this.opts.callerRole) < roleLevel(effectiveReadRole)) {\n        throw new AFSForbiddenError(\n          fullPath,\n          `role '${this.opts.callerRole ?? \"guest\"}' is below readRole '${effectiveReadRole}'`,\n        );\n      }\n    }\n    if (!this.opts.instanceBackend.search) {\n      throw new AFSForbiddenError(fullPath, \"instanceBackend does not support search\");\n    }\n    return this.opts.instanceBackend.search(fullPath, query, options);\n  }\n\n  // ── AFSModule.write ───────────────────────────────────────────────────────\n\n  async write(\n    path: string,\n    content: AFSWriteEntryPayload,\n    options?: AFSWriteOptions,\n  ): Promise<AFSWriteResult> {\n    // 1. Reconstruct full path and path safety check\n    const fullPath = this.toFullPath(path);\n    const normPath = assertPathSafe(fullPath);\n\n    // 2. Find matching collection (longest-match)\n    const match = matchCollections(this.opts.collections, normPath);\n    if (!match) {\n      // Non-matching path: gate network clients (instance-write-authz §5.5 / L3).\n      // Internal writes (seeding / agents / CLI) carry no callerOrigin → pass through.\n      const ctx = options?.context as AFSContext | undefined;\n      if (ctx?.callerOrigin === \"network\") {\n        throw new AFSForbiddenError(\n          fullPath,\n          \"network clients cannot write non-replicated instance paths\",\n        );\n      }\n      if (!this.opts.instanceBackend.write) {\n        throw new AFSForbiddenError(fullPath, \"instanceBackend does not support write\");\n      }\n      return this.opts.instanceBackend.write(fullPath, content, options);\n    }\n\n    const { name: collectionName, collection } = match;\n\n    // 3. Role gate\n    const effectiveMinRole = await this.getEffectiveMinRole(collectionName, collection);\n    if (roleLevel(this.opts.callerRole) < roleLevel(effectiveMinRole)) {\n      throw new AFSForbiddenError(\n        fullPath,\n        `role '${this.opts.callerRole ?? \"guest\"}' is below minRole '${effectiveMinRole}'`,\n      );\n    }\n\n    // 4. Provenance data (author_did is from verified caller, never client-supplied)\n    const authorDid = this.opts.callerDid ?? null;\n    const publishedAt = new Date().toISOString();\n\n    const copyMode = collection.copy ?? \"mirror\";\n\n    // 5. Step ③: write author copy (skip if copy:none or no userBackend)\n    if (copyMode !== \"none\" && this.opts.userBackend !== null && this.opts.userBackend.write) {\n      // View path: /user/notes/n1 (mirrors canonical /instance/notes/n1)\n      const copyViewPath = canonicalToViewCopyPath(fullPath);\n      // Provider-relative path (strip /user prefix for the userBackend provider)\n      const copyProviderPath = copyViewToProviderPath(copyViewPath);\n\n      // Author copy: unconditional (no ifMatch)\n      await this.opts.userBackend.write(copyProviderPath, content);\n\n      // Author-side sidecar (uses VIEW path for deriveSidecarPath, then strips /user)\n      const copySidecarViewPath = deriveSidecarPath(collection.canonical, copyViewPath);\n      const copySidecarProviderPath = copyViewToProviderPath(copySidecarViewPath);\n      const copySidecar = {\n        canonical_ref: {\n          instance_did: this.opts.instanceDid ?? \"\",\n          // Path relative to instance root (strip \"instance/\" prefix)\n          path: normPath.replace(/^instance\\//, \"\"),\n        },\n        published_at: publishedAt,\n      };\n      await this.opts.userBackend.write(copySidecarProviderPath, {\n        content: JSON.stringify(copySidecar),\n      });\n    }\n\n    // 6. Step ④: write canonical (with caller's ifMatch if provided)\n    if (!this.opts.instanceBackend.write) {\n      throw new AFSForbiddenError(fullPath, \"instanceBackend does not support write\");\n    }\n    const result = await this.opts.instanceBackend.write(fullPath, content, options);\n\n    // Canonical-side sidecar (after canonical write succeeds)\n    const canonicalSidecarPath = deriveSidecarPath(collection.canonical, fullPath);\n    const canonicalSidecar = {\n      // copy:none + no callerDid (true anonymous) → null; otherwise use verified did\n      author_did: authorDid,\n      published_at: publishedAt,\n    };\n    await this.opts.instanceBackend.write(canonicalSidecarPath, {\n      content: JSON.stringify(canonicalSidecar),\n    });\n\n    return result;\n  }\n\n  // ── AFSModule.delete ──────────────────────────────────────────────────────\n\n  async delete(path: string, options?: AFSDeleteOptions): Promise<AFSDeleteResult> {\n    // 1. Reconstruct full path and path safety check\n    const fullPath = this.toFullPath(path);\n    const normPath = assertPathSafe(fullPath);\n\n    // 2. Find matching collection\n    const match = matchCollections(this.opts.collections, normPath);\n    if (!match) {\n      // Non-matching path: pass-through to instanceBackend\n      if (!this.opts.instanceBackend.delete) {\n        return {};\n      }\n      return this.opts.instanceBackend.delete(fullPath, options);\n    }\n\n    const { collection } = match;\n\n    // 3. Read canonical sidecar to get author_did for ownItem gate\n    const canonicalSidecarPath = deriveSidecarPath(collection.canonical, fullPath);\n    let provenanceAuthorDid: string | null = null;\n\n    if (this.opts.instanceBackend.read) {\n      try {\n        const sidecarResult = await this.opts.instanceBackend.read(canonicalSidecarPath);\n        const raw = sidecarResult.data?.content;\n        if (typeof raw === \"string\") {\n          const sidecar = JSON.parse(raw) as { author_did?: string | null };\n          provenanceAuthorDid = sidecar.author_did ?? null;\n        }\n      } catch {\n        // Sidecar missing — author unknown, ownItem gate cannot be satisfied\n      }\n    }\n\n    // 4. Delete gate\n    const callerDid = this.opts.callerDid;\n    const anyItemRoleStr = collection.delete?.anyItem ?? \"admin\";\n\n    const isOwnItem =\n      callerDid != null && provenanceAuthorDid != null && callerDid === provenanceAuthorDid;\n    const hasAnyItemRole = roleLevel(this.opts.callerRole) >= roleLevel(anyItemRoleStr);\n\n    if (!isOwnItem && !hasAnyItemRole) {\n      throw new AFSForbiddenError(\n        fullPath,\n        `insufficient permission to delete: role='${this.opts.callerRole ?? \"guest\"}'`,\n      );\n    }\n\n    // 5. Delete canonical item (no cascade — author copy is untouched)\n    if (!this.opts.instanceBackend.delete) {\n      return {};\n    }\n    const result = await this.opts.instanceBackend.delete(fullPath, options);\n\n    // Delete canonical-side sidecar (best-effort; failure is benign)\n    try {\n      await this.opts.instanceBackend.delete(canonicalSidecarPath);\n    } catch {\n      // Sidecar already gone or delete unsupported — benign\n    }\n\n    return result;\n  }\n}\n"],"mappings":"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"}

package/dist/session/role-level.cjs

@@ -0,0 +1,36 @@
+
+//#region src/session/role-level.ts
+/**
+* roleLevel — ordered numeric representation of the four ARC caller roles.
+*
+* Guest (0) is the fail-closed floor: undefined / unknown / empty → 0.
+* This mirrors SettingsResolver's "unknown role → non-admin" fail-closed rule,
+* generalised to a four-level ordinal. See design.md §5.5.
+*/
+/**
+* Map a caller role string to its numeric ordinal.
+* Uses a switch rather than an object lookup to guard against prototype pollution.
+*
+* guest < member < admin < owner (0 < 1 < 2 < 3).
+* Any unrecognised or absent value returns 0 (= guest / fail-closed).
+*/
+function roleLevel(r) {
+	switch (r) {
+		case "guest": return 0;
+		case "member": return 1;
+		case "admin": return 2;
+		case "owner": return 3;
+		default: return 0;
+	}
+}
+/**
+* Compare two role strings by level.
+* Returns negative if a < b, 0 if equal, positive if a > b.
+*/
+function compareRole(a, b) {
+	return roleLevel(a) - roleLevel(b);
+}
+
+//#endregion
+exports.compareRole = compareRole;
+exports.roleLevel = roleLevel;

package/dist/session/role-level.d.cts

@@ -0,0 +1,24 @@
+//#region src/session/role-level.d.ts
+/**
+ * roleLevel — ordered numeric representation of the four ARC caller roles.
+ *
+ * Guest (0) is the fail-closed floor: undefined / unknown / empty → 0.
+ * This mirrors SettingsResolver's "unknown role → non-admin" fail-closed rule,
+ * generalised to a four-level ordinal. See design.md §5.5.
+ */
+/**
+ * Map a caller role string to its numeric ordinal.
+ * Uses a switch rather than an object lookup to guard against prototype pollution.
+ *
+ * guest < member < admin < owner (0 < 1 < 2 < 3).
+ * Any unrecognised or absent value returns 0 (= guest / fail-closed).
+ */
+declare function roleLevel(r?: string): number;
+/**
+ * Compare two role strings by level.
+ * Returns negative if a < b, 0 if equal, positive if a > b.
+ */
+declare function compareRole(a?: string, b?: string): number;
+//#endregion
+export { compareRole, roleLevel };
+//# sourceMappingURL=role-level.d.cts.map

package/dist/session/role-level.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-level.d.cts","names":[],"sources":["../../src/session/role-level.ts"],"mappings":";;AAeA;;;;;AAmBA;;;;;;;;iBAnBgB,SAAA,CAAU,CAAA;;;;;iBAmBV,WAAA,CAAY,CAAA,WAAY,CAAA"}

package/dist/session/role-level.d.mts

@@ -0,0 +1,24 @@
+//#region src/session/role-level.d.ts
+/**
+ * roleLevel — ordered numeric representation of the four ARC caller roles.
+ *
+ * Guest (0) is the fail-closed floor: undefined / unknown / empty → 0.
+ * This mirrors SettingsResolver's "unknown role → non-admin" fail-closed rule,
+ * generalised to a four-level ordinal. See design.md §5.5.
+ */
+/**
+ * Map a caller role string to its numeric ordinal.
+ * Uses a switch rather than an object lookup to guard against prototype pollution.
+ *
+ * guest < member < admin < owner (0 < 1 < 2 < 3).
+ * Any unrecognised or absent value returns 0 (= guest / fail-closed).
+ */
+declare function roleLevel(r?: string): number;
+/**
+ * Compare two role strings by level.
+ * Returns negative if a < b, 0 if equal, positive if a > b.
+ */
+declare function compareRole(a?: string, b?: string): number;
+//#endregion
+export { compareRole, roleLevel };
+//# sourceMappingURL=role-level.d.mts.map

package/dist/session/role-level.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-level.d.mts","names":[],"sources":["../../src/session/role-level.ts"],"mappings":";;AAeA;;;;;AAmBA;;;;;;;;iBAnBgB,SAAA,CAAU,CAAA;;;;;iBAmBV,WAAA,CAAY,CAAA,WAAY,CAAA"}

package/dist/session/role-level.mjs

@@ -0,0 +1,35 @@
+//#region src/session/role-level.ts
+/**
+* roleLevel — ordered numeric representation of the four ARC caller roles.
+*
+* Guest (0) is the fail-closed floor: undefined / unknown / empty → 0.
+* This mirrors SettingsResolver's "unknown role → non-admin" fail-closed rule,
+* generalised to a four-level ordinal. See design.md §5.5.
+*/
+/**
+* Map a caller role string to its numeric ordinal.
+* Uses a switch rather than an object lookup to guard against prototype pollution.
+*
+* guest < member < admin < owner (0 < 1 < 2 < 3).
+* Any unrecognised or absent value returns 0 (= guest / fail-closed).
+*/
+function roleLevel(r) {
+	switch (r) {
+		case "guest": return 0;
+		case "member": return 1;
+		case "admin": return 2;
+		case "owner": return 3;
+		default: return 0;
+	}
+}
+/**
+* Compare two role strings by level.
+* Returns negative if a < b, 0 if equal, positive if a > b.
+*/
+function compareRole(a, b) {
+	return roleLevel(a) - roleLevel(b);
+}
+
+//#endregion
+export { compareRole, roleLevel };
+//# sourceMappingURL=role-level.mjs.map

package/dist/session/role-level.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"role-level.mjs","names":[],"sources":["../../src/session/role-level.ts"],"sourcesContent":["/**\n * roleLevel — ordered numeric representation of the four ARC caller roles.\n *\n * Guest (0) is the fail-closed floor: undefined / unknown / empty → 0.\n * This mirrors SettingsResolver's \"unknown role → non-admin\" fail-closed rule,\n * generalised to a four-level ordinal. See design.md §5.5.\n */\n\n/**\n * Map a caller role string to its numeric ordinal.\n * Uses a switch rather than an object lookup to guard against prototype pollution.\n *\n * guest < member < admin < owner (0 < 1 < 2 < 3).\n * Any unrecognised or absent value returns 0 (= guest / fail-closed).\n */\nexport function roleLevel(r?: string): number {\n  switch (r) {\n    case \"guest\":\n      return 0;\n    case \"member\":\n      return 1;\n    case \"admin\":\n      return 2;\n    case \"owner\":\n      return 3;\n    default:\n      return 0;\n  }\n}\n\n/**\n * Compare two role strings by level.\n * Returns negative if a < b, 0 if equal, positive if a > b.\n */\nexport function compareRole(a?: string, b?: string): number {\n  return roleLevel(a) - roleLevel(b);\n}\n"],"mappings":";;;;;;;;;;;;;;;AAeA,SAAgB,UAAU,GAAoB;AAC5C,SAAQ,GAAR;EACE,KAAK,QACH,QAAO;EACT,KAAK,SACH,QAAO;EACT,KAAK,QACH,QAAO;EACT,KAAK,QACH,QAAO;EACT,QACE,QAAO;;;;;;;AAQb,SAAgB,YAAY,GAAY,GAAoB;AAC1D,QAAO,UAAU,EAAE,GAAG,UAAU,EAAE"}