@xfey/tutti 0.1.105 → 0.1.107

package/dist/server-shell/http/host-tunnel.js

@@ -1,5 +1,5 @@
-import { isTrustedConversationSourceIngestionCommand } from "@tutti/shared/schemas/internal";
-import { TRUSTED_INTEGRATION_INGESTION_PATH } from "../../collaboration-ingestion/index.js";
+import { INTEGRATION_APPROVAL_DECISION_TUNNEL_PATH, INTEGRATION_MANAGED_REFERENCE_TUNNEL_PATH, INTEGRATION_REFERENCE_ATTACHMENT_TUNNEL_PATH, isTrustedApprovalDecisionCommand, isTrustedConversationSourceIngestionCommand, isTrustedManagedReferenceIngestionCommand, isTrustedReferenceAttachmentIngestionCommand, } from "@tutti/shared/schemas/internal";
+import { TRUSTED_INTEGRATION_INGESTION_PATH, TRUSTED_INTEGRATION_REFERENCE_ATTACHMENT_PATH, } from "../../collaboration-ingestion/index.js";
 import { TRUSTED_RELAY_METADATA_REQUEST_HEADER, } from "../session/relay-session-context.js";
 function browserMetadataMatchesSurface(projectSurface, request) {
     return projectSurface === "standalone"
@@ -38,6 +38,30 @@ function integrationResponse(requestId, disposition) {
         body_base64: Buffer.from(JSON.stringify(body), "utf8").toString("base64"),
     };
 }
+function integrationApprovalResponse(requestId, disposition) {
+    const body = {
+        protocol_version: 1,
+        disposition,
+    };
+    return {
+        request_id: requestId,
+        status_code: 200,
+        headers: { "content-type": "application/json; charset=utf-8" },
+        body_base64: Buffer.from(JSON.stringify(body), "utf8").toString("base64"),
+    };
+}
+function integrationManagedReferenceResponse(requestId, disposition) {
+    const body = {
+        protocol_version: 1,
+        disposition,
+    };
+    return {
+        request_id: requestId,
+        status_code: 200,
+        headers: { "content-type": "application/json; charset=utf-8" },
+        body_base64: Buffer.from(JSON.stringify(body), "utf8").toString("base64"),
+    };
+}
 function sameInstallation(left, right) {
     return left.platform === right.platform && left.installation_ref === right.installation_ref;
 }
