@xfey/tutti 0.1.104 → 0.1.106

package/dist/workspace-ops/index.d.ts

@@ -3,11 +3,11 @@ export { WorkspaceOpsError } from "./errors.js";
 export { commitOwnedPaths, requireOwnedPathsWriteReady } from "./system-commits.js";
 export { collectProjectSourceDiff, createAcceptedCheckpoint, inspectProjectWorkspace, recoverAcceptedCheckpoint, } from "./project-workspace.js";
 export { initializeProjectDocs, readProjectDocsInitializationStatus, syncProjectDocs, } from "./project-docs.js";
-export { uploadReferenceFile } from "./reference-files.js";
+export { readManagedReferenceSnapshotState, uploadReferenceFile, writeManagedReferenceSnapshot, } from "./reference-files.js";
 export { isReferenceFilePath, referenceFileCategoryForPath, referenceFolderGroupForPath, referenceMediaTypeForPath, } from "./reference-metadata.js";
 export { readReferenceFileEntries } from "./reference-tree.js";
 export { readReferenceSummaryEntries, readReferenceSummaryIndex, readReferenceSummaryTargets, referenceSummaryProjectionForEntry, updateReferenceSummaries, } from "./reference-summaries.js";
 export { readViewerAsset, readViewerFile, readViewerSnapshot, readViewerTree } from "./viewer.js";
 export type { WorkspaceOpsErrorCode } from "./errors.js";
-export type { AcceptedCheckpointRecoveryResult, AcceptedCheckpointResult, CreateAcceptedCheckpointOptions, InitializeProjectDocsOptions, InitializeProjectDocsResult, ProjectDocsInitializationContext, ProjectDocsInitializationDocument, ProjectDocsInitializationStatus, ProjectWorkspaceInspection, ReadViewerAssetOptions, ReadViewerFileOptions, ReadViewerTreeOptions, ReferenceFileCategory, ReferenceSummaryProjection, ReferenceSummaryRecord, ReferenceSummaryStatus, ReferenceSummaryTarget, RunDiffSummary, SyncProjectDocsResult, SyncProjectDocsUpdate, UpdateReferenceSummariesOptions, UpdateReferenceSummariesResult, UploadReferenceFileOptions, UploadReferenceFileResult, ViewerAssetResult, ViewerAssetVariant, ViewerEntryKind, ViewerFileContent, ViewerFileResult, ViewerRepoSnapshot, ViewerTreeEntry, ViewerTreeResult, WorkspaceViewerOptions, } from "./types.js";
+export type { AcceptedCheckpointRecoveryResult, AcceptedCheckpointResult, CreateAcceptedCheckpointOptions, InitializeProjectDocsOptions, InitializeProjectDocsResult, ProjectDocsInitializationContext, ProjectDocsInitializationDocument, ProjectDocsInitializationStatus, ProjectWorkspaceInspection, ReadViewerAssetOptions, ReadViewerFileOptions, ReadViewerTreeOptions, ReferenceFileCategory, ReferenceSummaryProjection, ReferenceSummaryRecord, ReferenceSummaryStatus, ReferenceSummaryTarget, RunDiffSummary, SyncProjectDocsResult, SyncProjectDocsUpdate, UpdateReferenceSummariesOptions, UpdateReferenceSummariesResult, UploadReferenceFileOptions, UploadReferenceFileResult, WriteManagedReferenceSnapshotOptions, WriteManagedReferenceSnapshotResult, ManagedReferenceSnapshotState, ViewerAssetResult, ViewerAssetVariant, ViewerEntryKind, ViewerFileContent, ViewerFileResult, ViewerRepoSnapshot, ViewerTreeEntry, ViewerTreeResult, WorkspaceViewerOptions, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/workspace-ops/index.js

@@ -3,7 +3,7 @@ export { WorkspaceOpsError } from "./errors.js";
 export { commitOwnedPaths, requireOwnedPathsWriteReady } from "./system-commits.js";
 export { collectProjectSourceDiff, createAcceptedCheckpoint, inspectProjectWorkspace, recoverAcceptedCheckpoint, } from "./project-workspace.js";
 export { initializeProjectDocs, readProjectDocsInitializationStatus, syncProjectDocs, } from "./project-docs.js";
-export { uploadReferenceFile } from "./reference-files.js";
+export { readManagedReferenceSnapshotState, uploadReferenceFile, writeManagedReferenceSnapshot, } from "./reference-files.js";
 export { isReferenceFilePath, referenceFileCategoryForPath, referenceFolderGroupForPath, referenceMediaTypeForPath, } from "./reference-metadata.js";
 export { readReferenceFileEntries } from "./reference-tree.js";
 export { readReferenceSummaryEntries, readReferenceSummaryIndex, readReferenceSummaryTargets, referenceSummaryProjectionForEntry, updateReferenceSummaries, } from "./reference-summaries.js";

package/dist/workspace-ops/reference-files.d.ts

@@ -1,3 +1,16 @@
-import type { UploadReferenceFileOptions, UploadReferenceFileResult } from "./types.js";
+import type { UploadReferenceFileOptions, UploadReferenceFileResult, WriteManagedReferenceSnapshotOptions, WriteManagedReferenceSnapshotResult, ManagedReferenceSnapshotState } from "./types.js";
 export declare function uploadReferenceFile(options: UploadReferenceFileOptions): UploadReferenceFileResult;
+/**
+ * Writes a caller-managed logical Reference snapshot at one stable path.
+ *
+ * Platform adapters remain responsible for external source identity and
+ * revision discovery. Updates use the committed blob oid as a compare-and-set
+ * boundary so a stale adapter cannot overwrite a newer local snapshot.
+ */
+export declare function writeManagedReferenceSnapshot(options: WriteManagedReferenceSnapshotOptions): WriteManagedReferenceSnapshotResult;
+export declare function readManagedReferenceSnapshotState(options: {
+    workspaceRoot: string;
+    path: string;
+    now?: () => Date;
+}): ManagedReferenceSnapshotState;
 //# sourceMappingURL=reference-files.d.ts.map

package/dist/workspace-ops/reference-files.js

@@ -1,10 +1,13 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { extname, join, posix } from "node:path";
 import { classifyViewerPath } from "@tutti/shared/utils";
-import { MAX_REFERENCE_UPLOAD_BYTES, REFERENCE_DIRECTORY_PATH, REFERENCE_INDEX_PATH, } from "./constants.js";
+import { MAX_REFERENCE_UPLOAD_BYTES, REFERENCE_DIRECTORY_PATH, REFERENCE_IMAGES_DIRECTORY_PATH, REFERENCE_INDEX_PATH, } from "./constants.js";
 import { WorkspaceOpsError } from "./errors.js";
 import { classifyReferenceUpload } from "./reference-metadata.js";
 import { commitOwnedPaths, requireOwnedPathsWriteReady } from "./system-commits.js";
+import { requireNormalizedViewerPath } from "./viewer-paths.js";
+import { readBlob, requireFileEntry } from "./viewer-git.js";
 import { readViewerFile } from "./viewer.js";
 const MAX_REFERENCE_FILE_NAME_BYTES = 240;
 const WINDOWS_RESERVED_FILE_STEMS = /^(?:con|prn|aux|nul|clock\$|com[1-9]|lpt[1-9])$/iu;
@@ -199,4 +202,166 @@ export function uploadReferenceFile(options) {
         commit_oid: resolvedCommitOid,
     };
 }
