@synap-core/cli 1.11.0 → 1.12.2

package/dist/lib/device-connect.js

@@ -0,0 +1,256 @@
+/**
+ * Connect THIS computer to a pod — the pod-side device flow (RFC 8628,
+ * MACHINE-IDENTITY-PLAN §4). The only way `synap init` and `synap login` get a
+ * credential for a pod, on self-hosted and managed pods alike.
+ *
+ *   1. POST {pod}/api/hub/setup/device        → a user code + where to enter it
+ *   2. the person opens the link on any device, signs in to the pod, approves
+ *      the computer and the agents it asked for (one decision)
+ *   3. POST {pod}/api/hub/setup/device/token  → 400 RFC 8628 errors until then,
+ *      then ONCE: the computer's key + one key per approved agent
+ *
+ * The computer gets its OWN governed principal ("devbox"); each agent is a
+ * distinct agent on that computer ("Claude Code on devbox"). Nothing here needs
+ * a Synap account session, a browser on this machine, or a loopback port.
+ */
+import os from "os";
+import chalk from "chalk";
+import { log } from "../utils/logger.js";
+/**
+ * The agent types the device door accepts (`SURFACE_AGENT_TYPES`,
+ * synap-backend `routers/hub-protocol/rest/setup.ts`). A mirror: the CLI does
+ * not depend on the backend package. A type outside it would 400 the whole
+ * request, so it is filtered out before asking.
+ */
+export const DEVICE_AGENT_TYPES = [
+    "claude-code",
+    "claude-desktop",
+    "cursor",
+    "raycast",
+    "codex",
+    "openwebui",
+    "discord",
+    "proton",
+    "generic",
+];
+/** The pod's cap on agents per request (`DEVICE_MAX_AGENTS`). */
+export const DEVICE_MAX_AGENTS = 8;
+/** The agents of `targets` the device door can approve, deduped, capped. */
+export function deviceAgentsFor(targets) {
+    const ok = targets.filter((t) => DEVICE_AGENT_TYPES.includes(t));
+    return [...new Set(ok)].slice(0, DEVICE_MAX_AGENTS);
+}
+/** The pod could not start a request (an older pod has no device door: 404). */
+export class DeviceStartError extends Error {
+    status;
+    constructor(status, message) {
+        super(message);
+        this.status = status;
+        this.name = "DeviceStartError";
+    }
+}
+const podHost = (podUrl) => {
+    try {
+        return new URL(podUrl).host;
+    }
+    catch {
+        return podUrl;
+    }
+};
+/**
+ * Ask the pod to connect this computer, show the person where to approve it,
+ * and wait — honouring the pod's `interval` and `slow_down` — until it is
+ * approved, denied, or the code expires. Throws `DeviceStartError` only when
+ * the request could not be started at all.
+ */
+export async function deviceConnect(podUrl, opts, deps = {}) {
+    const base = podUrl.replace(/\/+$/, "");
+    const scale = deps.timeScale ?? 1;
+    const host = podHost(base);
+    let res;
+    try {
+        res = await fetch(`${base}/api/hub/setup/device`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                clientName: opts.clientName ?? "Synap CLI",
+                hostname: (opts.hostname ?? os.hostname()).slice(0, 253) || "computer",
+                platform: opts.platform ?? process.platform,
+                agents: deviceAgentsFor(opts.agents),
+            }),
+            signal: AbortSignal.timeout(15_000),
+        });
+    }
+    catch (err) {
+        throw new DeviceStartError(null, `Could not reach ${host}: ${err.message}`);
+    }
+    if (!res.ok) {
+        const body = (await res.json().catch(() => null));
+        throw new DeviceStartError(res.status, res.status === 404
+            ? `${host} cannot connect a computer yet (it needs an update).`
+            : `${host} could not start the request (HTTP ${res.status})${body?.error_description ? `: ${body.error_description}` : "."}`);
+    }
+    const auth = (await res.json());
+    // The instruction comes FIRST and stays on screen: on a headless box (SSH)
+    // there is no browser to open — the person uses their phone or laptop.
+    log.blank();
+    console.log(`  Open ${chalk.cyan.bold(auth.verification_uri)} on any device and enter ${chalk.bold(auth.user_code)}`);
+    if (auth.verification_uri_complete) {
+        log.dim(`Or open: ${auth.verification_uri_complete}`);
+        try {
+            const qr = await (deps.renderQr ?? (await import("./pair-link.js")).renderTerminalQr)(auth.verification_uri_complete);
+            console.log("\n" + qr);
+        }
+        catch {
+            // The link above is enough; a QR is a convenience.
+        }
+    }
+    const minutes = Math.max(1, Math.round(auth.expires_in / 60));
+    log.dim(`Waiting for you to approve this computer on ${host} (the code lasts ${minutes} min)…`);
+    const poll = deps.poll ?? (await import("./approval-poll.js")).pollForApproval;
+    let lastError;
+    try {
+        const grant = await poll({
+            url: `${base}/api/hub/setup/device/token`,
+            method: "POST",
+            body: JSON.stringify({ device_code: auth.device_code }),
+            readErrorBodies: true,
+            intervalMs: (auth.interval ?? 5) * 1000 * scale,
+            timeoutMs: auth.expires_in * 1000 * scale,
+            isApproved: (d) => typeof d.access_token === "string",
+            isRejected: (d) => {
+                const e = d.error;
+                if (e === "access_denied" || e === "expired_token" || e === "invalid_grant") {
+                    lastError = e;
+                    return true;
+                }
+                return false;
+            },
+            // RFC 8628 §3.5: slow_down adds to the interval for the rest of the wait.
+            nextIntervalMs: (d, current) => {
+                const body = d;
+                if (body.error !== "slow_down")
+                    return current;
+                return typeof body.interval === "number" ? body.interval * 1000 * scale : current + 5000 * scale;
+            },
+            onApproved: (d) => {
+                const b = d;
+                return { computer: b.computer, agents: b.agents ?? [] };
+            },
+        });
+        return { status: "approved", grant };
+    }
+    catch {
+        if (lastError === "access_denied")
+            return { status: "denied", message: `Denied on ${host}.` };
+        return { status: "expired", message: "Code expired — run again." };
+    }
+}
+/** Renew a computer key this close to (or past) its expiry. */
+export const COMPUTER_KEY_RENEW_DAYS = 7;
+/**
+ * True when a saved computer key expires within `COMPUTER_KEY_RENEW_DAYS`, or
+ * already has. A credential with no recorded expiry (a pasted key, an old
+ * operator key) is never "due": nothing says it expires.
+ */
+export function computerKeyNeedsRenewal(config, now = Date.now()) {
+    if (!config.keyExpiresAt)
+        return false;
+    const at = Date.parse(config.keyExpiresAt);
+    if (Number.isNaN(at))
+        return false;
+    return at - now < COMPUTER_KEY_RENEW_DAYS * 24 * 60 * 60 * 1000;
+}
+/**
+ * Keep what the device flow returned, once, where each reader already looks:
+ *   - the computer's key → the pod profile `name` (it IS the CLI's identity
+ *     for this pod now), with its expiry so it can be renewed in time;
+ *   - each agent's key → the surface key store (`agentKeys`) AND the
+ *     pre-approved slot its installer takes from, so `synap connect`'s own
+ *     installer writes it into Claude Code / Codex / Cursor instead of minting.
+ * Fields of an existing profile (label, podId) are kept.
+ */
+export async function saveDeviceGrant(podUrl, grant, profile) {
+    const pod = await import("./pod.js");
+    const { presetApprovedKey } = await import("./batch-approval.js");
+    const prior = pod.listPodProfiles().find((p) => p.name === profile.name)?.config;
+    const podId = profile.podId ?? prior?.podId;
+    const config = {
+        ...prior,
+        podUrl,
+        ...(podId ? { podId } : {}),
+        workspaceId: prior?.workspaceId ?? "",
+        agentUserId: grant.computer.id,
+        hubApiKey: grant.computer.apiKey,
+        credential: "computer",
+        computerName: grant.computer.name,
+        savedAt: new Date().toISOString(),
+    };
+    if (grant.computer.expiresAt)
+        config.keyExpiresAt = grant.computer.expiresAt;
+    else
+        delete config.keyExpiresAt;
+    pod.addPodProfile(profile.name, config);
+    for (const a of grant.agents) {
+        if (pod.SURFACE_NAMES.includes(a.agentType)) {
+            pod.setSurfaceAgentKey(a.agentType, {
+                hubApiKey: a.apiKey,
+                agentUserId: a.agentUserId,
+                podUrl,
+            });
+        }
+        presetApprovedKey(a.agentType, { hubApiKey: a.apiKey, agentUserId: a.agentUserId });
+    }
+    return config;
+}
+/** The approved agents this CLI has an installer for, as `synap connect` targets. */
+export async function approvedTargets(grant) {
+    const { isTargetName } = await import("./targets.js");
+    return grant.agents.map((a) => a.agentType).filter(isTargetName);
+}
+/**
+ * Write each approved agent's own key into its client config — the same
+ * installers (`connectAgentsBatch` → `installForTarget`) `synap init` uses —
+ * for the callers that have no agents step of their own (`synap login`,
+ * reconnect, renewal).
+ */
+export async function wireApprovedAgents(podUrl, computerKey, grant) {
+    const targets = await approvedTargets(grant);
+    if (targets.length === 0)
+        return;
+    const { connectAgentsBatch } = await import("./agent-door.js");
+    await connectAgentsBatch({ podUrl, apiKey: computerKey }, targets, {});
+}
+/**
+ * Connect this computer to `podUrl` and save the result under profile `name`:
+ * the device flow, then `saveDeviceGrant`, then the agents' configs. The agents
+ * asked for are the ones found on this machine. Returns the saved profile, or
+ * null after printing why (denied, expired, or the pod can't do it).
+ */
+export async function connectThisComputer(podUrl, profile, opts = {}) {
+    let agents = opts.agents;
+    if (!agents) {
+        const { detectAgents } = await import("./agent-detect.js");
+        agents = detectAgents()
+            .filter((r) => r.found)
+            .map((r) => r.target);
+    }
+    let outcome;
+    try {
+        outcome = await deviceConnect(podUrl, { agents });
+    }
+    catch (err) {
+        log.error(err instanceof Error ? err.message : String(err));
+        return null;
+    }
+    if (outcome.status !== "approved") {
+        log.error(outcome.message);
+        return null;
+    }
+    const config = await saveDeviceGrant(podUrl, outcome.grant, profile);
+    log.success(`${outcome.grant.computer.name} connected to ${podHost(podUrl)}`);
+    if (opts.wireAgents !== false)
+        await wireApprovedAgents(podUrl, config.hubApiKey, outcome.grant);
+    return config;
+}
+//# sourceMappingURL=device-connect.js.map