@@ -51,6 +75,15 @@ function dispatchIntegrationDelivery(options, request) {
     if (!("integration_delivery" in request.metadata)) {
         throw new TypeError("Integration delivery metadata is required");
     }
+    if (request.path === INTEGRATION_APPROVAL_DECISION_TUNNEL_PATH) {
+        return dispatchIntegrationApprovalDecision(options, request);
+    }
+    if (request.path === INTEGRATION_REFERENCE_ATTACHMENT_TUNNEL_PATH) {
+        return dispatchIntegrationReferenceAttachment(options, request);
+    }
+    if (request.path === INTEGRATION_MANAGED_REFERENCE_TUNNEL_PATH) {
+        return dispatchIntegrationManagedReference(options, request);
+    }
     if (request.method.toUpperCase() !== "POST" ||
         request.path !== TRUSTED_INTEGRATION_INGESTION_PATH) {
         return Promise.resolve(integrationResponse(request.request_id, {
@@ -73,7 +106,8 @@ function dispatchIntegrationDelivery(options, request) {
         }));
     }
     const metadata = request.metadata.integration_delivery;
-    if (command.relay_project_ref !== metadata.relay_project_ref ||
+    if (!("receipt_key" in metadata) ||
+        command.relay_project_ref !== metadata.relay_project_ref ||
         command.binding_ref !== metadata.binding_ref ||
         command.receipt.receipt_key !== metadata.receipt_key ||
         command.actor.verified_at !== metadata.verified_at ||
@@ -92,6 +126,143 @@ function dispatchIntegrationDelivery(options, request) {
     }
     return Promise.resolve(integrationResponse(request.request_id, options.integrationDelivery(command)));
 }
+async function dispatchIntegrationReferenceAttachment(options, request) {
+    if (!("integration_delivery" in request.metadata)) {
+        throw new TypeError("Integration delivery metadata is required");
+    }
+    if (request.method.toUpperCase() !== "POST" ||
+        request.path !== TRUSTED_INTEGRATION_REFERENCE_ATTACHMENT_PATH) {
+        return integrationResponse(request.request_id, {
+            kind: "invalid",
+            reason_code: "internal_route_invalid",
+        });
+    }
+    const payload = decodeRequestBody(request.body_base64);
+    let command;
+    try {
+        command = payload === undefined ? undefined : JSON.parse(payload.toString("utf8"));
+    }
+    catch {
+        command = undefined;
+    }
+    if (!isTrustedReferenceAttachmentIngestionCommand(command)) {
+        return integrationResponse(request.request_id, {
+            kind: "invalid",
+            reason_code: "trusted_attachment_command_invalid",
+        });
+    }
+    const metadata = request.metadata.integration_delivery;
+    if (!("receipt_key" in metadata) ||
+        command.relay_project_ref !== metadata.relay_project_ref ||
+        command.binding_ref !== metadata.binding_ref ||
+        command.receipt.receipt_key !== metadata.receipt_key ||
+        command.actor.verified_at !== metadata.verified_at ||
+        !sameInstallation(command.receipt.installation, metadata.installation)) {
+        return integrationResponse(request.request_id, {
+            kind: "invalid",
+            reason_code: "trusted_metadata_mismatch",
+        });
+    }
+    if (options.integrationReferenceAttachment === undefined) {
+        return integrationResponse(request.request_id, {
+            kind: "host_incompatible",
+            retryable: true,
+            reason_code: "integration_attachment_ingestion_unsupported",
+        });
+    }
+    return integrationResponse(request.request_id, await options.integrationReferenceAttachment(command));
+}
+async function dispatchIntegrationManagedReference(options, request) {
+    if (!("integration_delivery" in request.metadata)) {
+        throw new TypeError("Integration delivery metadata is required");
+    }
+    if (request.method.toUpperCase() !== "POST" ||
+        request.path !== INTEGRATION_MANAGED_REFERENCE_TUNNEL_PATH) {
+        return integrationManagedReferenceResponse(request.request_id, {
+            kind: "invalid",
+            reason_code: "internal_route_invalid",
+        });
+    }
+    const payload = decodeRequestBody(request.body_base64);
+    let command;
+    try {
+        command = payload === undefined ? undefined : JSON.parse(payload.toString("utf8"));
+    }
+    catch {
+        command = undefined;
+    }
+    if (!isTrustedManagedReferenceIngestionCommand(command)) {
+        return integrationManagedReferenceResponse(request.request_id, {
+            kind: "invalid",
+            reason_code: "trusted_managed_reference_command_invalid",
+        });
+    }
+    const metadata = request.metadata.integration_delivery;
+    if (!("operation_ref" in metadata) ||
+        command.relay_project_ref !== metadata.relay_project_ref ||
+        command.binding_ref !== metadata.binding_ref ||
+        command.operation_ref !== metadata.operation_ref ||
+        command.actor.verified_at !== metadata.verified_at ||
+        !sameInstallation(command.source.installation, metadata.installation)) {
+        return integrationManagedReferenceResponse(request.request_id, {
+            kind: "invalid",
+            reason_code: "trusted_metadata_mismatch",
+        });
+    }
+    if (options.integrationManagedReference === undefined) {
+        return integrationManagedReferenceResponse(request.request_id, {
+            kind: "host_incompatible",
+            retryable: true,
+            reason_code: "integration_managed_reference_ingestion_unsupported",
+        });
+    }
+    return integrationManagedReferenceResponse(request.request_id, await options.integrationManagedReference(command));
+}
+function dispatchIntegrationApprovalDecision(options, request) {
+    if (!("integration_delivery" in request.metadata)) {
+        throw new TypeError("Integration delivery metadata is required");
+    }
+    if (request.method.toUpperCase() !== "POST") {
+        return Promise.resolve(integrationApprovalResponse(request.request_id, {
+            kind: "invalid",
+            reason_code: "internal_route_invalid",
+        }));
+    }
+    const payload = decodeRequestBody(request.body_base64);
+    let command;
+    try {
+        command = payload === undefined ? undefined : JSON.parse(payload.toString("utf8"));
+    }
+    catch {
+        command = undefined;
+    }
+    if (!isTrustedApprovalDecisionCommand(command)) {
+        return Promise.resolve(integrationApprovalResponse(request.request_id, {
+            kind: "invalid",
+            reason_code: "trusted_command_invalid",
+        }));
+    }
+    const metadata = request.metadata.integration_delivery;
+    if (!("receipt_key" in metadata) ||
+        command.relay_project_ref !== metadata.relay_project_ref ||
+        command.binding_ref !== metadata.binding_ref ||
+        command.receipt.receipt_key !== metadata.receipt_key ||
+        command.actor.verified_at !== metadata.verified_at ||
+        !sameInstallation(command.receipt.installation, metadata.installation)) {
+        return Promise.resolve(integrationApprovalResponse(request.request_id, {
+            kind: "invalid",
+            reason_code: "trusted_metadata_mismatch",
+        }));
+    }
+    if (options.integrationApprovalDecision === undefined) {
+        return Promise.resolve(integrationApprovalResponse(request.request_id, {
+            kind: "host_incompatible",
+            retryable: true,
+            reason_code: "integration_approval_decision_unsupported",
+        }));
+    }
+    return Promise.resolve(integrationApprovalResponse(request.request_id, options.integrationApprovalDecision(command)));
+}
 function injectHeaders(request) {
     const headers = {};
     for (const [name, value] of Object.entries(request.headers)) {

package/dist/server-shell/http/routes/project-api/approval-routes.js

@@ -1,9 +1,9 @@
 import { ActiveApprovalProjectionSchema, DecideApprovalBodySchema, DecideApprovalResponseSchema, } from "@tutti/shared/schemas/api";
-import { executeIdempotentCommand } from "../../../command-idempotency/index.js";
+import { executeApprovalDecisionCommand } from "../../../../approvals/index.js";
 import { HOST_PROJECT_API_BASE_PATH } from "./constants.js";
 import { approvalInvalidates } from "./invalidations.js";
-import { ApprovalRequestParamsSchema, } from "./schemas.js";
-import { requireHostProjectSession, requireProjectStore, } from "./session-requirements.js";
+import { ApprovalRequestParamsSchema } from "./schemas.js";
+import { requireHostProjectSession, requireProjectStore } from "./session-requirements.js";
 function readActiveApproval(options) {
     return options.approvalManager?.getActiveApproval() ?? { state: "none" };
 }
@@ -29,26 +29,19 @@ export function registerApprovalRoutes(app, options) {
     }, (request) => {
         const session = requireHostProjectSession(request, options);
         const store = requireProjectStore(options);
-        const execution = executeIdempotentCommand({
+        const execution = executeApprovalDecisionCommand({
             db: store.db,
-            command_id: request.body.command_id,
-            command_name: "approval.decide",
-            target_ref: request.params.approvalId,
-            payload: {
-                decision_id: request.body.payload.decision_id,
+            ...(options.approvalManager === undefined
+                ? {}
+                : { approvalManager: options.approvalManager }),
+            commandId: request.body.command_id,
+            approvalId: request.params.approvalId,
+            decisionId: request.body.payload.decision_id,
+            actor: {
+                account_ref: session.account.account_ref,
+                display_name: session.account.display_name,
             },
             ...(options.now === undefined ? {} : { now: options.now }),
-            execute: () => options.approvalManager?.decide({
-                approvalId: request.params.approvalId,
-                payload: request.body.payload,
-                actor: {
-                    account_ref: session.account.account_ref,
-                    display_name: session.account.display_name,
-                },
-            }) ?? {
-                disposition: { kind: "stale_approval" },
-                result: { approval: { state: "none" } },
-            },
         });
         const response = {
             command_id: execution.command_id,

package/dist/server-shell/http/routes/project-api/reference-files-routes.js

@@ -4,8 +4,9 @@ import { REFERENCE_DIRECTORY_PATH } from "../../../../workspace-ops/index.js";
 import { decideCommandIdempotencyReplay, executeIdempotentCommand, readCommandIdempotencyRecord, } from "../../../command-idempotency/index.js";
 import { HOST_PROJECT_API_BASE_PATH } from "./constants.js";
 import { readReferenceFilesResponse, referenceSummaryProcedureInvalidates, } from "./reference-files.js";
-import { requireControlPlane, requireHostProjectSession, requireProjectStore, requireWorkspaceRoot, } from "./session-requirements.js";
+import { requireControlPlane, requireHostProjectSession, requireHostProjectOwnerSession, requireProjectStore, requireWorkspaceRoot, } from "./session-requirements.js";
 import { abortDownloadedStagedUpload, cleanupDownloadedStagedUpload, downloadStagedUpload, } from "./staged-uploads.js";
+import { HostProjectBadRequestError } from "./errors.js";
 export function registerReferenceFilesRoutes(app, { options, workspaceEvents, }) {
     app.get(`${HOST_PROJECT_API_BASE_PATH}/references/files`, {
         schema: {
@@ -90,7 +91,16 @@ export function registerReferenceFilesRoutes(app, { options, workspaceEvents, })
             },
         },
     }, (request) => {
-        requireHostProjectSession(request, options);
+        if (options.surfaceProfile?.kind === "feishu") {
+            requireHostProjectOwnerSession(request, options);
+            const paths = request.body.payload.paths;
+            if (paths?.length !== 1 || !paths[0]?.startsWith(`${REFERENCE_DIRECTORY_PATH}/`)) {
+                throw new HostProjectBadRequestError("Select one project Reference to retry its summary");
+            }
+        }
+        else {
+            requireHostProjectSession(request, options);
+        }
         const store = requireProjectStore(options);
         const execution = executeIdempotentCommand({
             db: store.db,
@@ -109,6 +119,13 @@ export function registerReferenceFilesRoutes(app, { options, workspaceEvents, })
         if (execution.result !== undefined) {
             response.result = execution.result;
         }
+        request.log.info({
+            command_id: execution.command_id,
+            disposition: execution.disposition.kind,
+            activity_ref: execution.result?.activity_ref,
+            workflow_ref: execution.result?.workflow_ref,
+            target_count: execution.result?.target_count,
+        }, "Reference summary refresh requested");
         return response;
     });
 }

package/dist/server-shell/http/routes/project-api/staged-uploads.d.ts

@@ -4,6 +4,12 @@ export type DownloadedStagedUpload = {
     resolved: ResolvedStagedUpload;
     content: Buffer;
 };
+export type StagedUploadResolver = NonNullable<HostProjectApiRouteOptions["resolveStagedUpload"]>;
+export declare function downloadStagedUploadWithResolver(options: {
+    resolveStagedUpload: StagedUploadResolver;
+    expected: StagedUploadReference;
+    purpose: RelayUploadPurpose;
+}): Promise<DownloadedStagedUpload>;
 export declare function downloadStagedUpload(options: {
     routeOptions: HostProjectApiRouteOptions;
     expected: StagedUploadReference;

package/dist/server-shell/http/routes/project-api/staged-uploads.js

@@ -104,14 +104,14 @@ async function disposeResolvedStagedUpload(upload, status) {
         // Completion metadata is best-effort after the host has decided the terminal status.
     }
 }
-export async function downloadStagedUpload(options) {
+export async function downloadStagedUploadWithResolver(options) {
     const maxBytes = maxStagedUploadBytesForPurpose(options.purpose);
     if (options.expected.size_bytes > maxBytes) {
         throw new HostProjectValidationError(`Upload content cannot exceed ${maxBytes} bytes`);
     }
     let resolved;
     try {
-        resolved = await requireStagedUploadResolver(options.routeOptions)(options.expected.upload_id);
+        resolved = await options.resolveStagedUpload(options.expected.upload_id);
     }
     catch {
         throw new HostProjectValidationError("Upload session could not be resolved");
@@ -140,6 +140,13 @@ export async function downloadStagedUpload(options) {
         content,
     };
 }
+export async function downloadStagedUpload(options) {
+    return downloadStagedUploadWithResolver({
+        resolveStagedUpload: requireStagedUploadResolver(options.routeOptions),
+        expected: options.expected,
+        purpose: options.purpose,
+    });
+}
 export async function cleanupDownloadedStagedUpload(upload) {
     await disposeResolvedStagedUpload(upload.resolved, "completed");
 }

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[];
 };