+function managedReferenceSnapshotPath(path) {
+    const repoPath = requireNormalizedViewerPath(path);
+    if (repoPath !== path || !repoPath.startsWith(`${REFERENCE_DIRECTORY_PATH}/`)) {
+        throw new WorkspaceOpsError("validation_failed", "Managed reference snapshot path must be normalized and inside the Reference directory");
+    }
+    if (repoPath === REFERENCE_INDEX_PATH) {
+        throw new WorkspaceOpsError("validation_failed", "Managed reference snapshot cannot replace the Reference index");
+    }
+    const fileName = posix.basename(repoPath);
+    if (normalizeReferenceFileName(fileName) !== fileName) {
+        throw new WorkspaceOpsError("validation_failed", "Managed reference snapshot file name is not normalized");
+    }
+    const directoryPath = posix.dirname(repoPath);
+    const category = repoPath.startsWith(`${REFERENCE_IMAGES_DIRECTORY_PATH}/`)
+        ? "image"
+        : "file";
+    return { repoPath, directoryPath, fileName, category };
+}
+function readManagedSnapshotPathEntry(path) {
+    try {
+        return lstatSync(path);
+    }
+    catch (error) {
+        if (typeof error === "object" && error !== null && "code" in error && error.code === "ENOENT") {
+            return undefined;
+        }
+        throw new WorkspaceOpsError("forbidden", "Managed reference snapshot path could not be inspected", { reason_code: "managed_reference_snapshot_path_unavailable" });
+    }
+}
+function inspectManagedReferenceSnapshotFilesystemPath(options) {
+    const segments = options.repoPath.split("/");
+    let currentPath = options.workspaceRoot;
+    for (const [index, segment] of segments.entries()) {
+        currentPath = join(currentPath, segment);
+        const entry = readManagedSnapshotPathEntry(currentPath);
+        if (entry === undefined) {
+            return {
+                filesystemPath: join(options.workspaceRoot, ...segments),
+                exists: false,
+            };
+        }
+        if (entry.isSymbolicLink()) {
+            throw new WorkspaceOpsError("forbidden", "Managed reference snapshot path must not traverse a symbolic link", { reason_code: "managed_reference_snapshot_symlink" });
+        }
+        const isTarget = index === segments.length - 1;
+        if (!isTarget && !entry.isDirectory()) {
+            throw new WorkspaceOpsError("conflict", "Managed reference snapshot parent path is not a directory", { reason_code: "managed_reference_snapshot_parent_invalid" });
+        }
+        if (isTarget && !entry.isFile()) {
+            throw new WorkspaceOpsError("conflict", "Managed reference snapshot target is not a regular file", { reason_code: "managed_reference_snapshot_target_invalid" });
+        }
+    }
+    return {
+        filesystemPath: join(options.workspaceRoot, ...segments),
+        exists: true,
+    };
+}
+/**
+ * Writes a caller-managed logical Reference snapshot at one stable path.
+ *
+ * Platform adapters remain responsible for external source identity and
+ * revision discovery. Updates use the committed blob oid as a compare-and-set
+ * boundary so a stale adapter cannot overwrite a newer local snapshot.
+ */
+export function writeManagedReferenceSnapshot(options) {
+    if (options.content.byteLength > MAX_REFERENCE_UPLOAD_BYTES) {
+        throw new WorkspaceOpsError("validation_failed", `Managed reference snapshot cannot exceed ${MAX_REFERENCE_UPLOAD_BYTES} bytes`);
+    }
+    const { repoPath, directoryPath, fileName, category } = managedReferenceSnapshotPath(options.path);
+    const pathState = inspectManagedReferenceSnapshotFilesystemPath({
+        workspaceRoot: options.workspaceRoot,
+        repoPath,
+    });
+    const filesystemPath = pathState.filesystemPath;
+    const indexOwnedPaths = pathState.exists ? [repoPath] : [REFERENCE_INDEX_PATH, repoPath];
+    requireOwnedPathsWriteReady(options.workspaceRoot, indexOwnedPaths);
+    let previous;
+    if (pathState.exists) {
+        previous = readViewerFile({
+            workspaceRoot: options.workspaceRoot,
+            path: repoPath,
+            ...(options.now === undefined ? {} : { now: options.now }),
+        });
+        if (options.expectedBlobOid === undefined) {
+            throw new WorkspaceOpsError("conflict", "Managed reference snapshot already exists", {
+                reason_code: "managed_reference_snapshot_exists",
+            });
+        }
+        if (previous.file.blob_oid !== options.expectedBlobOid) {
+            throw new WorkspaceOpsError("conflict", "Managed reference snapshot changed before this update", { reason_code: "managed_reference_snapshot_stale" });
+        }
+        if (sameFileContent(filesystemPath, options.content)) {
+            return {
+                disposition: "unchanged",
+                file: previous.file,
+                category,
+                index_path: REFERENCE_INDEX_PATH,
+                previous_blob_oid: previous.file.blob_oid,
+                commit_oid: previous.snapshot.head.oid,
+            };
+        }
+    }
+    else if (options.expectedBlobOid !== undefined) {
+        throw new WorkspaceOpsError("conflict", "Managed reference snapshot no longer exists", {
+            reason_code: "managed_reference_snapshot_missing",
+        });
+    }
+    mkdirSync(join(options.workspaceRoot, ...directoryPath.split("/")), { recursive: true });
+    writeFileSync(filesystemPath, options.content);
+    if (previous === undefined) {
+        appendReferenceIndexEntry({
+            workspaceRoot: options.workspaceRoot,
+            fileName,
+            repoPath,
+            category,
+            ...(options.note === undefined ? {} : { note: options.note }),
+        });
+    }
+    const commitOid = commitOwnedPaths({
+        workspaceRoot: options.workspaceRoot,
+        paths: indexOwnedPaths,
+        message: previous === undefined
+            ? `Add managed reference snapshot: ${fileName}`
+            : `Update managed reference snapshot: ${fileName}`,
+    });
+    const file = readViewerFile({
+        workspaceRoot: options.workspaceRoot,
+        path: repoPath,
+        ...(options.now === undefined ? {} : { now: options.now }),
+    });
+    return {
+        disposition: previous === undefined ? "created" : "updated",
+        file: file.file,
+        category,
+        index_path: REFERENCE_INDEX_PATH,
+        ...(previous === undefined ? {} : { previous_blob_oid: previous.file.blob_oid }),
+        ...(commitOid === null ? {} : { commit_oid: commitOid }),
+    };
+}
+export function readManagedReferenceSnapshotState(options) {
+    const { repoPath } = managedReferenceSnapshotPath(options.path);
+    const pathState = inspectManagedReferenceSnapshotFilesystemPath({
+        workspaceRoot: options.workspaceRoot,
+        repoPath,
+    });
+    requireOwnedPathsWriteReady(options.workspaceRoot, pathState.exists ? [repoPath] : [REFERENCE_INDEX_PATH, repoPath]);
+    if (!pathState.exists) {
+        return { exists: false, path: repoPath };
+    }
+    const entry = requireFileEntry({
+        workspaceRoot: options.workspaceRoot,
+        path: repoPath,
+    });
+    const content = readBlob(options.workspaceRoot, entry.oid, entry.size);
+    return {
+        exists: true,
+        path: repoPath,
+        blob_oid: entry.oid,
+        content_sha256: `sha256:${createHash("sha256").update(content).digest("hex")}`,
+        size_bytes: entry.size,
+    };
+}
 //# sourceMappingURL=reference-files.js.map

