reffy-cli 1.4.2 → 1.7.0

package/dist/remote.js

@@ -1,8 +1,12 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
 import { resolveRefsDir } from "./refs-paths.js";
-export const REMOTE_CONFIG_VERSION = 1;
+export const REMOTE_CONFIG_VERSION = 4;
 export const REMOTE_PROVIDER = "paseo";
+export const REMOTE_BACKEND_ACTOR_TYPE = "reffyRemoteBackend";
+export const REMOTE_BACKEND_VERSION = "v2";
+export const REMOTE_MANAGER_ACTOR_TYPE = "reffyWorkspaceManager";
+export const REMOTE_MANAGER_VERSION = "v1";
 const REMOTE_STATE_DIR = path.join("state");
 const REMOTE_CONFIG_FILE = "remote.json";
 function isObject(value) {
@@ -14,9 +18,54 @@ function isNonEmptyString(value) {
 function normalizeSeparators(value) {
     return value.split(path.sep).join("/");
 }
+function readActorIdentity(value, label, configPath) {
+    if (!isObject(value)) {
+        throw new Error(`Remote config at ${configPath} must define ${label} as an object with pod_name and actor_id`);
+    }
+    if (!isNonEmptyString(value.pod_name)) {
+        throw new Error(`Remote config at ${configPath} must define ${label}.pod_name`);
+    }
+    if (!isNonEmptyString(value.actor_id)) {
+        throw new Error(`Remote config at ${configPath} must define ${label}.actor_id`);
+    }
+    return { pod_name: value.pod_name.trim(), actor_id: value.actor_id.trim() };
+}
 export function resolveRemoteConfigPath(repoRoot) {
     return path.join(resolveRefsDir(repoRoot), REMOTE_STATE_DIR, REMOTE_CONFIG_FILE);
 }
+export function resolveSelectedWorkspaceId(identity, override) {
+    const workspaceIds = (identity.workspace_ids ?? [])
+        .map((entry) => entry.trim())
+        .filter((entry) => entry.length > 0);
+    if (override !== undefined) {
+        const trimmed = override.trim();
+        if (!trimmed) {
+            throw new Error("--workspace-id requires a non-empty value");
+        }
+        if (workspaceIds.length > 0 && !workspaceIds.includes(trimmed)) {
+            throw new Error(`Selected workspace id "${trimmed}" is not a member of manifest.workspace_ids: ${workspaceIds.join(", ") || "(none)"}`);
+        }
+        return trimmed;
+    }
+    if (workspaceIds.length === 0) {
+        throw new Error("Remote sync requires .reffy/manifest.json to define workspace_ids. Run `reffy init` or add at least one workspace id.");
+    }
+    if (workspaceIds.length === 1) {
+        return workspaceIds[0];
+    }
+    throw new Error(`Manifest has multiple workspace_ids (${workspaceIds.join(", ")}); pass --workspace-id to select a target projection.`);
+}
+export function requireWorkspaceIdentity(identity, selectedWorkspaceId) {
+    const project_id = identity.project_id?.trim();
+    if (!project_id) {
+        throw new Error("Remote sync requires .reffy/manifest.json to define project_id");
+    }
+    const workspace_id = selectedWorkspaceId.trim();
+    if (!workspace_id) {
+        throw new Error("Remote sync requires a selected workspace_id");
+    }
+    return { project_id, workspace_id };
+}
 export async function readRemoteConfig(repoRoot) {
     const configPath = resolveRemoteConfigPath(repoRoot);
     const raw = await fs.readFile(configPath, "utf8").catch(() => null);
@@ -32,28 +81,41 @@ export async function readRemoteConfig(repoRoot) {
     if (!isObject(parsed)) {
         throw new Error(`Remote config at ${configPath} must be an object`);
     }
-    if (parsed.version !== REMOTE_CONFIG_VERSION) {
-        throw new Error(`Remote config at ${configPath} must use version ${String(REMOTE_CONFIG_VERSION)}`);
-    }
     if (parsed.provider !== REMOTE_PROVIDER) {
         throw new Error(`Remote config at ${configPath} must use provider "${REMOTE_PROVIDER}"`);
     }
-    if (!isNonEmptyString(parsed.endpoint)) {
-        throw new Error(`Remote config at ${configPath} must define endpoint`);
+    if (parsed.version === 1) {
+        throw new Error(`Remote config at ${configPath} uses the legacy v1 single-target shape. Run \`reffy remote init\` against the workspace manager actor (reffyWorkspaceManager.v1) to reinitialize, then repush with \`reffy remote push\`.`);
+    }
+    if (parsed.version === 2) {
+        throw new Error(`Remote config at ${configPath} uses the legacy v2 combined-backend shape. The Paseo backend now splits into reffyWorkspaceManager.v1 (control plane) and reffyRemoteBackend.v2 (per-workspace storage). Run \`reffy remote init --manager-pod <pod> --manager-actor <actor>\` (or \`--provision\`) to reinitialize, then repush with \`reffy remote push\`.`);
+    }
+    if (parsed.version === 3) {
+        throw new Error(`Remote config at ${configPath} uses the legacy v3 shape that persisted the Paseo endpoint and pre-dates bearer-token auth. Set PASEO_ENDPOINT and PASEO_TOKEN in your .env, then run \`reffy remote init\` (with \`--provision\` for fresh setups) to reinitialize, and repush with \`reffy remote push\`.`);
+    }
+    if (parsed.version !== REMOTE_CONFIG_VERSION) {
+        throw new Error(`Remote config at ${configPath} must use version ${String(REMOTE_CONFIG_VERSION)}`);
     }
-    if (!isNonEmptyString(parsed.pod_name)) {
-        throw new Error(`Remote config at ${configPath} must define pod_name`);
+    const manager = readActorIdentity(parsed.manager, "manager", configPath);
+    if (!isObject(parsed.targets)) {
+        throw new Error(`Remote config at ${configPath} must define targets as an object keyed by workspace_id`);
     }
-    if (!isNonEmptyString(parsed.actor_id)) {
-        throw new Error(`Remote config at ${configPath} must define actor_id`);
+    const targets = {};
+    for (const [workspaceId, entry] of Object.entries(parsed.targets)) {
+        if (!isObject(entry)) {
+            throw new Error(`Remote config at ${configPath} has invalid target for workspace_id "${workspaceId}"`);
+        }
+        const workspace_backend = readActorIdentity(entry.workspace_backend, `targets.${workspaceId}.workspace_backend`, configPath);
+        targets[workspaceId] = {
+            workspace_backend,
+            last_imported_at: isNonEmptyString(entry.last_imported_at) ? entry.last_imported_at.trim() : undefined,
+        };
     }
     return {
         version: REMOTE_CONFIG_VERSION,
         provider: REMOTE_PROVIDER,
-        endpoint: parsed.endpoint.trim(),
-        pod_name: parsed.pod_name.trim(),
-        actor_id: parsed.actor_id.trim(),
-        last_imported_at: isNonEmptyString(parsed.last_imported_at) ? parsed.last_imported_at.trim() : undefined,
+        manager,
+        targets,
     };
 }
 export async function writeRemoteConfig(repoRoot, config) {
@@ -62,48 +124,96 @@ export async function writeRemoteConfig(repoRoot, config) {
     await fs.writeFile(configPath, JSON.stringify(config, null, 2), "utf8");
     return configPath;
 }
-export async function updateRemoteConfigMetadata(repoRoot, patch) {
+export async function updateRemoteConfigMetadata(repoRoot, workspaceId, patch) {
     const existing = await readRemoteConfig(repoRoot);
     if (!existing)
         return null;
+    const target = existing.targets[workspaceId];
+    if (!target)
+        return null;
     const next = {
         ...existing,
-        ...patch,
+        targets: {
+            ...existing.targets,
+            [workspaceId]: { ...target, ...patch },
+        },
     };
     await writeRemoteConfig(repoRoot, next);
     return next;
 }
-export function mergeRemoteConfig(stored, overrides) {
-    if (!stored && !overrides.endpoint && !overrides.pod_name && !overrides.actor_id) {
-        return null;
+export async function removeWorkspaceTarget(repoRoot, existing, workspaceId) {
+    const existed = Object.prototype.hasOwnProperty.call(existing.targets, workspaceId);
+    if (!existed) {
+        return { config: existing, existed: false };
     }
-    const endpoint = overrides.endpoint ?? stored?.endpoint;
-    const pod_name = overrides.pod_name ?? stored?.pod_name;
-    const actor_id = overrides.actor_id ?? stored?.actor_id;
-    if (!endpoint || !pod_name || !actor_id) {
+    const nextTargets = { ...existing.targets };
+    delete nextTargets[workspaceId];
+    const next = { ...existing, targets: nextTargets };
+    await writeRemoteConfig(repoRoot, next);
+    return { config: next, existed: true };
+}
+export async function upsertWorkspaceTarget(repoRoot, existing, workspaceId, workspaceBackend) {
+    const priorTarget = existing.targets[workspaceId];
+    const next = {
+        ...existing,
+        targets: {
+            ...existing.targets,
+            [workspaceId]: {
+                workspace_backend: workspaceBackend,
+                last_imported_at: priorTarget?.last_imported_at,
+            },
+        },
+    };
+    await writeRemoteConfig(repoRoot, next);
+    return next;
+}
+export function resolveRemoteTarget(stored, workspaceId, endpoint) {
+    if (!stored)
+        return null;
+    const target = stored.targets[workspaceId];
+    if (!target)
         return null;
-    }
     return {
-        version: REMOTE_CONFIG_VERSION,
-        provider: REMOTE_PROVIDER,
         endpoint,
-        pod_name,
-        actor_id,
-        last_imported_at: stored?.last_imported_at,
+        manager: stored.manager,
+        workspace_backend: target.workspace_backend,
+        last_imported_at: target.last_imported_at,
     };
 }
-export function describeRemoteLinkage(config) {
-    return `endpoint=${config.endpoint} pod=${config.pod_name} actor=${config.actor_id}`;
+export function describeRemoteLinkage(linkage) {
+    return [
+        `endpoint=${linkage.endpoint}`,
+        `manager=${linkage.manager.pod_name}/${linkage.manager.actor_id}`,
+        `workspace_backend=${linkage.workspace_backend.pod_name}/${linkage.workspace_backend.actor_id}`,
+        `workspace=${linkage.workspace_id}`,
+    ].join(" ");
+}
+export class RemoteHttpError extends Error {
+    status;
+    body;
+    url;
+    method;
+    constructor(status, statusText, body, url, method) {
+        super(`${String(status)} ${statusText} - ${body}`);
+        this.status = status;
+        this.body = body;
+        this.url = url;
+        this.method = method;
+    }
 }
 async function http(url, init = {}) {
-    const headers = new Headers(init.headers ?? {});
-    if (!headers.has("Content-Type") && init.body) {
+    const { token, headers: rawHeaders, ...rest } = init;
+    const headers = new Headers(rawHeaders ?? {});
+    if (!headers.has("Content-Type") && rest.body) {
         headers.set("Content-Type", "application/json");
     }
-    const response = await fetch(url, { ...init, headers });
+    if (token && !headers.has("Authorization")) {
+        headers.set("Authorization", `Bearer ${token}`);
+    }
+    const response = await fetch(url, { ...rest, headers });
     if (!response.ok) {
         const text = await response.text().catch(() => "");
-        throw new Error(`${response.status} ${response.statusText} - ${text}`);
+        throw new RemoteHttpError(response.status, response.statusText, text, url, rest.method ?? "GET");
     }
     return response;
 }
@@ -111,126 +221,273 @@ async function httpJson(url, init = {}) {
     const response = await http(url, init);
     return (await response.json());
 }
-function actorBase(config) {
-    return `${config.endpoint}/pods/${config.pod_name}/actors/${config.actor_id}`;
+function actorBase(endpoint, identity) {
+    return `${endpoint}/pods/${identity.pod_name}/actors/${identity.actor_id}`;
 }
-export class PaseoRemoteClient {
-    config;
-    constructor(config) {
-        this.config = config;
+export class PaseoManagerClient {
+    endpoint;
+    identity;
+    token;
+    constructor(endpoint, identity, token) {
+        this.endpoint = endpoint;
+        this.identity = identity;
+        this.token = token;
+    }
+    base() {
+        return actorBase(this.endpoint, this.identity);
+    }
+    requireToken() {
+        if (!this.token) {
+            throw new Error("Manager request requires PASEO_TOKEN to be set in the environment. Add it to your .env (or export it) and retry.");
+        }
+        return this.token;
     }
     async createPod() {
-        const result = await httpJson(`${this.config.endpoint}/pods`, { method: "POST" });
+        const result = await httpJson(`${this.endpoint}/pods`, { method: "POST" });
         if (!isNonEmptyString(result.podName)) {
             throw new Error("Paseo create pod response missing podName");
         }
         return result.podName.trim();
     }
-    async createActor(identity) {
-        const result = await httpJson(`${this.config.endpoint}/pods/${this.config.pod_name}/actors`, {
+    async createManagerActor(podName) {
+        const result = await httpJson(`${this.endpoint}/pods/${podName}/actors`, {
             method: "POST",
             body: JSON.stringify({
                 config: {
-                    actorType: "reffyRemoteBackend",
-                    version: "v1",
+                    actorType: REMOTE_MANAGER_ACTOR_TYPE,
+                    version: REMOTE_MANAGER_VERSION,
                     schema: { type: "object" },
-                    params: {
-                        project_id: identity.project_id,
-                        workspace_name: identity.workspace_name,
-                        default_lock_ttl_seconds: 120,
-                        max_snapshot_documents: 1000,
-                    },
+                    params: {},
                 },
             }),
         });
         if (!isNonEmptyString(result.actorId)) {
-            throw new Error("Paseo create actor response missing actorId");
+            throw new Error("Paseo create manager actor response missing actorId");
         }
-        return result.actorId.trim();
-    }
-    async getWorkspace() {
-        return await httpJson(`${actorBase(this.config)}/workspace`);
+        if (!isNonEmptyString(result.managerAuthToken)) {
+            throw new Error("Paseo create manager actor response missing managerAuthToken. The backend may not yet expose bearer-token issuance for reffyWorkspaceManager.v1.");
+        }
+        return { actorId: result.actorId.trim(), managerAuthToken: result.managerAuthToken.trim() };
     }
-    async importWorkspace(documents, replaceMissing = true) {
-        return await httpJson(`${actorBase(this.config)}/workspace/import`, {
+    async createWorkspace(workspaceId, metadata) {
+        const result = await httpJson(`${this.base()}/workspaces`, {
             method: "POST",
+            token: this.requireToken(),
             body: JSON.stringify({
-                documents,
-                replace_missing: replaceMissing,
+                workspace_id: workspaceId,
+                metadata: metadata ?? {},
+                controller: { client: "reffy-cli" },
             }),
         });
+        return extractWorkspaceBackendIdentity(result, workspaceId, "createWorkspace");
     }
-    async getSnapshot(prefix) {
-        const query = prefix ? `?prefix=${encodeURIComponent(prefix)}` : "";
-        return await httpJson(`${actorBase(this.config)}/workspace/snapshot${query}`);
+    async getWorkspace(workspaceId) {
+        const result = await httpJson(`${this.base()}/workspaces/${encodeURIComponent(workspaceId)}`, { token: this.requireToken() });
+        return extractWorkspaceBackendIdentity(result, workspaceId, "getWorkspace");
     }
-    async getDocument(documentPath) {
-        return await httpJson(`${actorBase(this.config)}/workspace/documents?path=${encodeURIComponent(documentPath)}`);
+    async registerProject(workspaceId, projectId) {
+        try {
+            await http(`${this.base()}/workspaces/${encodeURIComponent(workspaceId)}/projects/${encodeURIComponent(projectId)}`, {
+                method: "POST",
+                token: this.requireToken(),
+                body: JSON.stringify({
+                    owner: { source: "reffy-cli" },
+                    metadata: { source: "reffy-cli" },
+                }),
+            });
+            return { alreadyRegistered: false };
+        }
+        catch (error) {
+            if (error instanceof RemoteHttpError && error.status === 409) {
+                return { alreadyRegistered: true };
+            }
+            throw error;
+        }
+    }
+    async listProjects(workspaceId) {
+        return await httpJson(`${this.base()}/workspaces/${encodeURIComponent(workspaceId)}/projects`, { token: this.requireToken() });
+    }
+    async getProject(workspaceId, projectId) {
+        return await httpJson(`${this.base()}/workspaces/${encodeURIComponent(workspaceId)}/projects/${encodeURIComponent(projectId)}`, { token: this.requireToken() });
+    }
+    async deleteWorkspace(workspaceId) {
+        try {
+            await http(`${this.base()}/workspaces/${encodeURIComponent(workspaceId)}`, {
+                method: "DELETE",
+                token: this.requireToken(),
+            });
+            return { alreadyAbsent: false };
+        }
+        catch (error) {
+            if (error instanceof RemoteHttpError && error.status === 404) {
+                return { alreadyAbsent: true };
+            }
+            throw error;
+        }
     }
 }
-export async function ensureRemoteInit(repoRoot, options) {
-    let created_pod = false;
-    let created_actor = false;
-    let podName = options.podName?.trim() || "";
-    let actorId = options.actorId?.trim() || "";
-    if (!options.endpoint.trim()) {
+function extractWorkspaceBackendIdentity(response, workspaceId, context) {
+    const workspace = response.workspace;
+    if (!isObject(workspace)) {
+        throw new Error(`Manager ${context} response missing workspace envelope for "${workspaceId}"`);
+    }
+    const backend = workspace.backend;
+    if (!isObject(backend)) {
+        throw new Error(`Manager ${context} response missing workspace.backend for "${workspaceId}"`);
+    }
+    if (!isNonEmptyString(backend.pod_name) || !isNonEmptyString(backend.actor_id)) {
+        throw new Error(`Manager ${context} response missing workspace.backend.pod_name or actor_id for "${workspaceId}"`);
+    }
+    return { pod_name: backend.pod_name.trim(), actor_id: backend.actor_id.trim() };
+}
+export class PaseoWorkspaceBackendClient {
+    endpoint;
+    identity;
+    token;
+    constructor(endpoint, identity, token) {
+        if (!token) {
+            throw new Error("PaseoWorkspaceBackendClient requires a bearer token. Set PASEO_TOKEN in your .env (or export it) before invoking remote commands.");
+        }
+        this.endpoint = endpoint;
+        this.identity = identity;
+        this.token = token;
+    }
+    base() {
+        return `${actorBase(this.endpoint, this.identity)}/workspace`;
+    }
+    async getWorkspace() {
+        return await httpJson(this.base(), { token: this.token });
+    }
+    async importProject(projectId, documents, replaceMissing = true) {
+        return await httpJson(`${this.base()}/projects/${encodeURIComponent(projectId)}/import`, {
+            method: "POST",
+            token: this.token,
+            body: JSON.stringify({ documents, replace_missing: replaceMissing }),
+        });
+    }
+    async listProjectDocuments(projectId, options = {}) {
+        const params = new URLSearchParams();
+        if (options.prefix)
+            params.set("prefix", options.prefix);
+        const query = params.toString();
+        return await httpJson(`${this.base()}/projects/${encodeURIComponent(projectId)}/documents${query ? `?${query}` : ""}`, { token: this.token });
+    }
+    async getProjectDocument(projectId, documentPath) {
+        return await httpJson(`${this.base()}/projects/${encodeURIComponent(projectId)}/documents?path=${encodeURIComponent(documentPath)}`, { token: this.token });
+    }
+    async getProjectSnapshot(projectId) {
+        return await httpJson(`${this.base()}/projects/${encodeURIComponent(projectId)}/snapshot`, { token: this.token });
+    }
+}
+export async function ensureManagerInit(repoRoot, options) {
+    const endpoint = options.endpoint.trim();
+    if (!endpoint) {
         throw new Error("Remote init requires an endpoint");
     }
+    const prior = options.existingConfig;
+    let podName = (options.managerPodName ?? prior?.manager.pod_name ?? "").trim();
+    let actorId = (options.managerActorId ?? prior?.manager.actor_id ?? "").trim();
+    let created_pod = false;
+    let created_actor = false;
+    let manager_auth_token;
     if (!podName && !options.provision) {
-        throw new Error("Remote init requires --pod-name unless --provision is set");
+        throw new Error("Remote init requires --manager-pod (or --provision to create a fresh pod and manager actor)");
     }
-    const baseClient = new PaseoRemoteClient({
-        endpoint: options.endpoint.trim(),
+    // createPod and createManagerActor do not require a bearer token; the manager actor itself issues the token.
+    const provisioner = new PaseoManagerClient(endpoint, {
         pod_name: podName || "pending-pod",
         actor_id: actorId || "pending-actor",
     });
     if (!podName) {
-        podName = await baseClient.createPod();
+        podName = await provisioner.createPod();
         created_pod = true;
     }
     if (!actorId) {
         if (!options.provision) {
-            throw new Error("Remote init requires --actor-id unless --provision is set");
+            throw new Error("Remote init requires --manager-actor unless --provision is set so the CLI can create a fresh manager actor");
         }
-        const client = new PaseoRemoteClient({
-            endpoint: options.endpoint.trim(),
+        const result = await new PaseoManagerClient(endpoint, {
             pod_name: podName,
             actor_id: "pending-actor",
-        });
-        actorId = await client.createActor(options.identity);
+        }).createManagerActor(podName);
+        actorId = result.actorId;
+        manager_auth_token = result.managerAuthToken;
         created_actor = true;
     }
     const config = {
         version: REMOTE_CONFIG_VERSION,
         provider: REMOTE_PROVIDER,
-        endpoint: options.endpoint.trim(),
-        pod_name: podName,
-        actor_id: actorId,
+        manager: { pod_name: podName, actor_id: actorId },
+        targets: prior?.targets ?? {},
     };
     await writeRemoteConfig(repoRoot, config);
-    return { config, created_pod, created_actor };
+    return { config, created_pod, created_actor, manager_auth_token };
 }
-export function requireWorkspaceIdentity(identity) {
-    const project_id = identity.project_id?.trim();
-    const workspace_name = identity.workspace_name?.trim();
-    if (!project_id || !workspace_name) {
-        throw new Error("Remote sync requires .reffy/manifest.json to define project_id and workspace_name");
+export async function ensureWorkspaceTarget(repoRoot, config, options) {
+    const manager = new PaseoManagerClient(options.endpoint, config.manager, options.token);
+    const existing = config.targets[options.workspaceId];
+    if (options.mode === "resolve" || (options.mode === "auto" && existing)) {
+        try {
+            const backend = await manager.getWorkspace(options.workspaceId);
+            const nextConfig = await upsertWorkspaceTarget(repoRoot, config, options.workspaceId, backend);
+            return { config: nextConfig, workspace_backend: backend, outcome: existing ? "reused" : "resolved" };
+        }
+        catch (error) {
+            if (options.mode === "resolve")
+                throw error;
+            // fall through to create on auto
+        }
+    }
+    // create (or auto with no existing)
+    try {
+        const backend = await manager.createWorkspace(options.workspaceId, options.metadata);
+        const nextConfig = await upsertWorkspaceTarget(repoRoot, config, options.workspaceId, backend);
+        return { config: nextConfig, workspace_backend: backend, outcome: "created" };
+    }
+    catch (error) {
+        if (error instanceof RemoteHttpError && error.status === 409) {
+            const backend = await manager.getWorkspace(options.workspaceId);
+            const nextConfig = await upsertWorkspaceTarget(repoRoot, config, options.workspaceId, backend);
+            return { config: nextConfig, workspace_backend: backend, outcome: "resolved" };
+        }
+        throw error;
     }
-    return { project_id, workspace_name };
 }
-export function extractWorkspaceIdentity(summary) {
+export function extractWorkspaceSummaryIdentity(summary) {
+    const top = summary;
+    const source = isObject(summary.source) ? summary.source : {};
     const workspace = isObject(summary.workspace) ? summary.workspace : {};
     const stats = isObject(summary.stats) ? summary.stats : {};
+    const actorType = typeof source.actor_type === "string"
+        ? source.actor_type
+        : typeof top.actor_type === "string"
+            ? top.actor_type
+            : null;
+    const backendVersion = typeof source.version === "string"
+        ? source.version
+        : typeof top.version === "string"
+            ? top.version
+            : null;
+    const documentCount = typeof stats.document_count === "number"
+        ? stats.document_count
+        : typeof stats.source_document_count === "number"
+            ? stats.source_document_count
+            : null;
     return {
-        project_id: typeof workspace.project_id === "string" ? workspace.project_id : null,
-        workspace_name: typeof workspace.workspace_name === "string" ? workspace.workspace_name : null,
-        document_count: typeof stats.document_count === "number" ? stats.document_count : null,
+        workspace_id: typeof workspace.workspace_id === "string" ? workspace.workspace_id : null,
+        actor_type: actorType,
+        backend_version: backendVersion,
+        document_count: documentCount,
+        registered_project_count: typeof stats.registered_project_count === "number" ? stats.registered_project_count : null,
     };
 }
-export function assertRemoteIdentity(summary, identity) {
-    const remote = extractWorkspaceIdentity(summary);
-    if (remote.project_id !== identity.project_id || remote.workspace_name !== identity.workspace_name) {
-        throw new Error(`Remote identity mismatch: local=${identity.project_id}/${identity.workspace_name} remote=${String(remote.project_id)}/${String(remote.workspace_name)}`);
+export function assertWorkspaceSummaryIdentity(summary, expectedWorkspaceId) {
+    const remote = extractWorkspaceSummaryIdentity(summary);
+    if (!remote.workspace_id) {
+        throw new Error("Remote workspace summary did not include a workspace.workspace_id envelope. The linked actor may be a legacy v1 backend or a non-workspace actor. Reinitialize against reffyWorkspaceManager.v1 + reffyRemoteBackend.v2 (`reffy remote init`) and repush with `reffy remote push`.");
+    }
+    if (remote.workspace_id !== expectedWorkspaceId) {
+        throw new Error(`Remote identity mismatch: expected workspace_id=${expectedWorkspaceId} but workspace backend reported workspace_id=${String(remote.workspace_id)}. Re-resolve the workspace through the manager (\`reffy remote workspace get ${expectedWorkspaceId}\`) or reinitialize linkage.`);
     }
 }
 export function validateImportResult(result) {

package/dist/storage.d.ts

@@ -12,7 +12,7 @@ export declare class ReferencesStore {
     listArtifacts(): Promise<Artifact[]>;
     getWorkspaceIdentity(): Promise<{
         project_id?: string;
-        workspace_name?: string;
+        workspace_ids?: string[];
     }>;
     getArtifact(artifactId: string): Promise<Artifact | null>;
     getArtifactPath(artifact: Artifact): string;

package/dist/storage.js

@@ -51,7 +51,7 @@ export class ReferencesStore {
         const manifest = await this.readManifest();
         return {
             project_id: manifest.project_id,
-            workspace_name: manifest.workspace_name,
+            workspace_ids: manifest.workspace_ids ? [...manifest.workspace_ids] : undefined,
         };
     }
     async getArtifact(artifactId) {

package/dist/types.d.ts

@@ -17,17 +17,25 @@ export interface Manifest {
     created_at: string;
     updated_at: string;
     project_id?: string;
+    workspace_ids?: string[];
+    /** Deprecated v1 field retained only as migration input. */
     workspace_name?: string;
     artifacts: Artifact[];
 }
-export interface RemoteLinkConfig {
-    version: number;
-    provider: "paseo";
-    endpoint: string;
+export interface RemoteActorIdentity {
     pod_name: string;
     actor_id: string;
+}
+export interface RemoteTarget {
+    workspace_backend: RemoteActorIdentity;
     last_imported_at?: string;
 }
+export interface RemoteLinkConfig {
+    version: number;
+    provider: "paseo";
+    manager: RemoteActorIdentity;
+    targets: Record<string, RemoteTarget>;
+}
 export interface RemoteDocument {
     path: string;
     content: string;
@@ -41,6 +49,7 @@ export interface RemoteImportResult {
     deleted?: number;
 }
 export interface RemoteWorkspaceSummary {
+    source?: Record<string, unknown>;
     workspace?: Record<string, unknown>;
     stats?: Record<string, unknown>;
 }

package/dist/workspace.js

@@ -1,6 +1,6 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
-import { deriveManifestIdentity, normalizeManifest } from "./manifest.js";
+import { normalizeManifest } from "./manifest.js";
 import { DEFAULT_REFS_DIRNAME, LEGACY_REFS_DIRNAME, detectWorkspaceState, resolveCanonicalRefsDir, } from "./refs-paths.js";
 async function pathExists(targetPath) {
     try {
@@ -30,11 +30,13 @@ async function ensureCanonicalStructure(repoRoot) {
                 const raw = JSON.parse(rawText);
                 if (raw && typeof raw === "object" && !Array.isArray(raw)) {
                     const record = raw;
-                    const defaults = deriveManifestIdentity(repoRoot);
-                    const missingIdentity = record.project_id === undefined || record.workspace_name === undefined;
-                    if (missingIdentity) {
+                    const missingProjectId = record.project_id === undefined;
+                    const missingWorkspaceIds = !Array.isArray(record.workspace_ids) || record.workspace_ids.length === 0;
+                    const needsMigration = missingProjectId || missingWorkspaceIds;
+                    if (needsMigration) {
                         const nextManifest = normalizeManifest(raw, repoRoot);
                         nextManifest.updated_at = new Date().toISOString();
+                        delete nextManifest.workspace_name;
                         await fs.writeFile(manifestPath, JSON.stringify(nextManifest, null, 2), "utf8");
                     }
                 }