package/dist/lib/device-connect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"device-connect.js","sourceRoot":"","sources":["../../src/lib/device-connect.ts"],"names":[],"mappings":"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"}

package/dist/lib/directory-lens.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Per-DIRECTORY lens — the durable default scope for a working tree.
+ *
+ * RATIFIED MODEL: a directory's `.synap/lens.json` is where a lens normally
+ * lives; the per-Claude-session lens (`session-lens.ts`) is an explicit
+ * OVERRIDE on top of it.
+ *
+ * The session lens alone could not express "this repo is always Builder" — it
+ * dies with the tab, so every new session started pod-wide (or, worse, on
+ * whatever the global config happened to hold) and the operator re-pinned by
+ * hand. A directory lens is discovered the way git discovers `.git`: walk UP
+ * from the cwd until a `.synap/lens.json` turns up.
+ *
+ * Full precedence, highest first (assembled in `hub-client.ts`):
+ *
+ *   explicit flag  ›  session lens  ›  DIRECTORY LENS  ›  env var  ›  global config
+ *
+ * ── Pod qualification ────────────────────────────────────────────────────────
+ * Workspace and project ids are POD-LOCAL: sending workspace W (pod A) to pod B
+ * is the "Access denied to workspace" 403. A directory lens is exposed to that
+ * hazard MORE than a session lens is, because it outlives many `synap pods use`
+ * switches. It therefore carries the same `podUrl` stamp and is compared
+ * through the SAME door — {@link lensMatchesPod} from `session-lens.ts`. There
+ * is deliberately no second comparison implementation here; a duplicated
+ * "is this the right pod" rule that drifts is the bug, not the fix.
+ *
+ * ── Write safety ─────────────────────────────────────────────────────────────
+ * Writes never escape the user's own tree: the target is either an EXISTING
+ * lens found on the upward walk (only when it sits at or below the home dir) or
+ * the cwd itself. A lens is never created in an ancestor, never above the home
+ * dir, and never at the filesystem root.
+ */
+import { type SessionLens } from "./session-lens.js";
+/** A directory lens is the same shape as a session lens — same fields, different lifetime. */
+export type DirectoryLens = SessionLens;
+export interface FoundDirectoryLens {
+    lens: DirectoryLens;
+    /** Absolute path to the `.synap/lens.json` that supplied it — shown by `synap lens`. */
+    file: string;
+    /** The directory that owns it (the one containing `.synap/`). */
+    dir: string;
+}
+/**
+ * Every directory to consider, nearest first: the cwd, then each ancestor.
+ * The walk STOPS after the home dir (a lens above `~` would apply to every
+ * unrelated project on the machine) and at the filesystem root.
+ */
+export declare function lensSearchPath(startDir?: string): string[];
+/**
+ * The nearest directory lens at or above `startDir`, ignoring pod qualification.
+ * Callers that are about to SEND ids must use {@link resolveDirectoryLensForPod}.
+ */
+export declare function findDirectoryLens(startDir?: string): FoundDirectoryLens | null;
+/**
+ * The nearest directory lens, but ONLY if it belongs to `podUrl`.
+ *
+ * A lens stamped with a different pod returns null so the caller falls through
+ * to the next rung (env var, then the pod-qualified global config) instead of
+ * sending a foreign workspace id. Comparison is delegated to `lensMatchesPod`
+ * — including its deliberate leniency for lenses written before the `podUrl`
+ * stamp existed.
+ */
+export declare function resolveDirectoryLensForPod(podUrl: string | undefined, startDir?: string): FoundDirectoryLens | null;
+/**
+ * The fields of a directory lens that are in force for THIS process.
+ *
+ * Workspace and project are the tree's durable scope and always apply. The
+ * focus SESSION does not, inside a Claude Code conversation: a session is the
+ * conversation's own, and `attachActiveSessionId` writes it to the session lens
+ * there for exactly that reason. Read through, a directory-lens session —
+ * attached from a plain terminal, or migrated from a `.synap-session` — was
+ * sent as `X-Session-Id` by every conversation opened in the tree, long after
+ * it went quiet, so each one's writes were filed into that old session (and a
+ * stale one was revived by them). Outside Claude Code there is no conversation
+ * to own a session, so the directory lens still carries it.
+ */
+export declare function effectiveDirectoryLens(lens: DirectoryLens): DirectoryLens;
+/**
+ * Where would a write land? An existing lens on the upward walk wins (so
+ * `synap use` from a subdirectory re-pins the repo's lens rather than seeding a
+ * nested one), but only when that lens sits at or below the home dir. Otherwise
+ * the cwd — a lens is never CREATED in an ancestor.
+ */
+export declare function directoryLensWriteTarget(startDir?: string): string;
+/**
+ * Merge-write the directory lens. Returns the file it wrote, so the caller can
+ * TELL the user which path now owns their scope — a silently-resolved lens is
+ * exactly what produced the 403 class this module exists to make legible.
+ */
+export declare function writeDirectoryLens(patch: Partial<DirectoryLens>, startDir?: string): {
+    lens: DirectoryLens;
+    file: string;
+    dir: string;
+};
+/**
+ * Clear one field (or the whole lens) from the nearest directory lens.
+ * Returns the file touched, or null when there was nothing to clear.
+ */
+export declare function clearDirectoryLensField(field?: keyof DirectoryLens, startDir?: string): string | null;