package/dist/workspace-ops/types.d.ts

@@ -123,6 +123,30 @@ export type UploadReferenceFileResult = {
     index_path: typeof REFERENCE_INDEX_PATH;
     commit_oid?: string;
 };
+export type WriteManagedReferenceSnapshotOptions = WorkspaceViewerOptions & {
+    path: string;
+    content: Buffer;
+    expectedBlobOid?: string;
+    note?: string;
+};
+export type WriteManagedReferenceSnapshotResult = {
+    disposition: "created" | "updated" | "unchanged";
+    file: ViewerFileResult["file"];
+    category: ReferenceFileCategory;
+    index_path: typeof REFERENCE_INDEX_PATH;
+    previous_blob_oid?: string;
+    commit_oid?: string;
+};
+export type ManagedReferenceSnapshotState = {
+    exists: false;
+    path: string;
+} | {
+    exists: true;
+    path: string;
+    blob_oid: string;
+    content_sha256: string;
+    size_bytes: number;
+};
 export type UpdateReferenceSummariesOptions = WorkspaceViewerOptions & {
     summaries: ReferenceSummaryRecord[];
 };

package/migrations/0018_platform_outbound_events.sql

@@ -0,0 +1,111 @@
+CREATE TABLE platform_outbound_intents_v2 (
+  intent_ref TEXT PRIMARY KEY CHECK (intent_ref GLOB 'idem_*'),
+  platform TEXT NOT NULL CHECK (platform = 'feishu'),
+  installation_ref TEXT NOT NULL,
+  binding_ref TEXT NOT NULL,
+  event_kind TEXT NOT NULL CHECK (
+    event_kind IN ('chat_response', 'needs_input', 'task_completed', 'task_failed')
+  ),
+  event_key TEXT NOT NULL UNIQUE,
+  subject_kind TEXT NOT NULL CHECK (
+    subject_kind IN ('message', 'clarification_round', 'approval_request', 'task_result')
+  ),
+  subject_ref TEXT NOT NULL,
+  target_kind TEXT NOT NULL CHECK (target_kind IN ('project', 'work')),
+  trigger_message_id TEXT,
+  canonical_message_id TEXT UNIQUE,
+  content_text TEXT CHECK (content_text IS NULL OR length(content_text) BETWEEN 1 AND 4000),
+  disposition TEXT NOT NULL CHECK (
+    disposition IN ('pending', 'sending', 'retry_wait', 'handed_off', 'terminal')
+  ),
+  attempt_count INTEGER NOT NULL DEFAULT 0 CHECK (attempt_count >= 0),
+  next_attempt_at TEXT,
+  last_attempt_at TEXT,
+  delivery_ref TEXT,
+  error_code TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  handed_off_at TEXT,
+  FOREIGN KEY (trigger_message_id) REFERENCES messages(id) ON DELETE RESTRICT,
+  FOREIGN KEY (canonical_message_id) REFERENCES messages(id) ON DELETE RESTRICT,
+  CHECK (canonical_message_id IS NOT NULL OR content_text IS NOT NULL),
+  CHECK (
+    event_kind != 'chat_response'
+    OR (
+      trigger_message_id IS NOT NULL
+      AND canonical_message_id IS NOT NULL
+      AND subject_kind = 'message'
+      AND target_kind = 'project'
+      AND content_text IS NULL
+    )
+  ),
+  CHECK (
+    (disposition = 'handed_off' AND delivery_ref IS NOT NULL AND handed_off_at IS NOT NULL)
+    OR disposition != 'handed_off'
+  )
+);
+
+INSERT INTO platform_outbound_intents_v2 (
+  intent_ref,
+  platform,
+  installation_ref,
+  binding_ref,
+  event_kind,
+  event_key,
+  subject_kind,
+  subject_ref,
+  target_kind,
+  trigger_message_id,
+  canonical_message_id,
+  content_text,
+  disposition,
+  attempt_count,
+  next_attempt_at,
+  last_attempt_at,
+  delivery_ref,
+  error_code,
+  created_at,
+  updated_at,
+  handed_off_at
+)
+SELECT
+  intent_ref,
+  platform,
+  installation_ref,
+  binding_ref,
+  'chat_response',
+  'chat_response:' || canonical_message_id,
+  'message',
+  canonical_message_id,
+  'project',
+  trigger_message_id,
+  canonical_message_id,
+  NULL,
+  disposition,
+  attempt_count,
+  next_attempt_at,
+  last_attempt_at,
+  delivery_ref,
+  error_code,
+  created_at,
+  updated_at,
+  handed_off_at
+FROM platform_outbound_intents;
+
+DROP TABLE platform_outbound_intents;
+ALTER TABLE platform_outbound_intents_v2 RENAME TO platform_outbound_intents;
+
+CREATE INDEX platform_outbound_intents_due
+  ON platform_outbound_intents (disposition, next_attempt_at, created_at, intent_ref);
+
+CREATE INDEX platform_outbound_intents_trigger
+  ON platform_outbound_intents (trigger_message_id, created_at, intent_ref);
+
+CREATE INDEX platform_outbound_intents_event
+  ON platform_outbound_intents (event_kind, subject_kind, subject_ref, created_at);
+
+CREATE TABLE platform_outbound_event_capture_state (
+  id INTEGER PRIMARY KEY CHECK (id = 1),
+  capture_after TEXT NOT NULL,
+  updated_at TEXT NOT NULL
+);

