@xfey/tutti 0.1.105 → 0.1.106

package/README.md

@@ -35,7 +35,7 @@
 
 - 已具备 Fastify host shell、后台 host manager CLI 套件、用户级 desktop integration / strict `tutti://projects` bridge、带 `service status / stop / restart`、卸载前 `shutdown`、并发启动锁、版本替换、strict terminal / desktop browser context、当前 runtime version bootstrap projection、idle / package update cleanup、全机readiness、exact npm global install、跨版本worker / recovery与私有日志的机器级 Local Console、Dev Runner、Host Project API、SSE、SQLite store、collaboration-state、workspace read-state、project timeline observability helper、Control Plane、Procedure / Run、workspace-ops、checks、Relay staged upload finalize、user skills 文件服务、artifacts 可视化产物查看层、current-generation Artifact feedback message / model formatter、Owner-only provider model discovery / update 和 OpenAI / Codex provider 接入。
 - 新 Host project 的空群聊会由 collaboration-state 幂等写入一条 Tutti 欢迎消息；它不经过 browser message command，不触发 `@tutti`、Chat read-state、Scratchpad 或 Timeline / execution 流程。
-- Feishu external source触发的主群聊Chat Assistant回复会在canonical message transaction中建立`platform_outbound_intents`，后台通过当前Host credential交给Relay；`handed_off`只表示Integration durable outbox已接受，不表示飞书最终delivered。
+- Feishu external source触发的主群聊Chat Assistant回复会在canonical message transaction中建立`platform_outbound_intents`；新clarification / approval和Task terminal也会以稳定event identity进入同一Host durable worker。后台通过当前Host credential交给Relay，`handed_off`只表示Integration durable outbox已接受，不表示飞书最终delivered。
 - Host server 与 Local Console 支持在显式 `webStatic.root` 或 packaged `web/` 存在时服务 Web 静态产物；`/api/*`、SSE、health、host-local control 和 `/local-console/*` API 不被 SPA fallback 吞掉。
 - Root `pack:dry-run` 会先清理 build output、重新构建，再复制 `apps/web/dist` 到 package-local `web/`，生成临时 staging `@xfey/tutti` artifact，并校验 npm pack 文件列表包含 CLI、migrations、prompts、Web index、bundled `@tutti/shared` / `@tutti/relay-client` 以及它们的外部 runtime dependencies，同时排除源码、source map、日志、SQLite、`.env`、`.tutti-dev` 与测试产物。
 - Root `smoke:packed-cli` 同样从干净 build output 生成 staging `@xfey/tutti` tarball、在临时目录安装，并验证 SQLite native binding、`tutti --help` / desktop help / `tutti service --help` / `tutti service status` / `tutti shutdown --help` / `tutti launch --help` / `tutti archive --help` / `tutti --version`、desktop assets、migrations、prompts、Web static index、bundled internal dependencies、bundled external runtime dependencies、CLI QR dependency、仓库锁定的 `@openai/codex` binary 可执行性和临时全局安装路径；该 smoke 不需要 Tutti source repo 存在。
@@ -57,7 +57,7 @@
 - host 注册使用 machine-local `host_registration_secret`；该 secret 明文只可写入受限权限的 machine-local secret store，不写入目标项目 repo、Git local config 项目身份、SQLite 协作真相或日志，`binding.json` 只保存引用。
 - Relay registration 成功后只把 `relay_project_ref` 写回 machine-local binding；Standalone join URL只在host本机终端或当前host-local control内存状态中展示，不写入binding、runtime endpoint、SQLite协作真相或日志。Feishu project不签发join URL。
 - 普通 `tutti launch` 默认后台运行 host；Standalone完成页展示join URL，Feishu完成页只确认collaboration surface，然后CLI退出。`tutti launch --foreground` 保留前台诊断模式。后台spawn为每次启动生成唯一`startup_attempt_ref`，源码入口会先把`tsx` loader解析为不受目标project cwd影响的绝对URL；spawn、endpoint等待、Relay readiness、内部启动失败与timeout使用同一ref写入`TUTTI_HOME/logs/host.log`。Host HTTP request log 与 Control Plane / Run Pipeline runtime log也写入该文件，不写入目标项目 repo 或常规 CLI stdout。
