@cerbur/clutch-dsh-worktree 0.1.0

package/lib/provider/sidecar.js

@@ -0,0 +1,410 @@
+import { lstat, mkdir, readFile, rename, unlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { SIDECAR_SCHEMA_VERSION, WorktreeProviderError, providerError, } from './types.js';
+const WORKTREE_KEYS = ['absolutePath', 'branch', 'status', 'workspaceId', 'worktreeId'];
+const BINDING_KEYS = ['sessionId', 'status', 'workspaceId', 'worktreeId'];
+const SNAPSHOT_KEYS = ['bindings', 'schemaVersion', 'workspaceId', 'worktrees'];
+function isObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/*
+ * 每个 schema version 使用精确字段白名单，避免新版或注入字段被旧代码静默接受、随后在
+ * 重写时丢失。格式演进必须显式提升 schema version。
+ *
+ * Each schema version uses an exact key allowlist so newer or injected fields
+ * are not silently accepted and then lost on rewrite. Format evolution must be
+ * represented by an explicit schema-version change.
+ */
+function hasExactKeys(value, keys) {
+    return JSON.stringify(Object.keys(value).sort()) === JSON.stringify([...keys].sort());
+}
+// 可读取但不满足 schema/invariant 的数据属于 `SIDECAR_CORRUPT`；文件系统故障另报 `SIDECAR_UNAVAILABLE`。
+// Readable data that violates the schema or invariants is `SIDECAR_CORRUPT`;
+// filesystem failures are reported separately as `SIDECAR_UNAVAILABLE`.
+function corrupt(pathname, message, details = {}) {
+    return providerError('SIDECAR_CORRUPT', `${message}: ${pathname}`, { path: pathname, ...details });
+}
+function assertWorktreeRecord(value, pathname) {
+    if (!isObject(value) ||
+        !hasExactKeys(value, WORKTREE_KEYS) ||
+        typeof value.worktreeId !== 'string' ||
+        typeof value.workspaceId !== 'string' ||
+        typeof value.absolutePath !== 'string' ||
+        !path.isAbsolute(value.absolutePath) ||
+        typeof value.branch !== 'string' ||
+        (value.status !== 'active' && value.status !== 'removed')) {
+        throw corrupt(pathname, 'invalid Worktree record');
+    }
+}
+function assertBinding(value, pathname) {
+    if (!isObject(value) ||
+        !hasExactKeys(value, BINDING_KEYS) ||
+        typeof value.workspaceId !== 'string' ||
+        typeof value.worktreeId !== 'string' ||
+        typeof value.sessionId !== 'string' ||
+        (value.status !== 'active' && value.status !== 'detached')) {
+        throw corrupt(pathname, 'invalid Session binding');
+    }
+}
+/**
+ * 校验完整 sidecar 快照及跨记录不变量：shard Workspace 身份一致、Worktree ID 唯一、
+ * 每个 Session 至多一个 active binding，且 active binding 必须指向 active Worktree。
+ *
+ * Validates a complete sidecar snapshot and its cross-record invariants: one
+ * Workspace identity per shard, unique Worktree IDs, at most one active binding
+ * per Session, and every active binding targeting an active Worktree.
+ *
+ * 提供 `generatedWorktreeRoot` 时，还要求 Provider 生成的 ID 合法且路径精确等于
+ * `<generatedWorktreeRoot>/<worktreeId>`。detached binding 可继续指向 removed 记录，
+ * 以保留删除后的关系历史。
+ *
+ * When `generatedWorktreeRoot` is supplied, Provider-generated IDs must be
+ * valid and paths must equal `<generatedWorktreeRoot>/<worktreeId>` exactly.
+ * Detached bindings may continue to reference removed records so relationships
+ * survive Worktree removal.
+ */
+export function validateSidecarSnapshot(value, pathname, generatedWorktreeRoot) {
+    if (!isObject(value) ||
+        !hasExactKeys(value, SNAPSHOT_KEYS) ||
+        value.schemaVersion !== SIDECAR_SCHEMA_VERSION ||
+        typeof value.workspaceId !== 'string' ||
+        !Array.isArray(value.worktrees) ||
+        !Array.isArray(value.bindings)) {
+        throw corrupt(pathname, 'invalid sidecar snapshot');
+    }
+    for (const record of value.worktrees)
+        assertWorktreeRecord(record, pathname);
+    for (const binding of value.bindings)
+        assertBinding(binding, pathname);
+    const workspaceId = value.workspaceId;
+    const worktreeIds = new Set();
+    for (const record of value.worktrees) {
+        if (record.workspaceId !== workspaceId) {
+            throw corrupt(pathname, 'Worktree record belongs to another Workspace');
+        }
+        if (worktreeIds.has(record.worktreeId)) {
+            throw corrupt(pathname, 'sidecar contains duplicate Worktree IDs');
+        }
+        worktreeIds.add(record.worktreeId);
+        if (generatedWorktreeRoot) {
+            // 这是词法路径约束；关键父目录的物理 symlink 边界由 I/O 前的检查单独负责。
+            // This is a lexical path constraint; physical symlink boundaries for the
+            // critical parent directories are checked separately before I/O.
+            if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(record.worktreeId)) {
+                throw corrupt(pathname, 'Worktree record has an invalid generated ID');
+            }
+            const expectedPath = path.resolve(generatedWorktreeRoot, record.worktreeId);
+            if (path.resolve(record.absolutePath) !== expectedPath) {
+                throw corrupt(pathname, 'Worktree path is outside the generated DSH Home root');
+            }
+        }
+    }
+    for (const binding of value.bindings) {
+        if (binding.workspaceId !== workspaceId) {
+            throw corrupt(pathname, 'Session binding belongs to another Workspace');
+        }
+    }
+    const activeSessions = new Set();
+    for (const binding of value.bindings) {
+        if (binding.status !== 'active')
+            continue;
+        if (activeSessions.has(binding.sessionId)) {
+            throw corrupt(pathname, 'Session has more than one active Worktree binding');
+        }
+        activeSessions.add(binding.sessionId);
+    }
+    // 只有 detached binding 可以保留对非 active Worktree 的关系；active 状态绝不静默降级。
+    // Only detached bindings may retain a relationship to a non-active Worktree;
+    // an active relationship is never silently downgraded.
+    const worktreeStatus = new Map(value.worktrees.map((record) => [record.worktreeId, record.status]));
+    for (const binding of value.bindings) {
+        if (binding.status === 'active' && worktreeStatus.get(binding.worktreeId) !== 'active') {
+            throw corrupt(pathname, 'active binding does not point to an active Worktree');
+        }
+    }
+    return {
+        schemaVersion: SIDECAR_SCHEMA_VERSION,
+        workspaceId,
+        worktrees: value.worktrees,
+        bindings: value.bindings,
+    };
+}
+function emptySnapshot(workspaceId) {
+    return {
+        schemaVersion: SIDECAR_SCHEMA_VERSION,
+        workspaceId,
+        worktrees: [],
+        bindings: [],
+    };
+}
+function sameWorktree(left, right) {
+    return (left.worktreeId === right.worktreeId &&
+        left.workspaceId === right.workspaceId &&
+        left.absolutePath === right.absolutePath &&
+        left.branch === right.branch &&
+        left.status === right.status);
+}
+function sameBinding(left, right) {
+    return (left.workspaceId === right.workspaceId &&
+        left.worktreeId === right.worktreeId &&
+        left.sessionId === right.sessionId &&
+        left.status === right.status);
+}
+/*
+ * 互斥范围是“同一 repository 实例 + 同一 Workspace key”。它让该实例内的 mutation
+ * 依次读取最新快照，但不会假装协调其他进程或其他 repository 实例；异常也会在 finally
+ * 中释放队列，避免后续操作永久阻塞。
+ *
+ * Mutual exclusion is scoped to one repository instance and one Workspace key.
+ * It makes mutations in that instance read the latest snapshot serially, but
+ * does not pretend to coordinate another process or repository instance;
+ * failures still release the queue in `finally` so later work cannot deadlock.
+ */
+class KeyedMutex {
+    tails = new Map();
+    async run(key, operation) {
+        const previous = this.tails.get(key) ?? Promise.resolve();
+        let release;
+        const current = new Promise((resolve) => {
+            release = resolve;
+        });
+        this.tails.set(key, current);
+        await previous;
+        try {
+            return await operation();
+        }
+        finally {
+            release();
+            if (this.tails.get(key) === current)
+                this.tails.delete(key);
+        }
+    }
+}
+/**
+ * 位于 DSH Home 下、按 Workspace 分 shard 的 sidecar repository；它只持久化外部
+ * Worktree/Session 关系，不读取或写入 DSH 原始数据及 Workspace 业务文件。
+ *
+ * Workspace-sharded sidecar repository under DSH Home; it persists only the
+ * external Worktree/Session relationship and never reads or writes DSH-owned
+ * data or Workspace business files.
+ *
+ * 同一实例内的 mutation 按 Workspace 串行化，并通过同目录临时文件加 rename 提供完整旧版或
+ * 完整新版的原子可见性；这不等同于跨进程锁，也不承诺 fsync 级崩溃持久性。
+ *
+ * Mutations are serialized per Workspace within one instance, and a temporary
+ * file plus same-directory rename provides complete-old-or-complete-new atomic
+ * visibility. This is neither a cross-process lock nor an fsync-level crash
+ * durability guarantee.
+ */
+export class WorkspaceShardedSidecarRepository {
+    pluginRoot;
+    worktreeRoot;
+    workspaceRoot;
+    dshHome;
+    mutex = new KeyedMutex();
+    constructor({ dshHome }) {
+        if (!path.isAbsolute(dshHome)) {
+            throw providerError('SIDECAR_UNAVAILABLE', 'DSH Home must be an absolute path', { dshHome });
+        }
+        this.dshHome = path.resolve(dshHome);
+        this.pluginRoot = path.join(this.dshHome, 'clutch-dsh-worktree');
+        this.worktreeRoot = path.join(this.pluginRoot, 'worktree');
+        this.workspaceRoot = path.join(this.pluginRoot, 'workspaces');
+    }
+    /**
+     * 将 Workspace ID 编码为单个稳定文件名，所有 shard 都限定在 Provider 自有目录中。
+     * Encodes a Workspace ID into one stable filename, keeping every shard under
+     * the Provider-owned directory.
+     */
+    getShardPath(workspaceId) {
+        return path.join(this.workspaceRoot, `${encodeURIComponent(workspaceId)}.json`);
+    }
+    /**
+     * 读取并完整校验 shard；文件不存在表示尚无关系并返回空快照，损坏内容绝不自动修复。
+     * Reads and fully validates a shard; a missing file means no relationships yet
+     * and returns an empty snapshot, while corrupt content is never auto-repaired.
+     */
+    async read(workspaceId) {
+        return this.readFromDisk(workspaceId);
+    }
+    /**
+     * 在 Workspace 互斥区内重新读取最新快照、应用转换、复验全部不变量，再决定是否原子写入。
+     * Re-reads the latest snapshot inside the Workspace mutex, applies the
+     * transition, revalidates every invariant, and only then decides whether to
+     * write atomically.
+     *
+     * mutation 抛错、返回非法快照或改变 Workspace 身份时，已有 shard 不会被本方法替换。
+     * If the mutation throws, returns an invalid snapshot, or changes Workspace
+     * identity, this method does not replace the existing shard.
+     */
+    async mutate(workspaceId, mutation) {
+        return this.mutex.run(workspaceId, async () => {
+            const current = await this.readFromDisk(workspaceId);
+            const result = await mutation(current);
+            const next = validateSidecarSnapshot(result.snapshot, this.getShardPath(workspaceId), this.worktreeRoot);
+            if (next.workspaceId !== workspaceId) {
+                throw corrupt(this.getShardPath(workspaceId), 'sidecar mutation changed the Workspace identity');
+            }
+            if (result.changed !== false)
+                await this.writeToDisk(next);
+            return result.result;
+        });
+    }
+    /**
+     * 按 Worktree ID 幂等插入；完全相同的记录直接复用，同一 ID 的不同 metadata 被视为损坏。
+     * Idempotently inserts by Worktree ID; an identical record is reused, while
+     * different metadata under the same ID is treated as corruption.
+     */
+    async upsertWorktree(record) {
+        const { health: _health, ...persistedRecord } = record;
+        void _health;
+        return this.mutate(record.workspaceId, (snapshot) => {
+            const existing = snapshot.worktrees.find((candidate) => candidate.worktreeId === persistedRecord.worktreeId);
+            if (existing) {
+                if (!sameWorktree(existing, persistedRecord)) {
+                    throw providerError('SIDECAR_CORRUPT', 'Worktree ID already contains different metadata', {
+                        worktreeId: persistedRecord.worktreeId,
+                    });
+                }
+                return { result: existing, snapshot, changed: false };
+            }
+            return {
+                result: persistedRecord,
+                snapshot: { ...snapshot, worktrees: [...snapshot.worktrees, persistedRecord] },
+            };
+        });
+    }
+    /**
+     * 按 Session ID 幂等插入 binding；完全相同的关系直接复用，任何既有不同关系都返回冲突。
+     * Idempotently inserts a binding by Session ID; an identical relationship is
+     * reused, while any different existing relationship returns a conflict.
+     */
+    async upsertBinding(binding) {
+        return this.mutate(binding.workspaceId, (snapshot) => {
+            const existing = snapshot.bindings.find((candidate) => candidate.sessionId === binding.sessionId);
+            if (existing) {
+                if (!sameBinding(existing, binding)) {
+                    throw providerError('SESSION_ALREADY_BOUND', 'Session is already bound to another Worktree', {
+                        sessionId: binding.sessionId,
+                        worktreeId: existing.worktreeId,
+                    });
+                }
+                return { result: existing, snapshot, changed: false };
+            }
+            return {
+                result: binding,
+                snapshot: { ...snapshot, bindings: [...snapshot.bindings, binding] },
+            };
+        });
+    }
+    async readFromDisk(workspaceId) {
+        await this.assertStorageBoundary();
+        const shardPath = this.getShardPath(workspaceId);
+        let text;
+        try {
+            text = await readFile(shardPath, 'utf8');
+        }
+        catch (error) {
+            // ENOENT 是未初始化状态；权限、I/O 等其他失败意味着存储不可用，不能伪装成空索引。
+            // ENOENT is an uninitialized state; permission, I/O, and other failures
+            // mean storage is unavailable and must not masquerade as an empty index.
+            if (error.code === 'ENOENT')
+                return emptySnapshot(workspaceId);
+            throw providerError('SIDECAR_UNAVAILABLE', `Unable to read sidecar shard: ${shardPath}`, {
+                path: shardPath,
+                cause: String(error),
+            });
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch (error) {
+            throw providerError('SIDECAR_CORRUPT', `Unable to parse sidecar shard: ${shardPath}`, {
+                path: shardPath,
+                cause: String(error),
+            });
+        }
+        const snapshot = validateSidecarSnapshot(parsed, shardPath, this.worktreeRoot);
+        if (snapshot.workspaceId !== workspaceId) {
+            throw corrupt(shardPath, 'sidecar shard Workspace identity does not match its filename');
+        }
+        return snapshot;
+    }
+    async writeToDisk(snapshot) {
+        await this.assertStorageBoundary();
+        const shardPath = this.getShardPath(snapshot.workspaceId);
+        // 临时文件与目标 shard 位于同一目录，从而避免跨文件系统 rename；随机后缀防止并发残留碰撞。
+        // The temporary file shares the shard directory to avoid a cross-filesystem
+        // rename, and its random suffix prevents collisions with concurrent debris.
+        const temporaryPath = `${shardPath}.${process.pid}.${randomUUID()}.tmp`;
+        try {
+            await mkdir(this.workspaceRoot, { recursive: true });
+            await writeFile(temporaryPath, `${JSON.stringify(snapshot, null, 2)}\n`, {
+                encoding: 'utf8',
+                mode: 0o600,
+            });
+            // 读取者只会观察到完整旧文件或完整新文件；rename 前的临时内容从不作为 shard 读取。
+            // Readers observe either the complete old file or complete new file; the
+            // pre-rename temporary contents are never read as the shard.
+            await rename(temporaryPath, shardPath);
+        }
+        catch (error) {
+            throw providerError('SIDECAR_UNAVAILABLE', `Unable to atomically write sidecar shard: ${shardPath}`, {
+                path: shardPath,
+                temporaryPath,
+                cause: String(error),
+            });
+        }
+        finally {
+            try {
+                await unlink(temporaryPath);
+            }
+            catch (error) {
+                if (error.code !== 'ENOENT') {
+                    // 临时文件的尽力清理失败不能覆盖原始写入结果。
+                    // A failed best-effort temporary-file cleanup must not replace the
+                    // original write result.
+                    void error;
+                }
+            }
+        }
+    }
+    /*
+     * 每次 I/O 前拒绝关键存储父目录本身为 symlink，避免 Provider 自有相对布局被重定向到
+     * Workspace 或 DSH 原始数据位置。目录不存在是首次初始化的正常状态。
+     *
+     * Before each I/O operation, reject critical storage parent directories that
+     * are themselves symlinks so the Provider-owned relative layout cannot be
+     * redirected into a Workspace or DSH-owned data. Missing directories are a
+     * normal first-initialization state.
+     */
+    async assertStorageBoundary() {
+        for (const [pathname, label] of [
+            [this.dshHome, 'DSH Home'],
+            [this.pluginRoot, 'plugin sidecar root'],
+            [this.worktreeRoot, 'Worktree root'],
+            [this.workspaceRoot, 'Workspace shard root'],
+        ]) {
+            try {
+                if ((await lstat(pathname)).isSymbolicLink()) {
+                    throw providerError('SIDECAR_UNAVAILABLE', `${label} must not be a symlink: ${pathname}`, {
+                        path: pathname,
+                    });
+                }
+            }
+            catch (error) {
+                if (error.code === 'ENOENT')
+                    continue;
+                if (error instanceof WorktreeProviderError)
+                    throw error;
+                throw providerError('SIDECAR_UNAVAILABLE', `Unable to inspect ${label}: ${pathname}`, {
+                    path: pathname,
+                    cause: String(error),
+                });
+            }
+        }
+    }
+}
+//# sourceMappingURL=sidecar.js.map

package/lib/provider/sidecar.js.map

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

package/lib/provider/types.d.ts

@@ -0,0 +1,126 @@
+import type { SessionBinding, WorktreeErrorCode, WorktreeErrorDetails, WorktreeRecord, WorkspaceId } from '../contract/index.js';
+/**
+ * 当前 sidecar 磁盘格式的唯一受支持版本；未知版本会被视为损坏，而不是被静默猜测或迁移。
+ * The only supported on-disk sidecar format; unknown versions are treated as
+ * corruption rather than guessed or silently migrated.
+ */
+export declare const SIDECAR_SCHEMA_VERSION: 1;
+/**
+ * 从 DSH 投影出的最小 Workspace 事实；Provider 不拥有、复制或写回这些数据。
+ * Minimal Workspace facts projected from DSH; the Provider neither owns,
+ * persists, nor writes these values back.
+ */
+export interface DshWorkspaceSummary {
+    readonly workspaceId: WorkspaceId;
+    readonly projectId?: string;
+    readonly rootPath: string;
+}
+/**
+ * 从 DSH Session header 投影出的只读事实；`cwd` 仅用于校验绑定关系，不成为 sidecar 数据。
+ * Read-only facts projected from a DSH Session header; `cwd` is used only to
+ * validate a binding and never becomes sidecar-owned data.
+ */
+export interface DshSessionSummary {
+    readonly sessionId: string;
+    readonly workspaceId?: WorkspaceId;
+    readonly projectId?: string;
+    readonly cwd: string;
+}
+/**
+ * DSH 唯一数据源的只读端口；该接口刻意不暴露任何 Workspace 或 Session mutation。
+ * Read-only port to the DSH source of truth; it deliberately exposes no
+ * Workspace or Session mutation capability.
+ */
+export interface DshReadAdapter {
+    getWorkspace(workspaceId: WorkspaceId): Promise<DshWorkspaceSummary | undefined>;
+    getSession(sessionId: string): Promise<DshSessionSummary | undefined>;
+    listSessions(): Promise<readonly DshSessionSummary[]>;
+}
+/**
+ * `git worktree list --porcelain` 的最小投影；detached HEAD 等条目可以没有本地 branch。
+ * Minimal projection of `git worktree list --porcelain`; entries such as a
+ * detached HEAD may have no local branch.
+ */
+export interface GitWorktreeInfo {
+    readonly absolutePath: string;
+    readonly branch?: string;
+}
+/**
+ * Git worktree 的窄端口：只允许校验、列举、创建和删除，不提供任意 Git、远程或业务文件操作。
+ * Narrow Git worktree port: it permits validation, listing, creation, and
+ * removal only, with no arbitrary Git, remote, or working-file operations.
+ */
+export interface GitWorktreeAdapter {
+    validateRepository(workspaceRoot: string): Promise<void>;
+    listBranches(workspaceRoot: string): Promise<readonly string[]>;
+    listWorktrees(workspaceRoot: string): Promise<readonly GitWorktreeInfo[]>;
+    createWorktree(workspaceRoot: string, targetPath: string, branch: string, newBranch?: string): Promise<void>;
+    removeWorktree(workspaceRoot: string, targetPath: string): Promise<void>;
+}
+/**
+ * 单个 Workspace shard 的完整外部关系快照；这里只保存 Worktree 元数据和 Session binding。
+ * Complete external-relation snapshot for one Workspace shard; it contains
+ * only Worktree metadata and Session bindings.
+ */
+export interface SidecarSnapshot {
+    readonly schemaVersion: typeof SIDECAR_SCHEMA_VERSION;
+    readonly workspaceId: WorkspaceId;
+    readonly worktrees: readonly WorktreeRecord[];
+    readonly bindings: readonly SessionBinding[];
+}
+/**
+ * 一次 mutation 的返回值和完整下一快照；`changed: false` 表示幂等命中并跳过磁盘替换。
+ * Result and complete next snapshot of one mutation; `changed: false` marks an
+ * idempotent hit and skips disk replacement.
+ *
+ * 即使跳过写入，具体 repository 仍会校验返回的快照，避免幂等分支绕过不变量。
+ * Even when persistence is skipped, the concrete repository still validates
+ * the returned snapshot so an idempotent branch cannot bypass invariants.
+ */
+export interface SidecarMutation<T> {
+    readonly result: T;
+    readonly snapshot: SidecarSnapshot;
+    readonly changed?: boolean;
+}
+/**
+ * sidecar 持久化端口；调用方通过一次 `mutate` 提交完整状态转换，不自行拼接 read/write 竞态窗口。
+ * Sidecar persistence port; callers submit a complete state transition through
+ * one `mutate` call instead of composing a racy read/write pair themselves.
+ */
+export interface SidecarStore {
+    read(workspaceId: WorkspaceId): Promise<SidecarSnapshot>;
+    mutate<T>(workspaceId: WorkspaceId, mutation: (snapshot: SidecarSnapshot) => SidecarMutation<T> | Promise<SidecarMutation<T>>): Promise<T>;
+}
+/**
+ * Provider/Manage 边界使用的结构化错误；稳定 code 供调用方分支，details 保留诊断上下文。
+ * Structured error used across the Provider/Manage boundary; callers branch on
+ * the stable code while details retain diagnostic context.
+ */
+export declare class WorktreeProviderError extends Error {
+    readonly code: WorktreeErrorCode;
+    readonly details: WorktreeErrorDetails;
+    constructor(code: WorktreeErrorCode, message: string, details?: WorktreeErrorDetails);
+    /**
+     * 生成可安全投影到 Remote/日志边界的纯数据表示，不包含 stack 或运行时原型。
+     * Produces a plain-data representation safe for Remote/logging boundaries,
+     * excluding the stack and runtime prototype.
+     */
+    toJSON(): {
+        code: WorktreeErrorCode;
+        message: string;
+        details: WorktreeErrorDetails;
+    };
+}
+/**
+ * 统一构造 Provider 错误，确保 code、message 和 details 使用同一错误类型传播。
+ * Constructs Provider errors consistently so code, message, and details travel
+ * through a single error type.
+ */
+export declare function providerError(code: WorktreeErrorCode, message: string, details?: WorktreeErrorDetails): WorktreeProviderError;
+/**
+ * 仅识别当前运行时中的真实 `WorktreeProviderError` 实例；反序列化后的同形对象不会通过。
+ * Recognizes genuine `WorktreeProviderError` instances in this runtime only;
+ * a structurally identical deserialized object does not pass this guard.
+ */
+export declare function isWorktreeProviderError(error: unknown): error is WorktreeProviderError;
+//# sourceMappingURL=types.d.ts.map

package/lib/provider/types.d.ts.map

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

package/lib/provider/types.js

@@ -0,0 +1,46 @@
+/**
+ * 当前 sidecar 磁盘格式的唯一受支持版本；未知版本会被视为损坏，而不是被静默猜测或迁移。
+ * The only supported on-disk sidecar format; unknown versions are treated as
+ * corruption rather than guessed or silently migrated.
+ */
+export const SIDECAR_SCHEMA_VERSION = 1;
+/**
+ * Provider/Manage 边界使用的结构化错误；稳定 code 供调用方分支，details 保留诊断上下文。
+ * Structured error used across the Provider/Manage boundary; callers branch on
+ * the stable code while details retain diagnostic context.
+ */
+export class WorktreeProviderError extends Error {
+    code;
+    details;
+    constructor(code, message, details = {}) {
+        super(message);
+        this.name = 'WorktreeProviderError';
+        this.code = code;
+        this.details = details;
+    }
+    /**
+     * 生成可安全投影到 Remote/日志边界的纯数据表示，不包含 stack 或运行时原型。
+     * Produces a plain-data representation safe for Remote/logging boundaries,
+     * excluding the stack and runtime prototype.
+     */
+    toJSON() {
+        return { code: this.code, message: this.message, details: this.details };
+    }
+}
+/**
+ * 统一构造 Provider 错误，确保 code、message 和 details 使用同一错误类型传播。
+ * Constructs Provider errors consistently so code, message, and details travel
+ * through a single error type.
+ */
+export function providerError(code, message, details = {}) {
+    return new WorktreeProviderError(code, message, details);
+}
+/**
+ * 仅识别当前运行时中的真实 `WorktreeProviderError` 实例；反序列化后的同形对象不会通过。
+ * Recognizes genuine `WorktreeProviderError` instances in this runtime only;
+ * a structurally identical deserialized object does not pass this guard.
+ */
+export function isWorktreeProviderError(error) {
+    return error instanceof WorktreeProviderError;
+}
+//# sourceMappingURL=types.js.map

package/lib/provider/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/provider/types.ts"],"names":[],"mappings":"AAQA;;;;GAIG;AACH,MAAM,CAAC,MAAM,sBAAsB,GAAG,CAAU,CAAC;AAwGjD;;;;GAIG;AACH,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IACrC,IAAI,CAAoB;IACxB,OAAO,CAAuB;IAEvC,YAAY,IAAuB,EAAE,OAAe,EAAE,UAAgC,EAAE;QACtF,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,OAAO,GAAG,OAAO,CAAC;IACzB,CAAC;IAED;;;;OAIG;IACH,MAAM;QACJ,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;IAC3E,CAAC;CACF;AAED;;;;GAIG;AACH,MAAM,UAAU,aAAa,CAC3B,IAAuB,EACvB,OAAe,EACf,UAAgC,EAAE;IAElC,OAAO,IAAI,qBAAqB,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;AAC3D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,uBAAuB,CAAC,KAAc;IACpD,OAAO,KAAK,YAAY,qBAAqB,CAAC;AAChD,CAAC"}

package/lib/typert.host.d.ts

@@ -0,0 +1,3 @@
+/* Generated by @deepseek-ai/dsh-typert-generator from FaceModel — do not edit. */
+
+export declare const TYPERT: unknown