package/migrations/0019_platform_outbound_card_content.sql

@@ -0,0 +1,76 @@
+CREATE TABLE platform_outbound_intents_v3 (
+  intent_ref TEXT PRIMARY KEY CHECK (intent_ref GLOB 'idem_*'),
+  platform TEXT NOT NULL CHECK (platform = 'feishu'),
+  installation_ref TEXT NOT NULL,
+  binding_ref TEXT NOT NULL,
+  event_kind TEXT NOT NULL CHECK (
+    event_kind IN ('chat_response', 'needs_input', 'task_completed', 'task_failed')
+  ),
+  event_key TEXT NOT NULL UNIQUE,
+  subject_kind TEXT NOT NULL CHECK (
+    subject_kind IN ('message', 'clarification_round', 'approval_request', 'task_result')
+  ),
+  subject_ref TEXT NOT NULL,
+  target_kind TEXT NOT NULL CHECK (target_kind IN ('project', 'work')),
+  trigger_message_id TEXT,
+  canonical_message_id TEXT UNIQUE,
+  content_text TEXT CHECK (content_text IS NULL OR length(content_text) BETWEEN 1 AND 4000),
+  content_json TEXT CHECK (content_json IS NULL OR length(content_json) BETWEEN 2 AND 32768),
+  disposition TEXT NOT NULL CHECK (
+    disposition IN ('pending', 'sending', 'retry_wait', 'handed_off', 'terminal')
+  ),
+  attempt_count INTEGER NOT NULL DEFAULT 0 CHECK (attempt_count >= 0),
+  next_attempt_at TEXT,
+  last_attempt_at TEXT,
+  delivery_ref TEXT,
+  error_code TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  handed_off_at TEXT,
+  FOREIGN KEY (trigger_message_id) REFERENCES messages(id) ON DELETE RESTRICT,
+  FOREIGN KEY (canonical_message_id) REFERENCES messages(id) ON DELETE RESTRICT,
+  CHECK (
+    canonical_message_id IS NOT NULL OR content_text IS NOT NULL OR content_json IS NOT NULL
+  ),
+  CHECK (content_text IS NULL OR content_json IS NULL),
+  CHECK (
+    event_kind != 'chat_response'
+    OR (
+      trigger_message_id IS NOT NULL
+      AND canonical_message_id IS NOT NULL
+      AND subject_kind = 'message'
+      AND target_kind = 'project'
+      AND content_text IS NULL
+      AND content_json IS NULL
+    )
+  ),
+  CHECK (
+    (disposition = 'handed_off' AND delivery_ref IS NOT NULL AND handed_off_at IS NOT NULL)
+    OR disposition != 'handed_off'
+  )
+);
+
+INSERT INTO platform_outbound_intents_v3 (
+  intent_ref, platform, installation_ref, binding_ref, event_kind, event_key,
+  subject_kind, subject_ref, target_kind, trigger_message_id, canonical_message_id,
+  content_text, content_json, disposition, attempt_count, next_attempt_at,
+  last_attempt_at, delivery_ref, error_code, created_at, updated_at, handed_off_at
+)
+SELECT
+  intent_ref, platform, installation_ref, binding_ref, event_kind, event_key,
+  subject_kind, subject_ref, target_kind, trigger_message_id, canonical_message_id,
+  content_text, NULL, disposition, attempt_count, next_attempt_at,
+  last_attempt_at, delivery_ref, error_code, created_at, updated_at, handed_off_at
+FROM platform_outbound_intents;
+
+DROP TABLE platform_outbound_intents;
+ALTER TABLE platform_outbound_intents_v3 RENAME TO platform_outbound_intents;
+
+CREATE INDEX platform_outbound_intents_due
+  ON platform_outbound_intents (disposition, next_attempt_at, created_at, intent_ref);
+
+CREATE INDEX platform_outbound_intents_trigger
+  ON platform_outbound_intents (trigger_message_id, created_at, intent_ref);
+
+CREATE INDEX platform_outbound_intents_event
+  ON platform_outbound_intents (event_kind, subject_kind, subject_ref, created_at);

