@codemem/server 0.29.2 → 0.30.0-alpha.1

package/dist/index.js

@@ -1,6 +1,6 @@
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { CODEMEM_CONFIG_ENV_OVERRIDES, DEFAULT_TIME_WINDOW_S, MemoryStore, VERSION, VERSION as VERSION$1, applyReplicationOps, buildBaseUrl, buildFilterClausesWithContext, buildRawEventEnvelopeFromHook, canonicalMemoryKind, cleanupNonces, coordinatorArchiveGroupAction, coordinatorCreateGroupAction, coordinatorCreateInviteAction, coordinatorDisableDeviceAction, coordinatorEnableDeviceAction, coordinatorImportInviteAction, coordinatorListBootstrapGrantsAction, coordinatorListDevicesAction, coordinatorListGroupsAction, coordinatorListJoinRequestsAction, coordinatorRemoveDeviceAction, coordinatorRenameDeviceAction, coordinatorRenameGroupAction, coordinatorReviewJoinRequestAction, coordinatorRevokeBootstrapGrantAction, coordinatorStatusSnapshot, coordinatorUnarchiveGroupAction, createCoordinatorReciprocalApproval, ensureDeviceIdentity, extractReplicationOps, fingerprintPublicKey, fromJson, getCodememConfigPath, getCodememEnvOverrides, getCoordinatorGroupPreference, getSemanticIndexDiagnostics, getSyncResetState, isSummaryLikeMemory, listCoordinatorJoinRequests, listMaintenanceJobs, listObserverProviderOptions, loadMemorySnapshotPageForPeer, loadReplicationOpsForPeer, lookupCoordinatorPeers, mergeAddresses, parseStrictInteger, probeAvailableCredentials, readCodememConfigFile, readCoordinatorSyncConfig, recordNonce, requestJson, resolveDbPath, runSyncPass, schema, stripJsonComments, stripPrivateObj, stripTrailingCommas, syncProjectAllowedByFilters, syncVisibilityAllowed, updatePeerAddresses, upsertCoordinatorGroupPreference, verifySignature, writeCodememConfigFile } from "@codemem/core";
+import { CODEMEM_CONFIG_ENV_OVERRIDES, DEFAULT_TIME_WINDOW_S, LOCAL_SYNC_CAPABILITY, MemoryStore, SYNC_SCOPE_QUERY_PARAM, VERSION, VERSION as VERSION$1, addSyncScopeToBoundary, applyReplicationOps, buildBaseUrl, buildFilterClausesWithContext, buildRawEventEnvelopeFromHook, canonicalMemoryKind, cleanupNonces, coordinatorArchiveGroupAction, coordinatorCreateGroupAction, coordinatorCreateInviteAction, coordinatorCreateScopeAction, coordinatorDisableDeviceAction, coordinatorEnableDeviceAction, coordinatorGrantScopeMembershipAction, coordinatorImportInviteAction, coordinatorListBootstrapGrantsAction, coordinatorListDevicesAction, coordinatorListGroupsAction, coordinatorListJoinRequestsAction, coordinatorListScopeMembershipsAction, coordinatorListScopesAction, coordinatorRemoveDeviceAction, coordinatorRenameDeviceAction, coordinatorRenameGroupAction, coordinatorReviewJoinRequestAction, coordinatorRevokeBootstrapGrantAction, coordinatorRevokeScopeMembershipAction, coordinatorStatusSnapshot, coordinatorUnarchiveGroupAction, coordinatorUpdateScopeAction, createCoordinatorReciprocalApproval, ensureDeviceIdentity, extractReplicationOps, filterReplicationOpsForSyncWithStatus, fingerprintPublicKey, fromJson, getCodememConfigPath, getCodememEnvOverrides, getCoordinatorGroupPreference, getSemanticIndexDiagnostics, getSyncResetState, isSummaryLikeMemory, listCoordinatorJoinRequests, listInboundScopeRejections, listMaintenanceJobs, listObserverProviderOptions, loadMemorySnapshotPageForPeer, loadReplicationOpsForPeer, lookupCoordinatorPeers, mergeAddresses, negotiateSyncCapability, normalizeSyncCapability, parseStrictInteger, parseSyncScopeRequest, personalScopeGrantStatusForPeer, probeAvailableCredentials, readCodememConfigFile, readCoordinatorSyncConfig, recordNonce, rejectInboundScopeFailures, requestJson, resolveDbPath, runSyncPass, schema, stripJsonComments, stripPrivateObj, stripTrailingCommas, summarizeInboundScopeRejections, syncScopeResetRequiredPayload, updatePeerAddresses, upsertCoordinatorGroupPreference, verifySignature, writeCodememConfigFile } from "@codemem/core";
 import { serveStatic } from "@hono/node-server/serve-static";
 import { Hono } from "hono";
 import { createMiddleware } from "hono/factory";