-- Standalone Host只接受普通`relay_session_context`工作区请求；Feishu Host接受`feishu_platform_session_context` browser请求和固定internal path的`integration_delivery`。三种metadata严格三选一，cross-Surface browser request在进入Fastify业务route前403。Feishu browser只开放Project / Work精确只读allowlist；Host outbound使用独立host-control route，不借用browser transport。无状态`/api/v1/openapi.json`诊断仍可生成contract。
+- Standalone Host只接受普通`relay_session_context`工作区请求；Feishu Host接受`feishu_platform_session_context` browser请求和固定internal path的`integration_delivery`。三种metadata严格三选一，cross-Surface browser request在进入Fastify业务route前403。Feishu browser只经Relay开放Project / Work / References / Artifacts精确query / command allowlist；References复用Host既有列表、Viewer文本与图片route，Artifacts复用既有projection、bodyless lease与raw preview route，不新增Host truth或upload route。Host仍执行相同actor、command idempotency与Control Plane逻辑。Host outbound使用独立host-control route，不借用browser transport。无状态`/api/v1/openapi.json`诊断仍可生成contract。
 - Reference 和 Skills 上传的最终写入由 Host Project API 完成；Host 只通过 Relay host-control resolve 获取短期 R2 URL 下载 staged object，不接收浏览器 base64 文件正文，也不持久化 presigned URL。
 - Host Project API的browser session context只信任Relay tunnel metadata中的Surface-matched variant；route handler不读取浏览器身份header，也不接受payload内身份字段。Feishu session在兼容projection中使用`client_session.transport = "feishu_platform_session"`，不代表创建Standalone Relay client session。
 - Artifact feedback 仍写入现有 `messages` truth并复用command idempotency；Host只在当前ready generation完全匹配时接受，Anchor技术字段仅保留审计ref，模型上下文使用bounded semantic formatter。

package/dist/approvals/decision-command.d.ts

@@ -0,0 +1,124 @@
+import type { ApprovalRequestId, IdempotencyKey } from "@tutti/shared/ids";
+import type { SqliteDatabase } from "../store/index.js";
+import type { ApprovalDecisionActor, ApprovalRequestManager } from "./manager.js";
+export declare function executeApprovalDecisionCommand(input: {
+    db: SqliteDatabase;
+    approvalManager?: ApprovalRequestManager;
+    commandId: IdempotencyKey;
+    approvalId: ApprovalRequestId;
+    decisionId: string;
+    actor: ApprovalDecisionActor;
+    now?: () => Date;
+}): import("../server-shell/command-idempotency/index.js").ExecuteIdempotentCommandResult<{
+    kind: "interrupted";
+    retry_with_new_command_id: true;
+} | {
+    kind: "accepted";
+} | {
+    kind: "stale_approval";
+} | {
+    kind: "decision_unavailable";
+}, {
+    approval?: {
+        state: "none";
+    } | {
+        request: {
+            task_id?: string;
+            activity_ref?: string;
+            expires_at?: string;
+            reason?: string;
+            file_change?: {
+                paths?: string[];
+                grant_root_label?: string;
+            };
+            permissions?: {
+                network?: {
+                    enabled: boolean;
+                };
+                filesystem?: {
+                    read?: string[];
+                    write?: string[];
+                };
+            };
+            command?: {
+                network?: {
+                    host: string;
+                    protocol: string;
+                };
+                cwd_label?: string;
+                actions?: {
+                    detail?: string;
+                    label: string;
+                }[];
+                text: string;
+            };
+            title: string;
+            summary: string;
+            decisions: {
+                kind: "allow_once" | "allow_session" | "deny" | "cancel";
+                label: string;
+                tone: "neutral" | "primary" | "danger";
+                decision_id: string;
+            }[];
+            approval_id: string;
+            request_kind: "command_execution" | "file_change" | "permissions" | "legacy_exec_command" | "legacy_apply_patch";
+            requested_at: string;
+        };
+        state: "pending";
+    } | {
+        request: {
+            task_id?: string;
+            activity_ref?: string;
+            expires_at?: string;
+            reason?: string;
+            file_change?: {
+                paths?: string[];
+                grant_root_label?: string;
+            };
+            permissions?: {
+                network?: {
+                    enabled: boolean;
+                };
+                filesystem?: {
+                    read?: string[];
+                    write?: string[];
+                };
+            };
+            command?: {
+                network?: {
+                    host: string;
+                    protocol: string;
+                };
+                cwd_label?: string;
+                actions?: {
+                    detail?: string;
+                    label: string;
+                }[];
+                text: string;
+            };
+            title: string;
+            summary: string;
+            decisions: {
+                kind: "allow_once" | "allow_session" | "deny" | "cancel";
+                label: string;
+                tone: "neutral" | "primary" | "danger";
+                decision_id: string;
+            }[];
+            approval_id: string;
+            request_kind: "command_execution" | "file_change" | "permissions" | "legacy_exec_command" | "legacy_apply_patch";
+            requested_at: string;
+        };
+        state: "resolved";
+        resolution: {
+            decided_by?: {
+                display_name: string;
+                account_ref: string;
+            };
+            label: string;
+            outcome: "accepted" | "declined" | "cancelled" | "expired";
+            decision_id: string;
+            decided_at: string;
+        };
+    };
+}>;
+//# sourceMappingURL=decision-command.d.ts.map