package/migrations/0020_managed_reference_sources.sql

@@ -0,0 +1,34 @@
+CREATE TABLE managed_reference_sources (
+  source_ref TEXT PRIMARY KEY,
+  adapter_key TEXT NOT NULL,
+  reference_path TEXT NOT NULL UNIQUE,
+  accepted_revision_ref TEXT,
+  accepted_blob_oid TEXT,
+  accepted_content_sha256 TEXT,
+  last_operation_ref TEXT,
+  last_expected_blob_oid TEXT,
+  last_outcome TEXT CHECK (last_outcome IS NULL OR last_outcome IN ('created', 'updated', 'unchanged')),
+  pending_operation_ref TEXT,
+  pending_revision_ref TEXT,
+  pending_content_sha256 TEXT,
+  pending_expected_blob_oid TEXT,
+  side_effects_pending INTEGER NOT NULL DEFAULT 0 CHECK (side_effects_pending IN (0, 1)),
+  last_checked_at TEXT,
+  last_accepted_at TEXT,
+  created_at TEXT NOT NULL,
+  updated_at TEXT NOT NULL,
+  CHECK (
+    (accepted_revision_ref IS NULL AND accepted_blob_oid IS NULL AND accepted_content_sha256 IS NULL)
+    OR
+    (accepted_revision_ref IS NOT NULL AND accepted_blob_oid IS NOT NULL AND accepted_content_sha256 IS NOT NULL)
+  ),
+  CHECK (
+    (pending_operation_ref IS NULL AND pending_revision_ref IS NULL AND pending_content_sha256 IS NULL)
+    OR
+    (pending_operation_ref IS NOT NULL AND pending_revision_ref IS NOT NULL AND pending_content_sha256 IS NOT NULL)
+  )
+);
+
+CREATE INDEX managed_reference_sources_pending_idx
+  ON managed_reference_sources (side_effects_pending, updated_at)
+  WHERE side_effects_pending = 1;

package/migrations/README.md

@@ -30,10 +30,13 @@
 - `0015_control_plane_intents.sql`：新增 Control Plane durable dispatch intent，保存 bounded kind / owner / dedupe / lane、pending-to-running claim lease 与 terminal 状态，为 Clarification、Task Compile、Scratchpad、Reference Summary 和 Run 提供可恢复的 runtime handoff；同时用 immutable pending Task Compile submission row 固化 context capture 前的 workflow / main-chat cursor boundary，不保存 prompt、消息正文、provider output、secret 或 host path。
 - `0016_external_source_mappings.sql`：新增external installation / message identity到既有`messages.id`的一对一mapping和append-only revision observation；mapped message evidence、mapping identity与observations由trigger / FK保护，不保存raw platform payload、credential或短期URL。
 - `0017_platform_outbound_intents.sql`：新增Host-owned platform outbound intent；只引用canonical / trigger message与installation / binding locator，保存handoff attempt和terminal状态，不复制回复正文或保存conversation ref / credential。
+- `0018_platform_outbound_events.sql`：把旧Chat response intent无损迁移为event-aware schema，新增stable event / subject / Project-or-Work target、approval bounded snapshot与首次status capture boundary；不回填升级前clarification / Task terminal消息。
+- `0019_platform_outbound_card_content.sql`：把approval outbound snapshot从text扩展为经过internal schema验证的structured card content，同时无损保留既有intent、handoff与重试状态；不保存conversation、platform action或callback receipt。
+- `0020_managed_reference_sources.sql`：保存opaque managed source / adapter /稳定Reference path、accepted revision / blob / digest、pending operation与写后副作用恢复checkpoint；不保存平台document locator、credential、正文、staged URL或Relay authority。
 
 ## 当前实现状态
 
-- `0001_init.sql` 至 `0017_platform_outbound_intents.sql` 已存在，代表当前 host project SQLite schema contract。`0014` 明确采用开发数据库重建策略，不提供旧 Scratchpad source/cursor 数据兼容；`0016`–`0017`是additive migration，不要求为既有internal Chat message或agent response回填external mapping / outbound intent。
+- `0001_init.sql` 至 `0020_managed_reference_sources.sql` 已存在，代表当前 host project SQLite schema contract。`0014` 明确采用开发数据库重建策略，不提供旧 Scratchpad source/cursor 数据兼容；`0016`–`0017`不要求为既有internal Chat message或agent response回填external mapping / outbound intent，`0018`保留旧intent并以runtime capture boundary阻止历史status回填，`0019`无损加入structured card content，`0020`加入独立managed Reference recovery checkpoint。
 - SQLite adapter、migration runner、checksum 校验、store metadata 初始化、transaction helper 与 command recovery scan helper 已实现。
 - 协作 repository 与 Control Plane 已实现第一批业务读写；Phase 7 首批已复用 `0001_init.sql` 中的 `tasks.latest_run_result_id`、`task_details.result_json` 与 `run_results` 表完成 Run result / checks / promotion 摘要持久化。Control Plane recovery resolver 与 task-bound continuation / retry 复用现有 schema；新 Run 的 accepted checkpoint 业务 truth 继续写入最终 Run result / task detail result，Git tag / commit trailer 承担 crash recovery evidence。Timeline 默认从 `tasks`、`run_results` 与历史主群聊 `refs.worklist_feedback` 投影任务级审计节点，当前 task terminal Chat feedback 写入 `refs.task_result` 消息；`project_timeline_events` 只保留缺少稳定 record 的轻量可观测性事件和历史 reconcile 兼容记录。project workspace、working diff 与 ignored runtime state 都不进入 SQLite truth。`provider_usage_events` 只保存 token 计数、调用来源、模型名、记录时间和可空 anchor，不保存 provider secret、prompt 或 raw response。store 基础设施本身已经可以创建并迁移 `tutti.sqlite`。
 

