@claudian-collab/protocol 3.2.0 → 3.3.0

package/dist/esm/CollabCloudBinding.mjs

@@ -0,0 +1,559 @@
+import { COLLAB_LIMITS, COLLAB_PROTOCOL_VERSION } from './CollabConstants.mjs';
+import { COLLAB_CONTROL_OPERATION_CODECS, } from './CollabControlOperationCodecs.mjs';
+import { COLLAB_ERROR_CODES, CollabError, sanitizeCollabDiagnosticContext, } from './CollabError.mjs';
+import { isCollabOpaqueId, isCollabProjectId, } from './CollabValidation.mjs';
+import { COLLAB_CHECKPOINT_ARTIFACT_LIMITS, COLLAB_PROJECT_CHECKPOINT_ARTIFACTS, } from './CollabProjectCheckpoint.mjs';
+export const COLLAB_CLOUD_BINDING_VERSION = 2;
+export const COLLAB_CLOUD_CAPABILITY_DOCUMENT_SCHEMA_VERSION = 2;
+export const COLLAB_CLOUD_CAPABILITIES = Object.freeze([
+    'accept',
+    'authority-transfer',
+    'cloud-imported-membership-claims',
+    'cloud-project-create',
+    'cloud-project-invitations',
+    'cloud-project-join',
+    'cloud-project-leave',
+    'cloud-project-manager-responsibility',
+    'cloud-project-membership',
+    'development-bootstrap',
+    'git-receive-pack-personal-ref',
+    'git-upload-pack',
+    'project-checkpoint-export',
+    'project-events',
+    'project-retirement',
+    'project-snapshot',
+    'requests',
+    'tickets',
+]);
+export const COLLAB_CLOUD_JSON_OPERATIONS = Object.freeze([
+    'getProjectSnapshot',
+    ...Object.keys(COLLAB_CONTROL_OPERATION_CODECS),
+]);
+export const COLLAB_CLOUD_BINDING_LIMITS = Object.freeze({
+    bootstrapAttemptTtlMs: 24 * 60 * 60 * 1_000,
+    defaultMaxConcurrentBootstrapUploads: 1,
+    eventHeartbeatMs: 30_000,
+    eventMissedHeartbeatLimit: 2,
+    maxCloudOpenRequests: 100,
+    maxCloudProjectMembers: 100,
+    maxCloudSnapshotUtf8Bytes: 448 * 1024,
+    maxCloudTicketHighlights: 5,
+    maxCheckpointCoordinationBytes: COLLAB_CHECKPOINT_ARTIFACT_LIMITS.maxCoordinationBytes,
+    maxCheckpointManifestUtf8Bytes: COLLAB_CHECKPOINT_ARTIFACT_LIMITS.maxManifestBytes,
+    maxCheckpointRepositoryBundleBytes: COLLAB_CHECKPOINT_ARTIFACT_LIMITS.maxRepositoryBundleBytes,
+    maxCheckpointStagingBytes: COLLAB_CHECKPOINT_ARTIFACT_LIMITS.maxStagingBytes,
+    maxDevelopmentBootstrapGitBundleBytes: 1024 * 1024 * 1024,
+    maxDevelopmentBootstrapManifestUtf8Bytes: 64 * 1024,
+    maxDevelopmentBootstrapReportUtf8Bytes: 64 * 1024,
+    maxDevelopmentBootstrapRepositoryBytes: 1024 * 1024 * 1024,
+    maxDevelopmentBootstrapStagingBytes: 2 * 1024 * 1024 * 1024,
+    maxEventReplay: 500,
+    maxGitReceivePackBytes: 256 * 1024 * 1024,
+    maxRepositoryBytes: 1024 * 1024 * 1024,
+    minRetainedEventCount: 10_000,
+    maxUploadsPerBootstrapAttempt: 1,
+    minEventRetentionDays: 30,
+    uploadDeadlineMs: 15 * 60 * 1_000,
+    uploadIdleTimeoutMs: 30_000,
+});
+const CLOUD_CAPABILITY_SET = new Set(COLLAB_CLOUD_CAPABILITIES);
+const CLOUD_JSON_OPERATION_SET = new Set(COLLAB_CLOUD_JSON_OPERATIONS);
+const COLLAB_PROJECT_CHECKPOINT_ARTIFACTS_SET = new Set(COLLAB_PROJECT_CHECKPOINT_ARTIFACTS);
+const COLLAB_ERROR_CODE_SET = new Set(COLLAB_ERROR_CODES);
+const RECOVERY_ACTION_SET = new Set([
+    'retry',
+    'review-conflicts',
+    'request-access',
+]);
+const CAPABILITY_TOKEN_PATTERN = /^[a-z][a-z0-9-]{0,63}$/u;
+const SHA256_PATTERN = /^[0-9a-f]{64}$/u;
+function invalidPayload(field) {
+    return new CollabError({
+        code: 'protocol-payload-invalid',
+        safeContext: { field },
+    });
+}
+function invalidRoute() {
+    throw new RangeError('Invalid Collab Cloud route input');
+}
+function record(value, field) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        throw invalidPayload(field);
+    }
+    return value;
+}
+function hasExactKeys(value, keys) {
+    const expected = new Set(keys);
+    return keys.every(key => Object.hasOwn(value, key))
+        && Object.keys(value).every(key => expected.has(key));
+}
+function exactRecord(value, field, keys) {
+    const source = record(value, field);
+    if (!hasExactKeys(source, keys))
+        throw invalidPayload(field);
+    return source;
+}
+function positiveSafeInteger(value, field, maximum) {
+    if (typeof value !== 'number'
+        || !Number.isSafeInteger(value)
+        || value < 1
+        || (maximum !== undefined && value > maximum)) {
+        throw invalidPayload(field);
+    }
+    return value;
+}
+function sortedUniqueIntegers(value, field) {
+    if (!Array.isArray(value) || value.length === 0)
+        throw invalidPayload(field);
+    const decoded = value.map(item => positiveSafeInteger(item, field));
+    if (decoded.some((item, index) => index > 0 && decoded[index - 1] >= item)) {
+        throw invalidPayload(field);
+    }
+    return Object.freeze(decoded);
+}
+function sortedUniqueTokens(value, field) {
+    if (!Array.isArray(value))
+        throw invalidPayload(field);
+    const decoded = value.map((item) => {
+        if (typeof item !== 'string' || !CAPABILITY_TOKEN_PATTERN.test(item)) {
+            throw invalidPayload(field);
+        }
+        return item;
+    });
+    if (decoded.some((item, index) => index > 0 && decoded[index - 1].localeCompare(item, 'en-US') >= 0)) {
+        throw invalidPayload(field);
+    }
+    return Object.freeze(decoded);
+}
+function requireSupportedVersion(versions, supportedVersion, kind) {
+    if (versions.length === 1 && versions[0] === supportedVersion)
+        return;
+    throw new CollabError({
+        code: 'protocol-version-unsupported',
+        safeContext: {
+            kind,
+            receivedVersion: versions.find(version => version !== supportedVersion)
+                ?? versions[0]
+                ?? 0,
+            supportedVersion,
+        },
+    });
+}
+function route(method, target, match) {
+    return Object.freeze({ match: Object.freeze(match), method, target });
+}
+function assertProjectId(projectId) {
+    if (!isCollabProjectId(projectId))
+        invalidRoute();
+}
+function assertAttemptId(attemptId) {
+    if (!isCollabOpaqueId(attemptId))
+        invalidRoute();
+}
+function isCloudJsonOperation(value) {
+    return CLOUD_JSON_OPERATION_SET.has(value);
+}
+function isoTimestamp(value, field) {
+    if (typeof value !== 'string'
+        || value.length > 64
+        || Number.isNaN(Date.parse(value))
+        || new Date(value).toISOString() !== value)
+        throw invalidPayload(field);
+    return value;
+}
+export function collabCloudCapabilitiesRoute() {
+    return route('GET', '/collab/capabilities', { kind: 'capabilities' });
+}
+export function collabCloudProjectOperationRoute(projectId, operation) {
+    assertProjectId(projectId);
+    if (!isCloudJsonOperation(operation))
+        invalidRoute();
+    return route('POST', `/v2/projects/${projectId}/operations/${operation}`, {
+        kind: 'project-operation',
+        operation,
+        projectId,
+    });
+}
+export function collabCloudProjectEventsRoute(projectId, afterSequence) {
+    assertProjectId(projectId);
+    if (!Number.isSafeInteger(afterSequence) || afterSequence < 0)
+        invalidRoute();
+    return route('GET', `/v2/projects/${projectId}/events?afterSequence=${afterSequence}`, {
+        afterSequence,
+        kind: 'project-events',
+        projectId,
+    });
+}
+export function collabCloudGitRoute(projectId, routeKind, service) {
+    assertProjectId(projectId);
+    if (routeKind === 'info-refs') {
+        if (service !== 'git-upload-pack' && service !== 'git-receive-pack')
+            invalidRoute();
+        return route('GET', `/v2/projects/${projectId}/repository.git/info/refs?service=${service}`, { kind: 'git-info-refs', projectId, service });
+    }
+    if (service !== undefined)
+        invalidRoute();
+    return route('POST', `/v2/projects/${projectId}/repository.git/${routeKind}`, {
+        kind: routeKind,
+        projectId,
+    });
+}
+export function collabCloudAuthorityTransferArtifactRoute(projectId, transferId, direction, artifact) {
+    assertProjectId(projectId);
+    assertAttemptId(transferId);
+    if (direction !== 'download' && direction !== 'upload'
+        || !COLLAB_PROJECT_CHECKPOINT_ARTIFACTS_SET.has(artifact))
+        invalidRoute();
+    return route(direction === 'upload' ? 'PUT' : 'GET', `/v2/projects/${projectId}/authority-transfers/${transferId}/checkpoint/${artifact}`, {
+        artifact,
+        direction,
+        kind: 'authority-transfer-artifact',
+        projectId,
+        transferId,
+    });
+}
+export function collabCloudProjectCheckpointExportArtifactRoute(projectId, exportId, artifact) {
+    assertProjectId(projectId);
+    assertAttemptId(exportId);
+    if (!COLLAB_PROJECT_CHECKPOINT_ARTIFACTS_SET.has(artifact))
+        invalidRoute();
+    return route('GET', `/v2/projects/${projectId}/checkpoint-exports/${exportId}/checkpoint/${artifact}`, {
+        artifact,
+        exportId,
+        kind: 'project-checkpoint-export-artifact',
+        projectId,
+    });
+}
+export function collabCloudProjectCheckpointExportRoute(projectId, exportId, operation) {
+    assertProjectId(projectId);
+    assertAttemptId(exportId);
+    if (operation !== 'begin' && operation !== 'status')
+        invalidRoute();
+    return route(operation === 'begin' ? 'POST' : 'GET', `/v2/projects/${projectId}/checkpoint-exports/${exportId}`, { exportId, kind: 'project-checkpoint-export', operation, projectId });
+}
+export function decodeCollabCloudProjectCheckpointExportStatus(value) {
+    const source = exactRecord(value, 'checkpointExport', [
+        'checkpointSha256',
+        'createdAt',
+        'expiresAt',
+        'exportId',
+        'projectId',
+        'state',
+    ]);
+    if (!isCollabOpaqueId(source.exportId) || !isCollabProjectId(source.projectId)) {
+        throw invalidPayload('checkpointExport');
+    }
+    const state = source.state;
+    if (state !== 'preparing' && state !== 'ready')
+        throw invalidPayload('state');
+    if (source.checkpointSha256 !== null && typeof source.checkpointSha256 !== 'string') {
+        throw invalidPayload('checkpointSha256');
+    }
+    const checkpointSha256 = source.checkpointSha256;
+    if ((state === 'preparing' && checkpointSha256 !== null)
+        || (state === 'ready' && (typeof checkpointSha256 !== 'string' || !SHA256_PATTERN.test(checkpointSha256))))
+        throw invalidPayload('checkpointSha256');
+    const createdAt = isoTimestamp(source.createdAt, 'createdAt');
+    const expiresAt = isoTimestamp(source.expiresAt, 'expiresAt');
+    if (Date.parse(expiresAt) <= Date.parse(createdAt))
+        throw invalidPayload('expiresAt');
+    return Object.freeze({
+        checkpointSha256,
+        createdAt,
+        expiresAt,
+        exportId: source.exportId,
+        projectId: source.projectId,
+        state,
+    });
+}
+export function collabDevelopmentBootstrapRoute(operation, attemptId) {
+    const base = '/v2/development/bootstrap/attempts';
+    if (operation === 'beginDevelopmentBootstrap') {
+        if (attemptId !== undefined)
+            invalidRoute();
+        return route('POST', base, { kind: 'development-bootstrap', operation });
+    }
+    if (attemptId === undefined)
+        invalidRoute();
+    assertAttemptId(attemptId);
+    const suffixes = {
+        activateDevelopmentBootstrap: ['POST', 'activate'],
+        cancelDevelopmentBootstrap: ['POST', 'cancel'],
+        getDevelopmentBootstrap: ['GET', ''],
+        putDevelopmentBootstrapGitBundle: ['PUT', 'git-bundle'],
+        submitDevelopmentBootstrapReport: ['POST', 'reports'],
+    };
+    const binding = suffixes[operation];
+    if (!binding)
+        invalidRoute();
+    const [method, suffix] = binding;
+    const target = suffix ? `${base}/${attemptId}/${suffix}` : `${base}/${attemptId}`;
+    return route(method, target, {
+        attemptId,
+        kind: 'development-bootstrap',
+        operation,
+    });
+}
+function exactQuery(url, expectedKeys) {
+    const keys = [...url.searchParams.keys()];
+    return keys.length === expectedKeys.length
+        && expectedKeys.every(key => keys.filter(candidate => candidate === key).length === 1)
+        && keys.every(key => expectedKeys.includes(key))
+        && url.search === (expectedKeys.length === 0 ? '' : `?${url.searchParams.toString()}`);
+}
+function parseCanonicalNonNegativeInteger(value) {
+    if (value === null || !/^(?:0|[1-9][0-9]*)$/u.test(value))
+        return null;
+    const parsed = Number(value);
+    return Number.isSafeInteger(parsed) ? parsed : null;
+}
+export function matchCollabCloudRoute(method, target) {
+    if (!target.startsWith('/') || target.startsWith('//') || target.includes('#'))
+        return null;
+    let url;
+    try {
+        url = new URL(target, 'http://collab.invalid');
+    }
+    catch {
+        return null;
+    }
+    if (`${url.pathname}${url.search}` !== target)
+        return null;
+    const segments = url.pathname.split('/').filter(Boolean);
+    if (url.pathname !== `/${segments.join('/')}` || target.endsWith('?'))
+        return null;
+    if (method === 'GET'
+        && url.pathname === '/collab/capabilities'
+        && exactQuery(url, []))
+        return { kind: 'capabilities' };
+    if (segments[0] === 'v2'
+        && segments[1] === 'projects'
+        && isCollabProjectId(segments[2])) {
+        const projectId = segments[2];
+        if (method === 'GET'
+            && segments.length === 7
+            && segments[3] === 'checkpoint-exports'
+            && isCollabOpaqueId(segments[4])
+            && segments[5] === 'checkpoint'
+            && COLLAB_PROJECT_CHECKPOINT_ARTIFACTS_SET.has(segments[6])
+            && exactQuery(url, [])) {
+            return {
+                artifact: segments[6],
+                exportId: segments[4],
+                kind: 'project-checkpoint-export-artifact',
+                projectId,
+            };
+        }
+        if ((method === 'POST' || method === 'GET')
+            && segments.length === 5
+            && segments[3] === 'checkpoint-exports'
+            && isCollabOpaqueId(segments[4])
+            && exactQuery(url, [])) {
+            return {
+                exportId: segments[4],
+                kind: 'project-checkpoint-export',
+                operation: method === 'POST' ? 'begin' : 'status',
+                projectId,
+            };
+        }
+        if ((method === 'GET' || method === 'PUT')
+            && segments.length === 7
+            && segments[3] === 'authority-transfers'
+            && isCollabOpaqueId(segments[4])
+            && segments[5] === 'checkpoint'
+            && COLLAB_PROJECT_CHECKPOINT_ARTIFACTS_SET.has(segments[6])
+            && exactQuery(url, [])) {
+            return {
+                artifact: segments[6],
+                direction: method === 'PUT' ? 'upload' : 'download',
+                kind: 'authority-transfer-artifact',
+                projectId,
+                transferId: segments[4],
+            };
+        }
+        if (method === 'POST'
+            && segments.length === 5
+            && segments[3] === 'operations'
+            && isCloudJsonOperation(segments[4])
+            && exactQuery(url, [])) {
+            return { kind: 'project-operation', operation: segments[4], projectId };
+        }
+        if (method === 'GET'
+            && segments.length === 4
+            && segments[3] === 'events'
+            && exactQuery(url, ['afterSequence'])) {
+            const afterSequence = parseCanonicalNonNegativeInteger(url.searchParams.get('afterSequence'));
+            return afterSequence === null
+                ? null
+                : { afterSequence, kind: 'project-events', projectId };
+        }
+        if (method === 'GET'
+            && segments.length === 6
+            && segments[3] === 'repository.git'
+            && segments[4] === 'info'
+            && segments[5] === 'refs'
+            && exactQuery(url, ['service'])) {
+            const service = url.searchParams.get('service');
+            return service === 'git-upload-pack' || service === 'git-receive-pack'
+                ? { kind: 'git-info-refs', projectId, service }
+                : null;
+        }
+        if (method === 'POST'
+            && segments.length === 5
+            && segments[3] === 'repository.git'
+            && (segments[4] === 'git-upload-pack' || segments[4] === 'git-receive-pack')
+            && exactQuery(url, []))
+            return { kind: segments[4], projectId };
+    }
+    if (segments[0] !== 'v2'
+        || segments[1] !== 'development'
+        || segments[2] !== 'bootstrap'
+        || segments[3] !== 'attempts'
+        || !exactQuery(url, []))
+        return null;
+    if (method === 'POST' && segments.length === 4) {
+        return { kind: 'development-bootstrap', operation: 'beginDevelopmentBootstrap' };
+    }
+    const attemptId = segments[4];
+    if (!isCollabOpaqueId(attemptId))
+        return null;
+    if (method === 'GET' && segments.length === 5) {
+        return { attemptId, kind: 'development-bootstrap', operation: 'getDevelopmentBootstrap' };
+    }
+    const operation = (segments.length === 6
+        ? {
+            activate: method === 'POST' ? 'activateDevelopmentBootstrap' : null,
+            cancel: method === 'POST' ? 'cancelDevelopmentBootstrap' : null,
+            'git-bundle': method === 'PUT' ? 'putDevelopmentBootstrapGitBundle' : null,
+            reports: method === 'POST' ? 'submitDevelopmentBootstrapReport' : null,
+        }[segments[5]]
+        : null);
+    return operation
+        ? { attemptId, kind: 'development-bootstrap', operation }
+        : null;
+}
+export function decodeCollabCloudCapabilityDocument(value) {
+    const source = exactRecord(value, 'capabilities', [
+        'bindingVersions',
+        'capabilities',
+        'limits',
+        'protocolVersions',
+        'schemaVersion',
+    ]);
+    if (source.schemaVersion !== COLLAB_CLOUD_CAPABILITY_DOCUMENT_SCHEMA_VERSION) {
+        throw invalidPayload('schemaVersion');
+    }
+    const bindingVersions = sortedUniqueIntegers(source.bindingVersions, 'bindingVersions');
+    const protocolVersions = sortedUniqueIntegers(source.protocolVersions, 'protocolVersions');
+    requireSupportedVersion(bindingVersions, COLLAB_CLOUD_BINDING_VERSION, 'cloud-binding');
+    requireSupportedVersion(protocolVersions, COLLAB_PROTOCOL_VERSION, 'canonical-wire');
+    const capabilities = sortedUniqueTokens(source.capabilities, 'capabilities');
+    const limitsSource = exactRecord(source.limits, 'limits', [
+        'maxCheckpointCoordinationBytes',
+        'maxCheckpointManifestUtf8Bytes',
+        'maxCheckpointRepositoryBundleBytes',
+        'maxCheckpointStagingBytes',
+        'maxDevelopmentBootstrapGitBundleBytes',
+        'maxDevelopmentBootstrapManifestUtf8Bytes',
+        'maxDevelopmentBootstrapReportUtf8Bytes',
+        'maxEventReplay',
+        'maxGitReceivePackBytes',
+        'maxJsonPayloadUtf8Bytes',
+        'maxRepositoryBytes',
+    ]);
+    const limits = Object.freeze({
+        maxCheckpointCoordinationBytes: positiveSafeInteger(limitsSource.maxCheckpointCoordinationBytes, 'maxCheckpointCoordinationBytes', COLLAB_CLOUD_BINDING_LIMITS.maxCheckpointCoordinationBytes),
+        maxCheckpointManifestUtf8Bytes: positiveSafeInteger(limitsSource.maxCheckpointManifestUtf8Bytes, 'maxCheckpointManifestUtf8Bytes', COLLAB_CLOUD_BINDING_LIMITS.maxCheckpointManifestUtf8Bytes),
+        maxCheckpointRepositoryBundleBytes: positiveSafeInteger(limitsSource.maxCheckpointRepositoryBundleBytes, 'maxCheckpointRepositoryBundleBytes', COLLAB_CLOUD_BINDING_LIMITS.maxCheckpointRepositoryBundleBytes),
+        maxCheckpointStagingBytes: positiveSafeInteger(limitsSource.maxCheckpointStagingBytes, 'maxCheckpointStagingBytes', COLLAB_CLOUD_BINDING_LIMITS.maxCheckpointStagingBytes),
+        maxDevelopmentBootstrapGitBundleBytes: positiveSafeInteger(limitsSource.maxDevelopmentBootstrapGitBundleBytes, 'maxDevelopmentBootstrapGitBundleBytes', COLLAB_CLOUD_BINDING_LIMITS.maxDevelopmentBootstrapGitBundleBytes),
+        maxDevelopmentBootstrapManifestUtf8Bytes: positiveSafeInteger(limitsSource.maxDevelopmentBootstrapManifestUtf8Bytes, 'maxDevelopmentBootstrapManifestUtf8Bytes', COLLAB_CLOUD_BINDING_LIMITS.maxDevelopmentBootstrapManifestUtf8Bytes),
+        maxDevelopmentBootstrapReportUtf8Bytes: positiveSafeInteger(limitsSource.maxDevelopmentBootstrapReportUtf8Bytes, 'maxDevelopmentBootstrapReportUtf8Bytes', COLLAB_CLOUD_BINDING_LIMITS.maxDevelopmentBootstrapReportUtf8Bytes),
+        maxEventReplay: positiveSafeInteger(limitsSource.maxEventReplay, 'maxEventReplay', COLLAB_CLOUD_BINDING_LIMITS.maxEventReplay),
+        maxGitReceivePackBytes: positiveSafeInteger(limitsSource.maxGitReceivePackBytes, 'maxGitReceivePackBytes', COLLAB_CLOUD_BINDING_LIMITS.maxGitReceivePackBytes),
+        maxJsonPayloadUtf8Bytes: positiveSafeInteger(limitsSource.maxJsonPayloadUtf8Bytes, 'maxJsonPayloadUtf8Bytes', COLLAB_LIMITS.maxJsonPayloadUtf8Bytes),
+        maxRepositoryBytes: positiveSafeInteger(limitsSource.maxRepositoryBytes, 'maxRepositoryBytes', COLLAB_CLOUD_BINDING_LIMITS.maxRepositoryBytes),
+    });
+    return Object.freeze({
+        bindingVersions,
+        capabilities,
+        limits,
+        protocolVersions,
+        schemaVersion: COLLAB_CLOUD_CAPABILITY_DOCUMENT_SCHEMA_VERSION,
+    });
+}
+export function collabCloudCapabilityDocument(capabilities, limits) {
+    if (!capabilities.every(capability => CLOUD_CAPABILITY_SET.has(capability))) {
+        throw invalidPayload('capabilities');
+    }
+    return decodeCollabCloudCapabilityDocument({
+        bindingVersions: [COLLAB_CLOUD_BINDING_VERSION],
+        capabilities: [...capabilities].sort((left, right) => left.localeCompare(right, 'en-US')),
+        limits,
+        protocolVersions: [COLLAB_PROTOCOL_VERSION],
+        schemaVersion: COLLAB_CLOUD_CAPABILITY_DOCUMENT_SCHEMA_VERSION,
+    });
+}
+export function collabCloudCapabilitySupported(document, capability) {
+    return CLOUD_CAPABILITY_SET.has(capability) && document.capabilities.includes(capability);
+}
+export function collabCloudSuccessEnvelope(requestId, data) {
+    if (!isCollabOpaqueId(requestId))
+        throw invalidPayload('requestId');
+    return Object.freeze({ data, protocolVersion: COLLAB_PROTOCOL_VERSION, requestId });
+}
+export function decodeCollabCloudSuccessEnvelope(value) {
+    const source = exactRecord(value, 'envelope', ['data', 'protocolVersion', 'requestId']);
+    if (source.protocolVersion !== COLLAB_PROTOCOL_VERSION || !isCollabOpaqueId(source.requestId)) {
+        throw invalidPayload('envelope');
+    }
+    return Object.freeze({
+        data: source.data,
+        protocolVersion: COLLAB_PROTOCOL_VERSION,
+        requestId: source.requestId,
+    });
+}
+export function collabCloudErrorEnvelope(requestId, error) {
+    if (!isCollabOpaqueId(requestId))
+        throw invalidPayload('requestId');
+    return Object.freeze({
+        error: Object.freeze({
+            code: error.code,
+            recoveryActions: Object.freeze([...error.recoveryActions]),
+            safeContext: error.safeContext,
+        }),
+        protocolVersion: COLLAB_PROTOCOL_VERSION,
+        requestId,
+    });
+}
+export function decodeCollabCloudErrorEnvelope(value) {
+    const source = exactRecord(value, 'envelope', ['error', 'protocolVersion', 'requestId']);
+    const wireError = exactRecord(source.error, 'error', [
+        'code',
+        'recoveryActions',
+        'safeContext',
+    ]);
+    if (source.protocolVersion !== COLLAB_PROTOCOL_VERSION
+        || !isCollabOpaqueId(source.requestId)
+        || typeof wireError.code !== 'string'
+        || !COLLAB_ERROR_CODE_SET.has(wireError.code)
+        || !Array.isArray(wireError.recoveryActions)
+        || !wireError.recoveryActions.every(action => (typeof action === 'string' && RECOVERY_ACTION_SET.has(action))))
+        throw invalidPayload('error');
+    const safeContextSource = record(wireError.safeContext, 'safeContext');
+    const safeContext = sanitizeCollabDiagnosticContext(safeContextSource);
+    if (Object.keys(safeContextSource).length !== Object.keys(safeContext).length
+        || Object.entries(safeContextSource).some(([key, item]) => safeContext[key] !== item))
+        throw invalidPayload('safeContext');
+    return Object.freeze({
+        error: Object.freeze({
+            code: wireError.code,
+            recoveryActions: Object.freeze([
+                ...wireError.recoveryActions,
+            ]),
+            safeContext,
+        }),
+        protocolVersion: COLLAB_PROTOCOL_VERSION,
+        requestId: source.requestId,
+    });
+}