@@ -1526,6 +1526,51 @@ function coordinatorAdminStatusPayload(config = readCoordinatorSyncConfig()) {
 		has_groups: hasGroups
 	};
 }
+function coordinatorAdminUnavailable(status) {
+	if (status.readiness === "not_configured") return {
+		body: {
+			error: "coordinator_not_configured",
+			status
+		},
+		httpStatus: 400
+	};
+	if (!status.has_admin_secret) return {
+		body: {
+			error: "coordinator_admin_secret_missing",
+			status
+		},
+		httpStatus: 400
+	};
+	return null;
+}
+async function parseViewerJsonBody(c, options = {}) {
+	const raw = await c.req.text();
+	if (!raw.trim()) return options.allowEmpty ? {} : null;
+	try {
+		const parsed = JSON.parse(raw);
+		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+		return parsed;
+	} catch {
+		return null;
+	}
+}
+function optionalViewerString(body, key) {
+	const value = body[key];
+	if (value == null) return null;
+	return String(value).trim() || null;
+}
+function optionalViewerNumber(body, key) {
+	const value = body[key];
+	if (value == null || value === "") return null;
+	const number = typeof value === "number" ? value : Number(value);
+	return Number.isFinite(number) ? Math.trunc(number) : NaN;
+}
+function coordinatorAdminMutationStatus(message) {
+	if (message.includes("scope_not_found") || message.includes("membership_not_found") || message.includes("group_not_found") || message.includes("Group not found") || message.includes("Scope not found") || message.includes("device_not_enrolled_for_scope_group") || message.includes("device must be enrolled")) return 404;
+	if (message.includes("not active") || message.includes("scope_not_active") || message.includes("group_archived") || message.includes("Group is archived")) return 409;
+	if (message.includes("Remote coordinator request failed (5") || message.includes("fetch failed") || message.includes("network") || message.includes("timed out")) return 502;
+	return 400;
+}
 function pairingAdvertiseAddresses(config = readCoordinatorSyncConfig()) {
 	const advertise = String(config.syncAdvertise || "auto").trim().toLowerCase();
 	if (advertise && advertise !== "auto" && advertise !== "default") return mergeAddresses([], String(config.syncAdvertise || "").split(",").map((item) => item.trim()).filter(Boolean));
@@ -1899,20 +1944,6 @@ function claimLegacyDeviceAsSelf(store, originDeviceId) {
 			     )`).run(store.actorId, store.actorDisplayName, personalWorkspaceId, deviceId, store.actorId, LEGACY_SYNC_ACTOR_DISPLAY_NAME, LEGACY_SHARED_WORKSPACE_ID);
 	return Number(result.changes ?? 0);
 }
-function peerClaimedLocalActor(store, peerDeviceId) {
-	const row = store.db.prepare("SELECT claimed_local_actor FROM sync_peers WHERE peer_device_id = ? LIMIT 1").get(peerDeviceId);
-	return Boolean(row?.claimed_local_actor);
-}
-function parseOpPayload(op) {
-	if (!op.payload_json || !String(op.payload_json).trim()) return null;
-	try {
-		const parsed = JSON.parse(op.payload_json);
-		if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
-		return parsed;
-	} catch {
-		return null;
-	}
-}
 function redactCoordinatorStatus(coordinator, showDiag) {
 	if (showDiag) return coordinator;
 	const discovered = Array.isArray(coordinator.discovered_devices) ? coordinator.discovered_devices.map((item) => {
@@ -2076,30 +2107,29 @@ async function acceptDiscoveredPeer(store, input) {
 		};
 	})();
 }
-function filterOpsForPeer(store, peerDeviceId, ops) {
-	const filters = readPeerProjectFilters(store, peerDeviceId);
-	const allowPrivate = peerClaimedLocalActor(store, peerDeviceId);
-	const allowed = [];
-	let skipped = 0;
-	for (const op of ops) {
-		if (op.entity_type !== "memory_item") {
-			allowed.push(op);
-			continue;
-		}
-		const payload = parseOpPayload(op);
-		if (!allowPrivate && !syncVisibilityAllowed(payload)) {
-			skipped++;
-			continue;
-		}
-		if (!syncProjectAllowedByFilters(payload && typeof payload.project === "string" ? payload.project : null, filters)) {
-			skipped++;
-			continue;
-		}
-		allowed.push(op);
-	}
+function filterOpsForPeer(store, peerDeviceId, localDeviceId, ops, options = {}) {
+	const [allowed, , skipped] = filterReplicationOpsForSyncWithStatus(store.db, ops, peerDeviceId, {
+		localDeviceId,
+		applyScopeFilter: options.applyScopeFilter
+	});
 	return {
 		allowed,
-		skipped
+		skipped: skipped?.skipped_count ?? 0
+	};
+}
+function claimedLocalActorScopeStatus(store, row) {
+	if (!row.claimed_local_actor) return null;
+	const peerDeviceId = String(row.peer_device_id ?? "").trim();
+	const actorId = String(row.actor_id ?? store.actorId).trim() || store.actorId;
+	const grant = personalScopeGrantStatusForPeer(store.db, {
+		peerDeviceId,
+		actorId
+	});
+	return {
+		scope_id: grant.scope_id,
+		authorized: grant.authorized,
+		state: grant.state,
+		action_required: !grant.authorized
 	};
 }
 /**
@@ -2107,12 +2137,13 @@ function filterOpsForPeer(store, peerDeviceId, ops) {
 * When showDiag is false, sensitive fields (fingerprint, last_error, addresses)
 * are redacted.
 */
-function mapPeerRow(store, row, showDiag, recentOpsByPeer) {
+function mapPeerRow(store, row, showDiag, recentOpsByPeer, scopeRejectionsByPeer) {
 	const peerId = String(row.peer_device_id ?? "");
 	const recentOps = recentOpsByPeer?.get(peerId) ?? {
 		in: 0,
 		out: 0
 	};
+	const scopeRejections = scopeRejectionsByPeer?.get(peerId);
 	return {
 		peer_device_id: row.peer_device_id,
 		name: row.name,
@@ -2124,6 +2155,7 @@ function mapPeerRow(store, row, showDiag, recentOpsByPeer) {
 		last_error: showDiag ? row.last_error : null,
 		has_error: Boolean(row.last_error),
 		claimed_local_actor: Boolean(row.claimed_local_actor),
+		claimed_local_actor_scope: showDiag ? claimedLocalActorScopeStatus(store, row) : null,
 		actor_id: row.actor_id ?? null,
 		actor_display_name: row.actor_display_name ?? null,
 		project_scope: { ...currentProjectScope(row, readPeerProjectFilters(store, String(row.peer_device_id ?? ""))) },
@@ -2131,10 +2163,27 @@ function mapPeerRow(store, row, showDiag, recentOpsByPeer) {
 			in: recentOps.in,
 			out: recentOps.out
 		},
+		scope_rejections: {
+			total: scopeRejections?.total ?? 0,
+			by_reason: scopeRejections?.by_reason ?? {},
+			last_at: scopeRejections?.last_at ?? null
+		},
 		discovered_via_coordinator_id: typeof row.discovered_via_coordinator_id === "string" ? row.discovered_via_coordinator_id : null,
 		discovered_via_group_id: typeof row.discovered_via_group_id === "string" ? row.discovered_via_group_id : null
 	};
 }
+var SYNC_SCOPE_REJECTION_WINDOW_SECONDS = 1440 * 60;
+function recentScopeRejectionsByPeer(store) {
+	const cutoff = (/* @__PURE__ */ new Date(Date.now() - SYNC_SCOPE_REJECTION_WINDOW_SECONDS * 1e3)).toISOString();
+	const summaries = summarizeInboundScopeRejections(store.db, { sinceIso: cutoff });
+	const map = /* @__PURE__ */ new Map();
+	for (const summary of summaries) {
+		const id = String(summary.peer_device_id ?? "").trim();
+		if (!id) continue;
+		map.set(id, summary);
+	}
+	return map;
+}
 var SYNC_DIRECTION_WINDOW_SECONDS = 1440 * 60;
 function recentPeerOps(store) {
 	const cutoff = (/* @__PURE__ */ new Date(Date.now() - SYNC_DIRECTION_WINDOW_SECONDS * 1e3)).toISOString();
@@ -2265,7 +2314,8 @@ function syncProtocolRoutes(getStore, opts = {}) {
 					device_id: deviceId,
 					protocol_version: SYNC_PROTOCOL_VERSION,
 					fingerprint,
-					sync_reset: syncReset
+					sync_reset: addSyncScopeToBoundary(syncReset, null),
+					sync_capability: LOCAL_SYNC_CAPABILITY
 				});
 			} catch {
 				return c.json({ error: "internal_error" }, 500);
@@ -2280,6 +2330,9 @@ function syncProtocolRoutes(getStore, opts = {}) {
 		if (limited) return limited;
 		const peerDeviceId = auth.deviceId;
 		try {
+			const rawScopeId = c.req.query(SYNC_SCOPE_QUERY_PARAM);
+			const scopeRequest = parseSyncScopeRequest(rawScopeId, rawScopeId !== void 0);
+			if (!scopeRequest.ok) return c.json(syncScopeResetRequiredPayload(getSyncResetState(store.db), scopeRequest.reason, LOCAL_SYNC_CAPABILITY), 409);
 			const since = c.req.query("since") ?? null;
 			const rawLimit = Number.parseInt(c.req.query("limit") ?? "200", 10);
 			const rawGeneration = c.req.query("generation");
@@ -2298,12 +2351,15 @@ function syncProtocolRoutes(getStore, opts = {}) {
 			});
 			if (result.reset_required) return c.json({
 				error: "reset_required",
-				...result.reset
+				sync_capability: LOCAL_SYNC_CAPABILITY,
+				...addSyncScopeToBoundary(result.reset, scopeRequest.scope_id)
 			}, 409);
 			const { ops, nextCursor, boundary } = result;
-			const filtered = filterOpsForPeer(store, peerDeviceId, ops);
+			const filtered = filterOpsForPeer(store, peerDeviceId, localDeviceId, ops);
 			return c.json({
 				reset_required: false,
+				sync_capability: LOCAL_SYNC_CAPABILITY,
+				scope_id: scopeRequest.scope_id,
 				generation: boundary.generation,
 				snapshot_id: boundary.snapshot_id,
 				baseline_cursor: boundary.baseline_cursor,
@@ -2343,6 +2399,9 @@ function syncProtocolRoutes(getStore, opts = {}) {
 			const limited = rateLimitedResponse(c, auth.deviceId, true);
 			if (limited) return limited;
 			try {
+				const rawScopeId = c.req.query(SYNC_SCOPE_QUERY_PARAM);
+				const scopeRequest = parseSyncScopeRequest(rawScopeId, rawScopeId !== void 0);
+				if (!scopeRequest.ok) return c.json(syncScopeResetRequiredPayload(getSyncResetState(store.db), scopeRequest.reason, LOCAL_SYNC_CAPABILITY), 409);
 				const rawGeneration = c.req.query("generation");
 				const generation = rawGeneration != null && rawGeneration.trim().length > 0 ? Number.parseInt(rawGeneration, 10) : null;
 				const snapshotId = c.req.query("snapshot_id") ?? null;
@@ -2361,10 +2420,12 @@ function syncProtocolRoutes(getStore, opts = {}) {
 					peerDeviceId: auth.deviceId
 				});
 				return c.json({
+					scope_id: scopeRequest.scope_id,
 					generation: result.boundary.generation,
 					snapshot_id: result.boundary.snapshot_id,
 					baseline_cursor: result.boundary.baseline_cursor,
 					retained_floor_cursor: result.boundary.retained_floor_cursor,
+					sync_capability: LOCAL_SYNC_CAPABILITY,
 					items: result.items,
 					next_page_token: result.nextPageToken,
 					has_more: result.hasMore
@@ -2393,6 +2454,8 @@ function syncProtocolRoutes(getStore, opts = {}) {
 		} catch {
 			return c.json({ error: "invalid_json" }, 400);
 		}
+		const scopeRequest = parseSyncScopeRequest(body.scope_id, Object.hasOwn(body, "scope_id"));
+		if (!scopeRequest.ok) return c.json(syncScopeResetRequiredPayload(getSyncResetState(store.db), scopeRequest.reason, LOCAL_SYNC_CAPABILITY), 409);
 		if (!Array.isArray(body.ops)) return c.json({ error: "invalid_ops" }, 400);
 		if (body.ops.length > MAX_SYNC_OPS) return c.json({ error: "too_many_ops" }, 413);
 		const normalizedOps = extractReplicationOps(body);
@@ -2402,11 +2465,26 @@ function syncProtocolRoutes(getStore, opts = {}) {
 			op_id: op.op_id
 		}, 400);
 		const [localDeviceId] = ensureDeviceIdentity(store.db, { keysDir: syncKeysDir() });
-		const filteredInbound = filterOpsForPeer(store, peerDeviceId, normalizedOps);
-		const result = applyReplicationOps(store.db, filteredInbound.allowed, localDeviceId, store.scanner);
+		const negotiatedCapability = negotiateSyncCapability(LOCAL_SYNC_CAPABILITY, normalizeSyncCapability(body.sync_capability));
+		const filtered = filterOpsForPeer(store, peerDeviceId, localDeviceId, normalizedOps, { applyScopeFilter: false });
+		const rejected = rejectInboundScopeFailures(store.db, normalizedOps, localDeviceId, {
+			enabled: negotiatedCapability !== "unsupported",
+			peerDeviceId
+		});
+		if (rejected) return c.json({
+			error: "scope_rejected",
+			reason: rejected.rejections[0]?.reason ?? "scope_mismatch",
+			rejections: rejected.rejections,
+			sync_capability: LOCAL_SYNC_CAPABILITY,
+			scope_id: scopeRequest.scope_id
+		}, 403);
+		const result = applyReplicationOps(store.db, filtered.allowed, localDeviceId, store.scanner);
+		const skipped = result.skipped + filtered.skipped;
 		return c.json({
 			...result,
-			skipped: result.skipped + filteredInbound.skipped
+			skipped,
+			sync_capability: LOCAL_SYNC_CAPABILITY,
+			scope_id: scopeRequest.scope_id
 		});
 	});
 	return app;
@@ -2509,8 +2587,9 @@ function syncRoutes(getStore, getSyncRuntimeStatus) {
 			}
 			const peerRows = traceSync("peerRows", () => store.db.prepare(PEERS_QUERY).all());
 			const recentOpsByPeer = traceSync("recentPeerOps", () => recentPeerOps(store));
+			const scopeRejectionsByPeer = traceSync("recentScopeRejectionsByPeer", () => recentScopeRejectionsByPeer(store));
 			const peersItems = peerRows.map((row) => {
-				const peer = mapPeerRow(store, row, showDiag, recentOpsByPeer);
+				const peer = mapPeerRow(store, row, showDiag, recentOpsByPeer, scopeRejectionsByPeer);
 				peer.status = peerStatus(peer);
 				return peer;
 			});
@@ -2523,7 +2602,10 @@ function syncRoutes(getStore, getSyncRuntimeStatus) {
 				started_at: schema.syncAttempts.started_at,
 				finished_at: schema.syncAttempts.finished_at,
 				ops_in: schema.syncAttempts.ops_in,
-				ops_out: schema.syncAttempts.ops_out
+				ops_out: schema.syncAttempts.ops_out,
+				local_sync_capability: schema.syncAttempts.local_sync_capability,
+				peer_sync_capability: schema.syncAttempts.peer_sync_capability,
+				negotiated_sync_capability: schema.syncAttempts.negotiated_sync_capability
 			}).from(schema.syncAttempts).orderBy(desc(schema.syncAttempts.finished_at)).limit(25).all());
 			const peerAddressMap = /* @__PURE__ */ new Map();
 			traceSync("peerAddressRows", () => store.db.prepare("SELECT peer_device_id, addresses_json FROM sync_peers").all()).forEach((peerRow) => {
@@ -2597,13 +2679,43 @@ function syncRoutes(getStore, getSyncRuntimeStatus) {
 			const showDiag = queryBool(c.req.query("includeDiagnostics"));
 			const rows = store.db.prepare(PEERS_QUERY).all();
 			const recentOpsByPeer = recentPeerOps(store);
-			const peers = rows.map((row) => mapPeerRow(store, row, showDiag, recentOpsByPeer));
+			const scopeRejectionsByPeer = recentScopeRejectionsByPeer(store);
+			const peers = rows.map((row) => mapPeerRow(store, row, showDiag, recentOpsByPeer, scopeRejectionsByPeer));
 			return c.json({
 				items: peers,
 				redacted: !showDiag
 			});
 		}
 	});
+	app.get("/api/sync/peers/:peer_device_id/scope-rejections", (c) => {
+		const store = getStore();
+		const peerDeviceId = String(c.req.param("peer_device_id") || "").trim();
+		if (!peerDeviceId) return c.json({ error: "missing_peer_device_id" }, 400);
+		const limit = queryInt(c.req.query("limit"), 100);
+		if (limit <= 0) return c.json({ error: "invalid_limit" }, 400);
+		const sinceMinutesRaw = queryInt(c.req.query("sinceMinutes"), 1440);
+		const sinceMinutes = Math.min(Math.max(sinceMinutesRaw, 0), 10 * 365 * 24 * 60);
+		const sinceIso = sinceMinutes > 0 ? (/* @__PURE__ */ new Date(Date.now() - sinceMinutes * 6e4)).toISOString() : void 0;
+		const records = listInboundScopeRejections(store.db, {
+			peerDeviceId,
+			sinceIso,
+			limit
+		});
+		const summary = summarizeInboundScopeRejections(store.db, {
+			peerDeviceId,
+			sinceIso
+		})[0] ?? {
+			peer_device_id: peerDeviceId,
+			total: 0,
+			by_reason: {},
+			last_at: null
+		};
+		return c.json({
+			peer_device_id: peerDeviceId,
+			summary,
+			items: records
+		});
+	});
 	app.get("/api/sync/actors", (c) => {
 		const store = getStore();
 		{
@@ -2629,7 +2741,10 @@ function syncRoutes(getStore, getSyncRuntimeStatus) {
 				started_at: schema.syncAttempts.started_at,
 				finished_at: schema.syncAttempts.finished_at,
 				ops_in: schema.syncAttempts.ops_in,
-				ops_out: schema.syncAttempts.ops_out
+				ops_out: schema.syncAttempts.ops_out,
+				local_sync_capability: schema.syncAttempts.local_sync_capability,
+				peer_sync_capability: schema.syncAttempts.peer_sync_capability,
+				negotiated_sync_capability: schema.syncAttempts.negotiated_sync_capability
 			}).from(schema.syncAttempts).orderBy(desc(schema.syncAttempts.finished_at)).limit(limit).all();
 			return c.json({ items: rows });
 		}
@@ -3052,7 +3167,7 @@ function syncRoutes(getStore, getSyncRuntimeStatus) {
 			return c.json({
 				error: message,
 				status
-			}, 502);
+			}, coordinatorAdminMutationStatus(message));
 		}
 	});
 	app.post("/api/coordinator/admin/groups", async (c) => {
@@ -3229,6 +3344,304 @@ function syncRoutes(getStore, getSyncRuntimeStatus) {
 			}, 400);
 		}
 	});
+	app.get("/api/coordinator/admin/groups/:group_id/scopes", async (c) => {
+		const config = readCoordinatorSyncConfig();
+		const status = coordinatorAdminStatusPayload(config);
+		const unavailable = coordinatorAdminUnavailable(status);
+		if (unavailable) return c.json(unavailable.body, unavailable.httpStatus);
+		const groupId = String(c.req.param("group_id") ?? "").trim();
+		if (!groupId) return c.json({
+			error: "group_id required",
+			status
+		}, 400);
+		try {
+			const items = await coordinatorListScopesAction({
+				groupId,
+				includeInactive: queryBool(c.req.query("include_inactive")),
+				remoteUrl: config.syncCoordinatorUrl || null,
+				adminSecret: config.syncCoordinatorAdminSecret || null
+			});
+			return c.json({
+				items,
+				group_id: groupId,
+				status
+			});
+		} catch (error) {
+			const message = error instanceof Error ? error.message : "unknown";
+			return c.json({
+				error: message,
+				status
+			}, coordinatorAdminMutationStatus(message));
+		}
+	});
+	app.post("/api/coordinator/admin/groups/:group_id/scopes", async (c) => {
+		const config = readCoordinatorSyncConfig();
+		const status = coordinatorAdminStatusPayload(config);
+		const unavailable = coordinatorAdminUnavailable(status);
+		if (unavailable) return c.json(unavailable.body, unavailable.httpStatus);
+		const groupId = String(c.req.param("group_id") ?? "").trim();
+		if (!groupId) return c.json({
+			error: "group_id required",
+			status
+		}, 400);
+		const body = await parseViewerJsonBody(c);
+		if (!body) return c.json({
+			error: "invalid json",
+			status
+		}, 400);
+		const scopeId = optionalViewerString(body, "scope_id");
+		const label = optionalViewerString(body, "label");
+		const membershipEpoch = optionalViewerNumber(body, "membership_epoch");
+		if (!scopeId || !label) return c.json({
+			error: "scope_id and label required",
+			status
+		}, 400);
+		if (Number.isNaN(membershipEpoch)) return c.json({
+			error: "membership_epoch must be number",
+			status
+		}, 400);
+		try {
+			const scope = await coordinatorCreateScopeAction({
+				groupId,
+				scopeId,
+				label,
+				kind: optionalViewerString(body, "kind"),
+				authorityType: optionalViewerString(body, "authority_type"),
+				coordinatorId: optionalViewerString(body, "coordinator_id"),
+				manifestIssuerDeviceId: optionalViewerString(body, "manifest_issuer_device_id"),
+				membershipEpoch,
+				manifestHash: optionalViewerString(body, "manifest_hash"),
+				status: optionalViewerString(body, "status"),
+				remoteUrl: config.syncCoordinatorUrl || null,
+				adminSecret: config.syncCoordinatorAdminSecret || null
+			});
+			return c.json({
+				ok: true,
+				scope,
+				group_id: groupId,
+				status
+			});
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return c.json({
+				error: message,
+				status
+			}, coordinatorAdminMutationStatus(message));
+		}
+	});
+	app.patch("/api/coordinator/admin/groups/:group_id/scopes/:scope_id", async (c) => {
+		const config = readCoordinatorSyncConfig();
+		const status = coordinatorAdminStatusPayload(config);
+		const unavailable = coordinatorAdminUnavailable(status);
+		if (unavailable) return c.json(unavailable.body, unavailable.httpStatus);
+		const groupId = String(c.req.param("group_id") ?? "").trim();
+		const scopeId = String(c.req.param("scope_id") ?? "").trim();
+		if (!groupId) return c.json({
+			error: "group_id required",
+			status
+		}, 400);
+		if (!scopeId) return c.json({
+			error: "scope_id required",
+			status
+		}, 400);
+		const body = await parseViewerJsonBody(c);
+		if (!body) return c.json({
+			error: "invalid json",
+			status
+		}, 400);
+		const membershipEpoch = optionalViewerNumber(body, "membership_epoch");
+		if (Number.isNaN(membershipEpoch)) return c.json({
+			error: "membership_epoch must be number",
+			status
+		}, 400);
+		try {
+			const scope = await coordinatorUpdateScopeAction({
+				groupId,
+				scopeId,
+				label: body.label === void 0 ? void 0 : optionalViewerString(body, "label"),
+				kind: body.kind === void 0 ? void 0 : optionalViewerString(body, "kind"),
+				authorityType: body.authority_type === void 0 ? void 0 : optionalViewerString(body, "authority_type"),
+				coordinatorId: body.coordinator_id === void 0 ? void 0 : optionalViewerString(body, "coordinator_id"),
+				manifestIssuerDeviceId: body.manifest_issuer_device_id === void 0 ? void 0 : optionalViewerString(body, "manifest_issuer_device_id"),
+				membershipEpoch,
+				manifestHash: body.manifest_hash === void 0 ? void 0 : optionalViewerString(body, "manifest_hash"),
+				status: body.status === void 0 ? void 0 : optionalViewerString(body, "status"),
+				remoteUrl: config.syncCoordinatorUrl || null,
+				adminSecret: config.syncCoordinatorAdminSecret || null
+			});
+			if (!scope) return c.json({
+				error: "scope_not_found",
+				status
+			}, 404);
+			return c.json({
+				ok: true,
+				scope,
+				group_id: groupId,
+				status
+			});
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return c.json({
+				error: message,
+				status
+			}, coordinatorAdminMutationStatus(message));
+		}
+	});
+	app.get("/api/coordinator/admin/groups/:group_id/scopes/:scope_id/members", async (c) => {
+		const config = readCoordinatorSyncConfig();
+		const status = coordinatorAdminStatusPayload(config);
+		const unavailable = coordinatorAdminUnavailable(status);
+		if (unavailable) return c.json(unavailable.body, unavailable.httpStatus);
+		const groupId = String(c.req.param("group_id") ?? "").trim();
+		const scopeId = String(c.req.param("scope_id") ?? "").trim();
+		if (!groupId) return c.json({
+			error: "group_id required",
+			status
+		}, 400);
+		if (!scopeId) return c.json({
+			error: "scope_id required",
+			status
+		}, 400);
+		try {
+			const items = await coordinatorListScopeMembershipsAction({
+				groupId,
+				scopeId,
+				includeRevoked: queryBool(c.req.query("include_revoked")),
+				remoteUrl: config.syncCoordinatorUrl || null,
+				adminSecret: config.syncCoordinatorAdminSecret || null
+			});
+			return c.json({
+				items,
+				group_id: groupId,
+				scope_id: scopeId,
+				status
+			});
+		} catch (error) {
+			const message = error instanceof Error ? error.message : "unknown";
+			return c.json({
+				error: message,
+				status
+			}, coordinatorAdminMutationStatus(message));
+		}
+	});
+	app.post("/api/coordinator/admin/groups/:group_id/scopes/:scope_id/members", async (c) => {
+		const config = readCoordinatorSyncConfig();
+		const status = coordinatorAdminStatusPayload(config);
+		const unavailable = coordinatorAdminUnavailable(status);
+		if (unavailable) return c.json(unavailable.body, unavailable.httpStatus);
+		const groupId = String(c.req.param("group_id") ?? "").trim();
+		const scopeId = String(c.req.param("scope_id") ?? "").trim();
+		if (!groupId) return c.json({
+			error: "group_id required",
+			status
+		}, 400);
+		if (!scopeId) return c.json({
+			error: "scope_id required",
+			status
+		}, 400);
+		const body = await parseViewerJsonBody(c);
+		if (!body) return c.json({
+			error: "invalid json",
+			status
+		}, 400);
+		const deviceId = optionalViewerString(body, "device_id");
+		const membershipEpoch = optionalViewerNumber(body, "membership_epoch");
+		if (!deviceId) return c.json({
+			error: "device_id required",
+			status
+		}, 400);
+		if (Number.isNaN(membershipEpoch)) return c.json({
+			error: "membership_epoch must be number",
+			status
+		}, 400);
+		try {
+			const membership = await coordinatorGrantScopeMembershipAction({
+				groupId,
+				scopeId,
+				deviceId,
+				role: optionalViewerString(body, "role"),
+				membershipEpoch,
+				coordinatorId: optionalViewerString(body, "coordinator_id"),
+				manifestIssuerDeviceId: optionalViewerString(body, "manifest_issuer_device_id"),
+				manifestHash: optionalViewerString(body, "manifest_hash"),
+				signedManifestJson: optionalViewerString(body, "signed_manifest_json"),
+				remoteUrl: config.syncCoordinatorUrl || null,
+				adminSecret: config.syncCoordinatorAdminSecret || null
+			});
+			return c.json({
+				ok: true,
+				membership,
+				group_id: groupId,
+				scope_id: scopeId,
+				status
+			});
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return c.json({
+				error: message,
+				status
+			}, coordinatorAdminMutationStatus(message));
+		}
+	});
+	app.post("/api/coordinator/admin/groups/:group_id/scopes/:scope_id/members/:device_id/revoke", async (c) => {
+		const config = readCoordinatorSyncConfig();
+		const status = coordinatorAdminStatusPayload(config);
+		const unavailable = coordinatorAdminUnavailable(status);
+		if (unavailable) return c.json(unavailable.body, unavailable.httpStatus);
+		const groupId = String(c.req.param("group_id") ?? "").trim();
+		const scopeId = String(c.req.param("scope_id") ?? "").trim();
+		const deviceId = String(c.req.param("device_id") ?? "").trim();
+		if (!groupId) return c.json({
+			error: "group_id required",
+			status
+		}, 400);
+		if (!scopeId) return c.json({
+			error: "scope_id required",
+			status
+		}, 400);
+		if (!deviceId) return c.json({
+			error: "device_id required",
+			status
+		}, 400);
+		const body = await parseViewerJsonBody(c, { allowEmpty: true });
+		if (!body) return c.json({
+			error: "invalid json",
+			status
+		}, 400);
+		const membershipEpoch = optionalViewerNumber(body, "membership_epoch");
+		if (Number.isNaN(membershipEpoch)) return c.json({
+			error: "membership_epoch must be number",
+			status
+		}, 400);
+		try {
+			if (!await coordinatorRevokeScopeMembershipAction({
+				groupId,
+				scopeId,
+				deviceId,
+				membershipEpoch,
+				manifestHash: optionalViewerString(body, "manifest_hash"),
+				signedManifestJson: optionalViewerString(body, "signed_manifest_json"),
+				remoteUrl: config.syncCoordinatorUrl || null,
+				adminSecret: config.syncCoordinatorAdminSecret || null
+			})) return c.json({
+				error: "membership_not_found",
+				status
+			}, 404);
+			return c.json({
+				ok: true,
+				group_id: groupId,
+				scope_id: scopeId,
+				device_id: deviceId,
+				status
+			});
+		} catch (error) {
+			const message = error instanceof Error ? error.message : String(error);
+			return c.json({
+				error: message,
+				status
+			}, coordinatorAdminMutationStatus(message));
+		}
+	});
 	app.post("/api/coordinator/admin/invites", async (c) => {
 		const config = readCoordinatorSyncConfig();
 		const status = coordinatorAdminStatusPayload(config);
@@ -3322,7 +3735,7 @@ function syncRoutes(getStore, getSyncRuntimeStatus) {
 			return c.json({
 				error: message,
 				status
-			}, 502);
+			}, coordinatorAdminMutationStatus(message));
 		}
 	});
 	app.post("/api/coordinator/admin/join-requests/:request_id/approve", async (c) => {
@@ -3440,7 +3853,7 @@ function syncRoutes(getStore, getSyncRuntimeStatus) {
 			return c.json({
 				error: message,
 				status
-			}, 502);
+			}, coordinatorAdminMutationStatus(message));
 		}
 	});
 	app.post("/api/coordinator/admin/devices/:device_id/rename", async (c) => {