package/node_modules/@tutti/relay-client/dist/host-control.d.ts

@@ -1,7 +1,7 @@
 import { type HostConnectionRef, type IdempotencyKey, type ProjectId, type RelayProjectRef, type RelayUploadRef } from "@tutti/shared/ids";
 import type { ProjectSurfaceProfile } from "@tutti/shared/domain";
 import type { RelayUploadPurpose, Sha256Digest } from "@tutti/shared/schemas/api";
-import { type FeishuSetupProjection, type PlatformOutboundHandoffResponse, type PlatformOutboundTextIntent } from "@tutti/shared/schemas/internal";
+import { type FeishuSetupProjection, type PlatformOutboundHandoffResponse, type PlatformOutboundIntent } from "@tutti/shared/schemas/internal";
 export type RelayHostControlFetch = (input: string | URL, init?: RequestInit) => Promise<Response>;
 export type RelayProjectProjection = {
     relay_project_ref: RelayProjectRef;
@@ -44,7 +44,10 @@ export type RegisterRelayHostConnectionPayload = {
             browser_secret_write: false;
             repo_viewer: boolean;
             integration_source_ingestion_v1?: boolean;
+            integration_attachment_ingestion_v1?: boolean;
+            integration_managed_reference_ingestion_v1?: boolean;
             integration_outbound_v1?: boolean;
+            integration_approval_decision_v1?: boolean;
         };
     };
     join_token?: {
@@ -139,7 +142,7 @@ export type DeliverRelayPlatformOutboundOptions = {
     relayProjectRef: RelayProjectRef;
     hostConnectionRef: HostConnectionRef;
     hostRegistrationSecret: string;
-    intent: PlatformOutboundTextIntent;
+    intent: PlatformOutboundIntent;
     fetch?: RelayHostControlFetch;
     timeoutMs?: number;
     signal?: AbortSignal;

package/node_modules/@tutti/relay-client/dist/host-control.js

@@ -57,7 +57,10 @@ function createRegisterPayload(options) {
                 browser_secret_write: false,
                 repo_viewer: capabilities.repo_viewer ?? false,
                 integration_source_ingestion_v1: capabilities.integration_source_ingestion_v1 ?? false,
+                integration_attachment_ingestion_v1: capabilities.integration_attachment_ingestion_v1 ?? false,
+                integration_managed_reference_ingestion_v1: capabilities.integration_managed_reference_ingestion_v1 ?? false,
                 integration_outbound_v1: capabilities.integration_outbound_v1 ?? false,
+                integration_approval_decision_v1: capabilities.integration_approval_decision_v1 ?? false,
             },
         },
     };

package/node_modules/@tutti/shared/dist/schemas/api/index.d.ts