package/dist/approvals/decision-command.js

@@ -0,0 +1,20 @@
+import { executeIdempotentCommand } from "../server-shell/command-idempotency/index.js";
+export function executeApprovalDecisionCommand(input) {
+    return executeIdempotentCommand({
+        db: input.db,
+        command_id: input.commandId,
+        command_name: "approval.decide",
+        target_ref: input.approvalId,
+        payload: { decision_id: input.decisionId },
+        ...(input.now === undefined ? {} : { now: input.now }),
+        execute: () => input.approvalManager?.decide({
+            approvalId: input.approvalId,
+            payload: { decision_id: input.decisionId },
+            actor: input.actor,
+        }) ?? {
+            disposition: { kind: "stale_approval" },
+            result: { approval: { state: "none" } },
+        },
+    });
+}
+//# sourceMappingURL=decision-command.js.map

package/dist/approvals/index.d.ts

@@ -1,3 +1,4 @@
 export { ApprovalRequestManager, type ApprovalDecisionActor, type ApprovalRequestManagerOptions, type AwaitApprovalInput, type DecideApprovalInput, } from "./manager.js";
+export { executeApprovalDecisionCommand } from "./decision-command.js";
 export { buildApprovalProjection, type ApprovalAppServerResponse, type ApprovalDecisionRuntime, type ApprovalProjectionBuildResult, type ApprovalProjectionContext, } from "./projections.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/approvals/index.js

@@ -1,3 +1,4 @@
 export { ApprovalRequestManager, } from "./manager.js";
+export { executeApprovalDecisionCommand } from "./decision-command.js";
 export { buildApprovalProjection, } from "./projections.js";
 //# sourceMappingURL=index.js.map

package/dist/approvals/manager.d.ts

@@ -1,5 +1,5 @@
 import type { ApprovalRequestId, IdempotencyKey } from "@tutti/shared/ids";
-import type { ActiveApprovalProjection, DecideApprovalDisposition, DecideApprovalPayload, DecideApprovalResult } from "@tutti/shared/schemas/api";
+import type { ActiveApprovalProjection, ApprovalRequestProjection, DecideApprovalDisposition, DecideApprovalPayload, DecideApprovalResult } from "@tutti/shared/schemas/api";
 import type { CodexAppServerJsonRpcServerRequest } from "../providers/openai/app-server/json-rpc.js";
 import type { WorkspaceEventBus } from "../server-shell/http/workspace-events.js";
 import { type ApprovalProjectionContext, type ApprovalAppServerResponse } from "./projections.js";