package/dist/lib/directory-lens.js

@@ -0,0 +1,187 @@
+/**
+ * Per-DIRECTORY lens — the durable default scope for a working tree.
+ *
+ * RATIFIED MODEL: a directory's `.synap/lens.json` is where a lens normally
+ * lives; the per-Claude-session lens (`session-lens.ts`) is an explicit
+ * OVERRIDE on top of it.
+ *
+ * The session lens alone could not express "this repo is always Builder" — it
+ * dies with the tab, so every new session started pod-wide (or, worse, on
+ * whatever the global config happened to hold) and the operator re-pinned by
+ * hand. A directory lens is discovered the way git discovers `.git`: walk UP
+ * from the cwd until a `.synap/lens.json` turns up.
+ *
+ * Full precedence, highest first (assembled in `hub-client.ts`):
+ *
+ *   explicit flag  ›  session lens  ›  DIRECTORY LENS  ›  env var  ›  global config
+ *
+ * ── Pod qualification ────────────────────────────────────────────────────────
+ * Workspace and project ids are POD-LOCAL: sending workspace W (pod A) to pod B
+ * is the "Access denied to workspace" 403. A directory lens is exposed to that
+ * hazard MORE than a session lens is, because it outlives many `synap pods use`
+ * switches. It therefore carries the same `podUrl` stamp and is compared
+ * through the SAME door — {@link lensMatchesPod} from `session-lens.ts`. There
+ * is deliberately no second comparison implementation here; a duplicated
+ * "is this the right pod" rule that drifts is the bug, not the fix.
+ *
+ * ── Write safety ─────────────────────────────────────────────────────────────
+ * Writes never escape the user's own tree: the target is either an EXISTING
+ * lens found on the upward walk (only when it sits at or below the home dir) or
+ * the cwd itself. A lens is never created in an ancestor, never above the home
+ * dir, and never at the filesystem root.
+ */
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { getClaudeSessionId, lensMatchesPod } from "./session-lens.js";
+import { writeSecretFile } from "./atomic-file.js";
+/** The directory name a lens lives in, and the file inside it. */
+const LENS_DIR_NAME = ".synap";
+const LENS_FILE_NAME = "lens.json";
+function lensFileIn(dir) {
+    return path.join(dir, LENS_DIR_NAME, LENS_FILE_NAME);
+}
+/** Is `dir` the home dir or inside it? Used to bound where a lens may be WRITTEN. */
+function isAtOrBelowHome(dir) {
+    const home = path.resolve(os.homedir());
+    const target = path.resolve(dir);
+    if (target === home)
+        return true;
+    return target.startsWith(home + path.sep);
+}
+/**
+ * Every directory to consider, nearest first: the cwd, then each ancestor.
+ * The walk STOPS after the home dir (a lens above `~` would apply to every
+ * unrelated project on the machine) and at the filesystem root.
+ */
+export function lensSearchPath(startDir = process.cwd()) {
+    const home = path.resolve(os.homedir());
+    const dirs = [];
+    let dir = path.resolve(startDir);
+    for (;;) {
+        dirs.push(dir);
+        if (dir === home)
+            break;
+        const parent = path.dirname(dir);
+        if (parent === dir)
+            break; // filesystem root
+        dir = parent;
+    }
+    return dirs;
+}
+/** Read + parse one candidate, or null when absent/corrupt. A malformed lens must not crash the CLI. */
+function readLensFile(dir) {
+    const file = lensFileIn(dir);
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf-8"));
+        if (!parsed || typeof parsed !== "object")
+            return null;
+        return { lens: parsed, file, dir };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * The nearest directory lens at or above `startDir`, ignoring pod qualification.
+ * Callers that are about to SEND ids must use {@link resolveDirectoryLensForPod}.
+ */
+export function findDirectoryLens(startDir) {
+    for (const dir of lensSearchPath(startDir)) {
+        const found = readLensFile(dir);
+        if (found)
+            return found;
+    }
+    return null;
+}
+/**
+ * The nearest directory lens, but ONLY if it belongs to `podUrl`.
+ *
+ * A lens stamped with a different pod returns null so the caller falls through
+ * to the next rung (env var, then the pod-qualified global config) instead of
+ * sending a foreign workspace id. Comparison is delegated to `lensMatchesPod`
+ * — including its deliberate leniency for lenses written before the `podUrl`
+ * stamp existed.
+ */
+export function resolveDirectoryLensForPod(podUrl, startDir) {
+    const found = findDirectoryLens(startDir);
+    if (!found)
+        return null;
+    return lensMatchesPod(found.lens, podUrl) ? found : null;
+}
+/**
+ * The fields of a directory lens that are in force for THIS process.
+ *
+ * Workspace and project are the tree's durable scope and always apply. The
+ * focus SESSION does not, inside a Claude Code conversation: a session is the
+ * conversation's own, and `attachActiveSessionId` writes it to the session lens
+ * there for exactly that reason. Read through, a directory-lens session —
+ * attached from a plain terminal, or migrated from a `.synap-session` — was
+ * sent as `X-Session-Id` by every conversation opened in the tree, long after
+ * it went quiet, so each one's writes were filed into that old session (and a
+ * stale one was revived by them). Outside Claude Code there is no conversation
+ * to own a session, so the directory lens still carries it.
+ */
+export function effectiveDirectoryLens(lens) {
+    if (!getClaudeSessionId())
+        return lens;
+    const { focusSessionId: _conversationOwned, ...scope } = lens;
+    return scope;
+}
+/**
+ * Where would a write land? An existing lens on the upward walk wins (so
+ * `synap use` from a subdirectory re-pins the repo's lens rather than seeding a
+ * nested one), but only when that lens sits at or below the home dir. Otherwise
+ * the cwd — a lens is never CREATED in an ancestor.
+ */
+export function directoryLensWriteTarget(startDir = process.cwd()) {
+    const found = findDirectoryLens(startDir);
+    if (found && isAtOrBelowHome(found.dir))
+        return found.dir;
+    return path.resolve(startDir);
+}
+/**
+ * Merge-write the directory lens. Returns the file it wrote, so the caller can
+ * TELL the user which path now owns their scope — a silently-resolved lens is
+ * exactly what produced the 403 class this module exists to make legible.
+ */
+export function writeDirectoryLens(patch, startDir) {
+    const dir = directoryLensWriteTarget(startDir);
+    const prev = readLensFile(dir)?.lens ?? {};
+    const next = { ...prev, ...patch, updatedAt: Date.now() };
+    const file = lensFileIn(dir);
+    fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+    writeSecretFile(file, JSON.stringify(next, null, 2) + "\n", { mode: 0o600 });
+    return { lens: next, file, dir };
+}
+/**
+ * Clear one field (or the whole lens) from the nearest directory lens.
+ * Returns the file touched, or null when there was nothing to clear.
+ */
+export function clearDirectoryLensField(field, startDir) {
+    const found = findDirectoryLens(startDir);
+    if (!found)
+        return null;
+    if (!field) {
+        try {
+            fs.unlinkSync(found.file);
+        }
+        catch {
+            return null;
+        }
+        return found.file;
+    }
+    if (!(field in found.lens))
+        return null;
+    const next = { ...found.lens };
+    delete next[field];
+    next.updatedAt = Date.now();
+    try {
+        writeSecretFile(found.file, JSON.stringify(next, null, 2) + "\n", { mode: 0o600 });
+    }
+    catch {
+        return null;
+    }
+    return found.file;
+}
+//# sourceMappingURL=directory-lens.js.map

package/dist/lib/directory-lens.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"directory-lens.js","sourceRoot":"","sources":["../../src/lib/directory-lens.ts"],"names":[],"mappings":"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"}