@@ -5,8 +5,8 @@ export { CompleteDesktopEntryContinuationBodySchema, CompleteDesktopEntryContinu
 export type { CompleteDesktopEntryContinuationBody, CreateDesktopEntryContinuationResponse, GetDesktopEntryContinuationResponse, SealedDesktopEntryPayload, } from "./desktop-entry-continuations.js";
 export { LOCAL_CONSOLE_ACCOUNT_HANDOFF_TOKEN_MAX_LENGTH, LOCAL_CONSOLE_ACCOUNT_HANDOFF_TOKEN_MIN_LENGTH, RegisterLocalConsoleAccountHandoffBodySchema, RegisterLocalConsoleAccountHandoffResponseSchema, } from "./local-console-account-handoffs.js";
 export type { RegisterLocalConsoleAccountHandoffBody, RegisterLocalConsoleAccountHandoffResponse, } from "./local-console-account-handoffs.js";
-export { FEISHU_H5_AUTHORIZATION_CODE_MAX_LENGTH, FEISHU_H5_REQUIRED_USER_SCOPE, FEISHU_PLATFORM_STATE_LENGTH, FeishuPlatformSessionBootstrapBodySchema, FeishuPlatformSessionBootstrapResponseSchema, FeishuPlatformSessionExchangeBodySchema, FeishuPlatformSessionProjectionSchema, FeishuPlatformStateSchema, } from "./platform-sessions.js";
-export type { FeishuPlatformSessionBootstrapBody, FeishuPlatformSessionBootstrapResponse, FeishuPlatformSessionExchangeBody, FeishuPlatformSessionProjection, } from "./platform-sessions.js";
+export { FEISHU_BROWSER_HANDOFF_TOKEN_LENGTH, FEISHU_DOCX_REQUIRED_USER_SCOPE, FEISHU_H5_AUTHORIZATION_CODE_MAX_LENGTH, FEISHU_H5_REQUIRED_USER_SCOPE, FEISHU_PLATFORM_STATE_LENGTH, FeishuPlatformSessionBootstrapBodySchema, FeishuPlatformSessionBootstrapResponseSchema, FeishuBrowserHandoffResponseSchema, FeishuBrowserHandoffTokenSchema, ConsumeFeishuBrowserHandoffBodySchema, FeishuDocumentAuthorizationBootstrapResponseSchema, FeishuDocumentAuthorizationExchangeBodySchema, FeishuDocumentAuthorizationProjectionSchema, FeishuPlatformSessionExchangeBodySchema, FeishuPlatformSessionProjectionSchema, FeishuPlatformStateSchema, } from "./platform-sessions.js";
+export type { FeishuPlatformSessionBootstrapBody, FeishuPlatformSessionBootstrapResponse, FeishuBrowserHandoffResponse, ConsumeFeishuBrowserHandoffBody, FeishuDocumentAuthorizationBootstrapResponse, FeishuDocumentAuthorizationExchangeBody, FeishuDocumentAuthorizationProjection, FeishuPlatformSessionExchangeBody, FeishuPlatformSessionProjection, } from "./platform-sessions.js";
 export { ApiErrorCodeSchema, ApiErrorResponseSchema, CommandDispositionBaseSchema, CursorPageRequestSchema, DEFAULT_SSE_REPLAY_WINDOW_POLICY, InterruptedCommandDispositionSchema, QueryInvalidationHintSchema, RelayInvalidationHintSchema, RelaySseEventTypeSchema, SseReplayWindowPolicySchema, WorkspaceSseEventTypeSchema, commandEnvelopeSchema, commandResponseSchema, commandResponseWithResultSchema, cursorPageSchema, relaySseEventSchema, timelineWindowSchema, workspaceSseEventSchema, } from "./primitives.js";
 export { GetProviderModelsResponseSchema, MAX_PROVIDER_MODEL_NAME_LENGTH, ProviderConfigInvalidReasonCodeSchema, ProviderConfigProjectionSchema, ProviderModelDiscoveryUnavailableReasonSchema, ProviderModelNameSchema, ProviderModelValidationFailureReasonSchema, ProviderUnavailableReasonCodeSchema, ProjectProviderUnavailableReasonSchema, UpdateProviderDefaultModelBodySchema, UpdateProviderDefaultModelDispositionSchema, UpdateProviderDefaultModelPayloadSchema, UpdateProviderDefaultModelResponseSchema, } from "./provider-config.js";
 export { ProviderUsageBreakdownProjectionSchema, ProviderUsageCategorySchema, ProviderUsageModelSummaryProjectionSchema, ProviderUsageProjectionSchema, ProviderUsageSourceSummaryProjectionSchema, } from "./provider-usage.js";

package/node_modules/@tutti/shared/dist/schemas/api/index.js

@@ -2,7 +2,7 @@ export * from "./openapi.js";
 export { ARTIFACT_FEEDBACK_MAX_ANNOTATIONS, ARTIFACT_FEEDBACK_MAX_AUTHORED_TEXT_LENGTH, ARTIFACT_FEEDBACK_MAX_COMMENT_LENGTH, ARTIFACT_FEEDBACK_MAX_SERIALIZED_BYTES, ARTIFACT_FEEDBACK_MAX_SUMMARY_LENGTH, ArtifactElementAnchorSchema, ArtifactElementKindSchema, ArtifactElementTargetSchema, ArtifactFeedbackAnnotationSchema, ArtifactFeedbackCommandSchema, ArtifactFeedbackRefSchema, ArtifactSemanticContextSchema, ArtifactSemanticSnapshotSchema, ArtifactSemanticStateSchema, } from "./artifact-feedback.js";
 export { CompleteDesktopEntryContinuationBodySchema, CompleteDesktopEntryContinuationResponseSchema, CreateDesktopEntryContinuationResponseSchema, DESKTOP_ENTRY_COMPLETION_TOKEN_LENGTH, DESKTOP_ENTRY_PAYLOAD_KEY_LENGTH, DESKTOP_ENTRY_SEALED_IV_LENGTH, DesktopEntryCompletionTokenSchema, DesktopEntryContinuationPendingProjectionSchema, DesktopEntryContinuationReadyProjectionSchema, DesktopEntryPayloadKeySchema, GetDesktopEntryContinuationResponseSchema, MAX_DESKTOP_ENTRY_SEALED_CIPHERTEXT_LENGTH, SealedDesktopEntryPayloadSchema, } from "./desktop-entry-continuations.js";
 export { LOCAL_CONSOLE_ACCOUNT_HANDOFF_TOKEN_MAX_LENGTH, LOCAL_CONSOLE_ACCOUNT_HANDOFF_TOKEN_MIN_LENGTH, RegisterLocalConsoleAccountHandoffBodySchema, RegisterLocalConsoleAccountHandoffResponseSchema, } from "./local-console-account-handoffs.js";
-export { FEISHU_H5_AUTHORIZATION_CODE_MAX_LENGTH, FEISHU_H5_REQUIRED_USER_SCOPE, FEISHU_PLATFORM_STATE_LENGTH, FeishuPlatformSessionBootstrapBodySchema, FeishuPlatformSessionBootstrapResponseSchema, FeishuPlatformSessionExchangeBodySchema, FeishuPlatformSessionProjectionSchema, FeishuPlatformStateSchema, } from "./platform-sessions.js";
+export { FEISHU_BROWSER_HANDOFF_TOKEN_LENGTH, FEISHU_DOCX_REQUIRED_USER_SCOPE, FEISHU_H5_AUTHORIZATION_CODE_MAX_LENGTH, FEISHU_H5_REQUIRED_USER_SCOPE, FEISHU_PLATFORM_STATE_LENGTH, FeishuPlatformSessionBootstrapBodySchema, FeishuPlatformSessionBootstrapResponseSchema, FeishuBrowserHandoffResponseSchema, FeishuBrowserHandoffTokenSchema, ConsumeFeishuBrowserHandoffBodySchema, FeishuDocumentAuthorizationBootstrapResponseSchema, FeishuDocumentAuthorizationExchangeBodySchema, FeishuDocumentAuthorizationProjectionSchema, FeishuPlatformSessionExchangeBodySchema, FeishuPlatformSessionProjectionSchema, FeishuPlatformStateSchema, } from "./platform-sessions.js";
 export { ApiErrorCodeSchema, ApiErrorResponseSchema, CommandDispositionBaseSchema, CursorPageRequestSchema, DEFAULT_SSE_REPLAY_WINDOW_POLICY, InterruptedCommandDispositionSchema, QueryInvalidationHintSchema, RelayInvalidationHintSchema, RelaySseEventTypeSchema, SseReplayWindowPolicySchema, WorkspaceSseEventTypeSchema, commandEnvelopeSchema, commandResponseSchema, commandResponseWithResultSchema, cursorPageSchema, relaySseEventSchema, timelineWindowSchema, workspaceSseEventSchema, } from "./primitives.js";
 export { GetProviderModelsResponseSchema, MAX_PROVIDER_MODEL_NAME_LENGTH, ProviderConfigInvalidReasonCodeSchema, ProviderConfigProjectionSchema, ProviderModelDiscoveryUnavailableReasonSchema, ProviderModelNameSchema, ProviderModelValidationFailureReasonSchema, ProviderUnavailableReasonCodeSchema, ProjectProviderUnavailableReasonSchema, UpdateProviderDefaultModelBodySchema, UpdateProviderDefaultModelDispositionSchema, UpdateProviderDefaultModelPayloadSchema, UpdateProviderDefaultModelResponseSchema, } from "./provider-config.js";
 export { ProviderUsageBreakdownProjectionSchema, ProviderUsageCategorySchema, ProviderUsageModelSummaryProjectionSchema, ProviderUsageProjectionSchema, ProviderUsageSourceSummaryProjectionSchema, } from "./provider-usage.js";

package/node_modules/@tutti/shared/dist/schemas/api/platform-sessions.d.ts

@@ -1,8 +1,11 @@
 import type { Static } from "@sinclair/typebox";
 export declare const FEISHU_H5_AUTHORIZATION_CODE_MAX_LENGTH = 2048;
 export declare const FEISHU_H5_REQUIRED_USER_SCOPE = "im:chat.members:read";
+export declare const FEISHU_DOCX_REQUIRED_USER_SCOPE = "docx:document:readonly";
 export declare const FEISHU_PLATFORM_STATE_LENGTH = 43;
+export declare const FEISHU_BROWSER_HANDOFF_TOKEN_LENGTH = 43;
 export declare const FeishuPlatformStateSchema: import("@sinclair/typebox").TString;
+export declare const FeishuBrowserHandoffTokenSchema: import("@sinclair/typebox").TString;
 export declare const FeishuPlatformSessionBootstrapBodySchema: import("@sinclair/typebox").TObject<{
     relay_project_ref: import("@sinclair/typebox").TString;
 }>;
@@ -36,8 +39,39 @@ export declare const FeishuPlatformSessionProjectionSchema: import("@sinclair/ty
         transport: import("@sinclair/typebox").TLiteral<"http_only_cookie">;
     }>;
 }>;