@@ -11,6 +11,7 @@ export type ApprovalRequestManagerOptions = {
     events?: WorkspaceEventBus;
     now?: () => Date;
     resolvedTtlMs?: number;
+    onPending?: (request: ApprovalRequestProjection) => void;
 };
 export type AwaitApprovalInput = {
     request: CodexAppServerJsonRpcServerRequest;
@@ -27,6 +28,7 @@ export declare class ApprovalRequestManager {
     private readonly events;
     private readonly now;
     private readonly resolvedTtlMs;
+    private readonly onPending;
     private active;
     private resolved;
     private resolvedTimer;

package/dist/approvals/manager.js

@@ -23,6 +23,7 @@ export class ApprovalRequestManager {
     events;
     now;
     resolvedTtlMs;
+    onPending;
     active = null;
     resolved = null;
     resolvedTimer;
@@ -30,6 +31,7 @@ export class ApprovalRequestManager {
         this.events = options.events;
         this.now = options.now ?? (() => new Date());
         this.resolvedTtlMs = options.resolvedTtlMs ?? DEFAULT_RESOLVED_TTL_MS;
+        this.onPending = options.onPending;
     }
     getActiveApproval() {
         if (this.active !== null) {
@@ -88,6 +90,13 @@ export class ApprovalRequestManager {
                 resolve,
                 timer,
             };
+            try {
+                this.onPending?.(build.request);
+            }
+            catch {
+                // Approval correctness and the app-server response must not depend on outbound notice
+                // capture. The platform worker records bounded diagnostics after successful capture.
+            }
             this.publish(this.active.projection);
         });
     }

package/dist/collaboration-ingestion/index.d.ts

@@ -1,5 +1,8 @@
 export { ingestTrustedConversationSource, TRUSTED_INTEGRATION_INGESTION_PATH, type IngestTrustedConversationSourceOptions, } from "./external-source.js";
 export { ingestMainChatMessage, type IngestMainChatMessageOptions, type MainChatMessageMaterialization, } from "./main-chat.js";
+export { ingestManagedReferenceSnapshot, publishManagedReferenceSnapshotChanged, type IngestManagedReferenceSnapshotOptions, } from "./managed-reference-snapshots.js";
+export { ingestTrustedManagedReference, type IngestTrustedManagedReferenceOptions, type ResolvedManagedReferenceContent, } from "./managed-reference-sources.js";
 export { ingestReferenceFile, REFERENCE_FILE_INGESTION_COMMAND_NAME, REFERENCE_FILE_INGESTION_TARGET_REF, toReferenceFileProjection, type IngestReferenceFileOptions, } from "./reference-files.js";
+export { ingestTrustedReferenceAttachment, TRUSTED_INTEGRATION_REFERENCE_ATTACHMENT_PATH, type IngestTrustedReferenceAttachmentOptions, type ResolvedReferenceAttachmentContent, } from "./reference-attachments.js";
 export type { ChatAssistantEnqueuer, ReferenceSummaryStarter, ScratchpadSourceNotifier, TrustedCollaborationAuthor, } from "./types.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/collaboration-ingestion/index.js

@@ -1,4 +1,7 @@
 export { ingestTrustedConversationSource, TRUSTED_INTEGRATION_INGESTION_PATH, } from "./external-source.js";
 export { ingestMainChatMessage, } from "./main-chat.js";
+export { ingestManagedReferenceSnapshot, publishManagedReferenceSnapshotChanged, } from "./managed-reference-snapshots.js";
+export { ingestTrustedManagedReference, } from "./managed-reference-sources.js";
 export { ingestReferenceFile, REFERENCE_FILE_INGESTION_COMMAND_NAME, REFERENCE_FILE_INGESTION_TARGET_REF, toReferenceFileProjection, } from "./reference-files.js";
+export { ingestTrustedReferenceAttachment, TRUSTED_INTEGRATION_REFERENCE_ATTACHMENT_PATH, } from "./reference-attachments.js";
 //# sourceMappingURL=index.js.map

package/dist/collaboration-ingestion/managed-reference-snapshots.d.ts

@@ -0,0 +1,27 @@
+import type { WorkspaceEventBus } from "../server-shell/http/workspace-events.js";
+import { type WriteManagedReferenceSnapshotResult } from "../workspace-ops/index.js";
+import type { ReferenceSummaryStarter } from "./types.js";
+export type IngestManagedReferenceSnapshotOptions = {
+    workspaceRoot: string;
+    events: WorkspaceEventBus;
+    path: string;
+    content: Buffer;
+    expectedBlobOid?: string;
+    note?: string;
+    referenceSummaries?: ReferenceSummaryStarter;
+    now?: () => Date;
+};
+export declare function publishManagedReferenceSnapshotChanged(options: {
+    events: WorkspaceEventBus;
+    path: string;
+    referenceSummaries?: ReferenceSummaryStarter;
+}): void;
+/**
+ * Applies content that a trusted platform adapter has already normalized.
+ *
+ * External source identity, revision discovery, download credentials and
+ * retries stay in the adapter. This service owns only the Host-side snapshot
+ * write, Reference invalidation and summary request.
+ */
+export declare function ingestManagedReferenceSnapshot(options: IngestManagedReferenceSnapshotOptions): WriteManagedReferenceSnapshotResult;
+//# sourceMappingURL=managed-reference-snapshots.d.ts.map

package/dist/collaboration-ingestion/managed-reference-snapshots.js

@@ -0,0 +1,45 @@
+import { REFERENCE_DIRECTORY_PATH, writeManagedReferenceSnapshot, } from "../workspace-ops/index.js";
+export function publishManagedReferenceSnapshotChanged(options) {
+    options.events.publish({
+        event_type: "query.invalidate",
+        payload: {
+            reason: "viewer_changed",
+            message: "Reference snapshot changed.",
+        },
+        invalidates: [
+            { kind: "viewer", path: REFERENCE_DIRECTORY_PATH },
+            { kind: "execution_status" },
+            { kind: "workspace" },
+            { kind: "bootstrap" },
+        ],
+    });
+    options.referenceSummaries?.start([options.path]);
+}
+/**
+ * Applies content that a trusted platform adapter has already normalized.
+ *
+ * External source identity, revision discovery, download credentials and
+ * retries stay in the adapter. This service owns only the Host-side snapshot
+ * write, Reference invalidation and summary request.
+ */
+export function ingestManagedReferenceSnapshot(options) {
+    const result = writeManagedReferenceSnapshot({
+        workspaceRoot: options.workspaceRoot,
+        path: options.path,
+        content: options.content,
+        ...(options.expectedBlobOid === undefined ? {} : { expectedBlobOid: options.expectedBlobOid }),
+        ...(options.note === undefined ? {} : { note: options.note }),
+        ...(options.now === undefined ? {} : { now: options.now }),
+    });
+    if (result.disposition !== "unchanged") {
+        publishManagedReferenceSnapshotChanged({
+            events: options.events,
+            path: result.file.path,
+            ...(options.referenceSummaries === undefined
+                ? {}
+                : { referenceSummaries: options.referenceSummaries }),
+        });
+    }
+    return result;
+}
+//# sourceMappingURL=managed-reference-snapshots.js.map

package/dist/collaboration-ingestion/managed-reference-sources.d.ts

@@ -0,0 +1,20 @@
+import type { IntegrationManagedReferenceDisposition, TrustedManagedReferenceIngestionCommand } from "@tutti/shared/schemas/internal";
+import type { HostProjectStore } from "../store/index.js";
+import type { WorkspaceEventBus } from "../server-shell/http/workspace-events.js";
+import type { ReferenceSummaryStarter } from "./types.js";
+export type ResolvedManagedReferenceContent = {
+    content: Buffer;
+    complete: () => Promise<void>;
+    abort: () => Promise<void>;
+};
+export type IngestTrustedManagedReferenceOptions = {
+    store: HostProjectStore;
+    workspaceRoot: string;
+    events: WorkspaceEventBus;
+    command: TrustedManagedReferenceIngestionCommand;
+    resolveContent: () => Promise<ResolvedManagedReferenceContent>;
+    referenceSummaries?: ReferenceSummaryStarter;
+    now?: () => Date;
+};
+export declare function ingestTrustedManagedReference(options: IngestTrustedManagedReferenceOptions): Promise<IntegrationManagedReferenceDisposition>;
+//# sourceMappingURL=managed-reference-sources.d.ts.map

package/dist/collaboration-ingestion/managed-reference-sources.js

@@ -0,0 +1,250 @@
+import { createHash } from "node:crypto";
+import { isTrustedManagedReferenceIngestionCommand } from "@tutti/shared/schemas/internal";
+import { readManagedReferenceSnapshotState, WorkspaceOpsError, writeManagedReferenceSnapshot, } from "../workspace-ops/index.js";
+import { publishManagedReferenceSnapshotChanged } from "./managed-reference-snapshots.js";
+function readSource(db, sourceRef) {
+    return (db
+        .prepare("SELECT * FROM managed_reference_sources WHERE source_ref = ?")
+        .get(sourceRef) ?? null);
+}
+function sourceIdentityMatches(row, command) {
+    return (row.adapter_key === command.source.adapter_key &&
+        row.reference_path === command.source.reference_path);
+}
+function duplicateDisposition(row) {
+    if (row.last_outcome === null ||
+        row.accepted_blob_oid === null ||
+        row.accepted_revision_ref === null) {
+        return null;
+    }
+    return {
+        kind: "duplicate",
+        outcome: row.last_outcome,
+        current_blob_oid: row.accepted_blob_oid,
+    };
+}
+function completedOperationMatches(row, command) {
+    return (sourceIdentityMatches(row, command) &&
+        row.accepted_revision_ref === command.remote_revision_ref &&
+        row.accepted_content_sha256 === command.content.sha256 &&
+        row.last_expected_blob_oid === (command.expected_host_blob_oid ?? null));
+}
+function prepareSource(db, command, nowIso) {
+    const existing = readSource(db, command.source.source_ref);
+    if (existing !== null) {
+        if (!sourceIdentityMatches(existing, command)) {
+            return { kind: "conflict", reason_code: "managed_reference_source_conflict" };
+        }
+        if (existing.last_operation_ref === command.operation_ref) {
+            if (!completedOperationMatches(existing, command)) {
+                return { kind: "conflict", reason_code: "managed_reference_operation_conflict" };
+            }
+            return (duplicateDisposition(existing) ?? {
+                kind: "host_unavailable",
+                retryable: true,
+                reason_code: "managed_reference_recovery_pending",
+            });
+        }
+        if (existing.pending_operation_ref === command.operation_ref) {
+            if (existing.pending_revision_ref !== command.remote_revision_ref ||
+                existing.pending_content_sha256 !== command.content.sha256 ||
+                existing.pending_expected_blob_oid !== (command.expected_host_blob_oid ?? null)) {
+                return { kind: "conflict", reason_code: "managed_reference_operation_conflict" };
+            }
+            return { row: existing };
+        }
+        if (existing.accepted_blob_oid !== (command.expected_host_blob_oid ?? null)) {
+            return { kind: "conflict", reason_code: "managed_reference_checkpoint_stale" };
+        }
+    }
+    else if (command.expected_host_blob_oid !== undefined) {
+        return { kind: "conflict", reason_code: "managed_reference_source_missing" };
+    }
+    db.prepare(`
+      INSERT INTO managed_reference_sources (
+        source_ref, adapter_key, reference_path, pending_operation_ref,
+        pending_revision_ref, pending_content_sha256, pending_expected_blob_oid,
+        created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(source_ref) DO UPDATE SET
+        pending_operation_ref = excluded.pending_operation_ref,
+        pending_revision_ref = excluded.pending_revision_ref,
+        pending_content_sha256 = excluded.pending_content_sha256,
+        pending_expected_blob_oid = excluded.pending_expected_blob_oid,
+        updated_at = excluded.updated_at
+    `).run(command.source.source_ref, command.source.adapter_key, command.source.reference_path, command.operation_ref, command.remote_revision_ref, command.content.sha256, command.expected_host_blob_oid ?? null, nowIso, nowIso);
+    return {
+        row: readSource(db, command.source.source_ref),
+    };
+}
+function finalizeAccepted(options) {
+    options.db
+        .prepare(`
+        UPDATE managed_reference_sources
+        SET accepted_revision_ref = ?, accepted_blob_oid = ?, accepted_content_sha256 = ?,
+            last_operation_ref = ?, last_expected_blob_oid = ?, last_outcome = ?,
+            pending_operation_ref = NULL, pending_revision_ref = NULL,
+            pending_content_sha256 = NULL, pending_expected_blob_oid = NULL,
+            side_effects_pending = ?, last_checked_at = ?, last_accepted_at = ?, updated_at = ?
+        WHERE source_ref = ?
+      `)
+        .run(options.command.remote_revision_ref, options.blobOid, options.command.content.sha256, options.command.operation_ref, options.command.expected_host_blob_oid ?? null, options.outcome, options.sideEffectsPending ? 1 : 0, options.nowIso, options.nowIso, options.nowIso, options.command.source.source_ref);
+    return readSource(options.db, options.command.source.source_ref);
+}
+function clearSideEffectsPending(db, sourceRef, nowIso) {
+    db.prepare(`
+      UPDATE managed_reference_sources
+      SET side_effects_pending = 0, updated_at = ?
+      WHERE source_ref = ?
+    `).run(nowIso, sourceRef);
+}
+function sha256(content) {
+    return `sha256:${createHash("sha256").update(content).digest("hex")}`;
+}
+function accepted(outcome, blobOid) {
+    return { kind: outcome, current_blob_oid: blobOid };
+}
+export async function ingestTrustedManagedReference(options) {
+    const command = options.command;
+    if (!isTrustedManagedReferenceIngestionCommand(command)) {
+        return { kind: "invalid", reason_code: "trusted_managed_reference_command_invalid" };
+    }
+    const now = options.now ?? (() => new Date());
+    const nowIso = now().toISOString();
+    const existing = readSource(options.store.db, command.source.source_ref);
+    if (existing?.last_operation_ref === command.operation_ref &&
+        !completedOperationMatches(existing, command)) {
+        return { kind: "conflict", reason_code: "managed_reference_operation_conflict" };
+    }
+    if (existing?.last_operation_ref === command.operation_ref &&
+        existing.side_effects_pending === 1 &&
+        existing.accepted_blob_oid !== null) {
+        publishManagedReferenceSnapshotChanged({
+            events: options.events,
+            path: existing.reference_path,
+            ...(options.referenceSummaries === undefined
+                ? {}
+                : { referenceSummaries: options.referenceSummaries }),
+        });
+        clearSideEffectsPending(options.store.db, existing.source_ref, now().toISOString());
+        return duplicateDisposition(existing);
+    }
+    let current;
+    try {
+        current = readManagedReferenceSnapshotState({
+            workspaceRoot: options.workspaceRoot,
+            path: command.source.reference_path,
+            now,
+        });
+    }
+    catch (error) {
+        return error instanceof WorkspaceOpsError && error.code === "conflict"
+            ? { kind: "conflict", reason_code: "managed_reference_workspace_changed" }
+            : { kind: "invalid", reason_code: "managed_reference_snapshot_rejected" };
+    }
+    if (existing === null && current.exists) {
+        return { kind: "conflict", reason_code: "managed_reference_path_conflict" };
+    }
+    const prepared = prepareSource(options.store.db, command, nowIso);
+    if (!("row" in prepared)) {
+        return prepared;
+    }
+    if (prepared.row.accepted_blob_oid !== null &&
+        (!current.exists ||
+            (current.blob_oid !== prepared.row.accepted_blob_oid &&
+                current.content_sha256 !== command.content.sha256))) {
+        return { kind: "conflict", reason_code: "managed_reference_workspace_changed" };
+    }
+    if (current.exists && current.content_sha256 === command.content.sha256) {
+        const outcome = prepared.row.accepted_blob_oid === null
+            ? "created"
+            : prepared.row.accepted_content_sha256 === command.content.sha256
+                ? "unchanged"
+                : "updated";
+        finalizeAccepted({
+            db: options.store.db,
+            command,
+            blobOid: current.blob_oid,
+            outcome,
+            sideEffectsPending: outcome !== "unchanged",
+            nowIso,
+        });
+        if (outcome !== "unchanged") {
+            publishManagedReferenceSnapshotChanged({
+                events: options.events,
+                path: command.source.reference_path,
+                ...(options.referenceSummaries === undefined
+                    ? {}
+                    : { referenceSummaries: options.referenceSummaries }),
+            });
+            clearSideEffectsPending(options.store.db, command.source.source_ref, now().toISOString());
+        }
+        return accepted(outcome, current.blob_oid);
+    }
+    let staged;
+    try {
+        staged = await options.resolveContent();
+    }
+    catch {
+        return {
+            kind: "host_unavailable",
+            retryable: true,
+            reason_code: "managed_reference_stage_unavailable",
+        };
+    }
+    try {
+        if (staged.content.byteLength !== command.content.size_bytes ||
+            sha256(staged.content) !== command.content.sha256) {
+            await staged.abort();
+            return { kind: "invalid", reason_code: "managed_reference_content_mismatch" };
+        }
+        const result = writeManagedReferenceSnapshot({
+            workspaceRoot: options.workspaceRoot,
+            path: command.source.reference_path,
+            content: staged.content,
+            ...(prepared.row.accepted_blob_oid === null
+                ? {}
+                : { expectedBlobOid: prepared.row.accepted_blob_oid }),
+            note: "Managed Feishu Docx snapshot.",
+            now,
+        });
+        finalizeAccepted({
+            db: options.store.db,
+            command,
+            blobOid: result.file.blob_oid,
+            outcome: result.disposition,
+            sideEffectsPending: result.disposition !== "unchanged",
+            nowIso: now().toISOString(),
+        });
+        try {
+            await staged.complete();
+        }
+        catch {
+            // The accepted Host snapshot is authoritative; staging cleanup is best effort.
+        }
+        if (result.disposition !== "unchanged") {
+            publishManagedReferenceSnapshotChanged({
+                events: options.events,
+                path: result.file.path,
+                ...(options.referenceSummaries === undefined
+                    ? {}
+                    : { referenceSummaries: options.referenceSummaries }),
+            });
+            clearSideEffectsPending(options.store.db, command.source.source_ref, now().toISOString());
+        }
+        return accepted(result.disposition, result.file.blob_oid);
+    }
+    catch (error) {
+        try {
+            await staged.abort();
+        }
+        catch {
+            // Preserve the original stable disposition.
+        }
+        if (error instanceof WorkspaceOpsError && error.code === "conflict") {
+            return { kind: "conflict", reason_code: "managed_reference_workspace_changed" };
+        }
+        return { kind: "invalid", reason_code: "managed_reference_snapshot_rejected" };
+    }
+}
+//# sourceMappingURL=managed-reference-sources.js.map

package/dist/collaboration-ingestion/reference-attachments.d.ts

@@ -0,0 +1,22 @@
+import type { IntegrationDeliveryDisposition, TrustedReferenceAttachmentIngestionCommand } from "@tutti/shared/schemas/internal";
+import type { HostProjectStore } from "../store/index.js";
+import type { WorkspaceEventBus } from "../server-shell/http/workspace-events.js";
+import type { ReferenceSummaryStarter, ScratchpadSourceNotifier } from "./types.js";
+export declare const TRUSTED_INTEGRATION_REFERENCE_ATTACHMENT_PATH = "/internal/integration/v1/reference-attachments";
+export type ResolvedReferenceAttachmentContent = {
+    content: Buffer;
+    complete: () => Promise<void>;
+    abort: () => Promise<void>;
+};
+export type IngestTrustedReferenceAttachmentOptions = {
+    store: HostProjectStore;
+    workspaceRoot: string;
+    events: WorkspaceEventBus;
+    command: TrustedReferenceAttachmentIngestionCommand;
+    resolveContent: () => Promise<ResolvedReferenceAttachmentContent>;
+    scratchpadSource?: ScratchpadSourceNotifier;
+    referenceSummaries?: ReferenceSummaryStarter;
+    now?: () => Date;
+};
+export declare function ingestTrustedReferenceAttachment(options: IngestTrustedReferenceAttachmentOptions): Promise<IntegrationDeliveryDisposition>;
+//# sourceMappingURL=reference-attachments.d.ts.map