package/dist/lib/exporter-coverage.d.ts

@@ -0,0 +1,71 @@
+/**
+ * What `--from-workspace` / `--from-project` do NOT carry out of a live pod.
+ * ==========================================================================
+ *
+ * `synap market publish --from-workspace <id>` serialises a LIVE workspace
+ * through the pod's `workspaceToPackageDefinition`
+ * (synap-backend/packages/api/src/services/workspace-to-package-definition.ts)
+ * and posts the result. `--from-project` walks the same serialiser for every
+ * workspace a project `uses`, then composes a suite — so the same drop-list
+ * applies to each constituent. That serialiser is a **lossy projection**: it
+ * emits 21 of `packageDefinitionSchema`'s keys and has no projection at all
+ * for the ones below. A workspace carrying them exports WITHOUT them — no
+ * error, no signal.
+ *
+ * Loops stay here deliberately: there is no durable loop row to reverse-
+ * serialise (`createLoopFromDefinition` dissolves into playbooks + triggers).
+ *
+ * `TEMPLATE-DEV-GUIDE.md` used to assert, unqualified, that a
+ * `PackageDefinition` "round-trips". It does not, in this direction, and the
+ * consequence is the shape this repo keeps paying for: an author who built one
+ * of the things below publishes their workspace, ships a thinner-than-expected
+ * package, and gets a success message. Same class as `status ?? "installed"` —
+ * a claim of completeness nobody verified. (Cards authored in Card Studio USED
+ * to be one of these — `workspaceToPackageDefinition` now emits them into
+ * `cells[]`, so that loss is fixed; the list below is what remains.)
+ *
+ * ── WHY THIS LIST IS UNCONDITIONAL, NOT DETECTED ────────────────────────────
+ * The CLI never sees the workspace, only the projection's OUTPUT. "key absent
+ * because the workspace had none" and "key absent because the serialiser cannot
+ * emit it" are indistinguishable from here, and reporting a count would be
+ * inventing a fact. So this warns about the DOOR ("this door does not carry
+ * these"), which is true on every call, rather than about the payload.
+ *
+ * Keeping it honest across the repo boundary is
+ * `test/exporter-coverage-parity.test.ts`, which reads the exporter's own
+ * source and fails if a key listed here has gained an assignment (the list is
+ * stale and over-warns) or if a key it claims to emit has lost one.
+ */
+/** A `packageDefinitionSchema` key the workspace serialiser cannot emit. */
+export interface UnemittedKey {
+    /** The `PackageDefinition` key, verbatim. */
+    key: string;
+    /** What an author actually loses, in product words (Card, not cell). */
+    loses: string;
+}
+/**
+ * Keys with real user-authored content behind them that the serialiser drops.
+ *
+ * DELIBERATELY EXCLUDED, and why — these are absent from the export too, but
+ * warning about them would be noise rather than a loss:
+ *   • `icon` / `color` / `domain` / `workspaceType` — a live workspace has no
+ *     field to read them from (the exporter says so at L107-109). Honest
+ *     under-convergence, not a silent drop.
+ *   • `suggestedEntities` / `suggestedRelations` / `phases` / `composesFrom` —
+ *     authoring-time seed hints and composition metadata. A live workspace has
+ *     real entities, not "suggestions"; there is nothing to derive them from.
+ *   • `capability` / `sourcePackage` / `contentHash` — a non-workspace package
+ *     body and publish-time provenance. Not this door's business.
+ */
+export declare const EXPORTER_UNEMITTED_KEYS: readonly UnemittedKey[];
+/**
+ * The keys the serialiser DOES emit. Not consumed at runtime — it is the other
+ * half of the parity tripwire's assertion, so that "emits" and "does not emit"
+ * are pinned by the same read of the same source and cannot disagree.
+ */
+export declare const EXPORTER_EMITTED_KEYS: readonly string[];
+/**
+ * One human line per dropped key, for `--json`'s `warnings[]` and for the
+ * terminal hint list. Deliberately phrased as a property of the DOOR.
+ */
+export declare function exporterDropWarnings(): string[];