+export declare const FeishuDocumentAuthorizationBootstrapResponseSchema: import("@sinclair/typebox").TObject<{
+    platform: import("@sinclair/typebox").TLiteral<"feishu">;
+    app_id: import("@sinclair/typebox").TString;
+    state: import("@sinclair/typebox").TString;
+    authorization_scopes: import("@sinclair/typebox").TTuple<[import("@sinclair/typebox").TLiteral<"docx:document:readonly">]>;
+    expires_at: import("@sinclair/typebox").TString;
+}>;
+export declare const FeishuDocumentAuthorizationExchangeBodySchema: import("@sinclair/typebox").TObject<{
+    state: import("@sinclair/typebox").TString;
+    authorization_code: import("@sinclair/typebox").TString;
+}>;
+export declare const FeishuDocumentAuthorizationProjectionSchema: import("@sinclair/typebox").TObject<{
+    platform: import("@sinclair/typebox").TLiteral<"feishu">;
+    status: import("@sinclair/typebox").TLiteral<"authorized">;
+    authorized_at: import("@sinclair/typebox").TString;
+}>;
+export declare const FeishuBrowserHandoffResponseSchema: import("@sinclair/typebox").TObject<{
+    platform: import("@sinclair/typebox").TLiteral<"feishu">;
+    relay_project_ref: import("@sinclair/typebox").TString;
+    handoff_token: import("@sinclair/typebox").TString;
+    expires_at: import("@sinclair/typebox").TString;
+}>;
+export declare const ConsumeFeishuBrowserHandoffBodySchema: import("@sinclair/typebox").TObject<{
+    relay_project_ref: import("@sinclair/typebox").TString;
+    handoff_token: import("@sinclair/typebox").TString;
+}>;
 export type FeishuPlatformSessionBootstrapBody = Static<typeof FeishuPlatformSessionBootstrapBodySchema>;
 export type FeishuPlatformSessionBootstrapResponse = Static<typeof FeishuPlatformSessionBootstrapResponseSchema>;
 export type FeishuPlatformSessionExchangeBody = Static<typeof FeishuPlatformSessionExchangeBodySchema>;
 export type FeishuPlatformSessionProjection = Static<typeof FeishuPlatformSessionProjectionSchema>;
+export type FeishuDocumentAuthorizationBootstrapResponse = Static<typeof FeishuDocumentAuthorizationBootstrapResponseSchema>;
+export type FeishuDocumentAuthorizationExchangeBody = Static<typeof FeishuDocumentAuthorizationExchangeBodySchema>;
+export type FeishuDocumentAuthorizationProjection = Static<typeof FeishuDocumentAuthorizationProjectionSchema>;
+export type FeishuBrowserHandoffResponse = Static<typeof FeishuBrowserHandoffResponseSchema>;
+export type ConsumeFeishuBrowserHandoffBody = Static<typeof ConsumeFeishuBrowserHandoffBodySchema>;
 //# sourceMappingURL=platform-sessions.d.ts.map