@claudian-collab/protocol 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,105 @@
+# @claudian-collab/protocol
+
+The canonical shared Collab wire contract, produced from the
+[claudian-collab-protocol](https://github.com/YishenTu/claudian-collab-protocol) repository. Both Claudian
+(LAN client and Host) and Claudian Cloud Server consume this package; neither
+may maintain copied types, operation registries, codec maps, shared constants,
+or compatibility rules.
+
+## Contents
+
+- Opaque Collab ID types (`CollabProjectId`, `CollabMemberId`, `CollabGitOid`, …)
+- Transport-neutral request and response DTOs
+- Executable request/response codecs with decoder-defined compatibility behavior
+- The canonical operation registry (`CollabControlOperationMap`,
+  `COLLAB_CONTROL_OPERATION_CODECS`, `collabControlOperationCodec`)
+- Safe public error codes and sanitized error context (`CollabError`,
+  `COLLAB_ERROR_CODES`, `sanitizeCollabDiagnosticContext`)
+- Shared Git ref semantics (`COLLAB_MAIN_REF`, `COLLAB_MEMBER_REF_PREFIX`,
+  `collabMemberRef`)
+- Shared limits that client and server must agree on (`COLLAB_LIMITS`)
+- Protocol-version negotiation (`COLLAB_PROTOCOL_VERSION`, envelope decoding)
+- Cloud binding v1 route construction/matching, capability negotiation, strict success/error envelopes, private-development bootstrap, Project snapshot, and redacted event contracts
+- Markdown-derived Ticket-reference and Member-mention semantics shared by
+  client rendering and authority derivation
+
+The package owns the declarative Cloud HTTP/WebSocket/Git binding contract, but no transport runtime, request dispatch, trust policy, authentication, authorization, persistence, Git execution, or client-local recovery. It contains no LAN Host admission, invitation trust, mDNS/TLS/discovery, or Host-transfer transport; no Obsidian, Vault, UI, Agent, provider, SQL, or filesystem behavior; and no `IngressPrincipal` or other deployment-ingress contracts.
+
+The current registry contains only the decision-complete, transport-neutral
+request, Ticket, metadata, and Accept operations. Detail DTOs embed the first
+page of their comments and accepted relations; `listRequestComments`,
+`listTicketComments`, and `listTicketAcceptedRelations` page the remainder
+with stable opaque cursors, and producers bound pages by the shared count and
+UTF-8 byte limits. Producers size embedded first pages against the measured
+fixed part of the detail so the whole detail stays within
+`detailMaxUtf8Bytes`, including JSON escaping. JSON adapters accept the shared
+`maxJsonPayloadUtf8Bytes` cap so every valid bounded request, page, and detail
+has one compatible final-serialization limit. Request comments and Ticket
+accepted relations also have shared authority-enforced total limits; summary
+counts let complete consumers reject partial or cross-snapshot assembly.
+Cloud binding v1 adds the authority-neutral Project snapshot, six redacted durable event kinds plus `snapshot.required`, eight capability tokens, the exact ordinary Project/Git route catalog, and six private-development bootstrap bindings. Existing LAN v9 Join, invitation, endpoint, membership lifecycle, Host-transfer, retirement, snapshot, event, and HTTP bindings remain independently application-owned.
+
+## Usage
+
+```ts
+import {
+  COLLAB_PROTOCOL_VERSION,
+  COLLAB_CONTROL_OPERATION_CODECS,
+  CollabError,
+} from '@claudian-collab/protocol';
+
+const codec = COLLAB_CONTROL_OPERATION_CODECS.ensureMyRequest;
+const decoded = codec.decodeRequest(rawBody);
+if (decoded.status !== 'ok') {
+  // decoded.error is a safe CollabError: no credentials, paths, or internals.
+}
+```
+
+Only the package root (`.`) is a supported import. Subpath imports are not
+part of the public surface.
+
+## Versioning
+
+Package SemVer, canonical wire version, and Cloud binding version are independent concepts.
+
+- **Package version** (this `package.json`): `1.0.0`. Patch releases preserve
+  every existing public declaration and runtime behavior baseline. Minor
+  releases may add backward-compatible API. Removing or changing an existing
+  declaration, export, runtime behavior, codec, error, limit, ref rule,
+  operation, or compatibility rule requires a major release. The package
+  version never signals wire compatibility by itself.
+- **Wire version** (`COLLAB_PROTOCOL_VERSION`): currently `4`. The supported
+  range is exactly `[4, 4]`. This is independent from Cloud binding version `1` and the existing application
+  LAN control version `9`. Any change to an envelope, DTO, or operation
+  payload shape, or to the operation inventory, is wire-breaking and requires
+  a new wire-protocol version.
+- **Cloud binding version** (`COLLAB_CLOUD_BINDING_VERSION`): currently `1`. It versions Cloud routes and capabilities independently from package and wire versions.
+
+### Compatibility behavior
+
+- Envelope decoders reject unknown fields (`protocol-payload-invalid`).
+  Operation request and response compatibility is
+  decoder-defined and pinned by package fixtures; decoded DTOs are reconstructed
+  rather than retaining unrecognized input properties.
+- An unsupported `protocolVersion` decodes to `unsupported-version` with the
+  received and supported versions in safe context.
+- Unknown operation kinds have no codec and fail at registry lookup.
+- Unknown Cloud capability tokens are accepted and ignored by older consumers; unknown document fields, route operations, discriminants, schema versions, binding versions, and wire versions fail closed.
+- `CollabError.safeContext` is sanitized: credential-like keys are redacted
+  and filesystem paths are replaced with `[PATH]`.
+
+Compatibility is tested with executable fixtures in this package
+(`tests/`), and cross-repository contract fixtures pin client and server to
+the same behavior.
+
+## Development
+
+```bash
+npm run build        # compile src/ -> dist/ (CommonJS + declarations)
+npm test             # package unit tests
+npm run check:compatibility
+npm run verify:pack  # pack the artifact and smoke-test a clean consumer
+```
+
+`dist/` is generated output and is never committed. The packed artifact is
+reproducible from source: `npm pack` rebuilds via `prepack`.

package/dist/CollabCloudBinding.d.ts

@@ -0,0 +1,106 @@
+import { COLLAB_PROTOCOL_VERSION } from './CollabConstants';
+import { CollabError, type CollabDiagnosticContext, type CollabErrorCode, type CollabRecoveryAction } from './CollabError';
+export declare const COLLAB_CLOUD_BINDING_VERSION: 1;
+export declare const COLLAB_CLOUD_CAPABILITY_DOCUMENT_SCHEMA_VERSION: 1;
+export declare const COLLAB_CLOUD_CAPABILITIES: readonly ["accept", "development-bootstrap", "git-receive-pack-personal-ref", "git-upload-pack", "project-events", "project-snapshot", "requests", "tickets"];
+export type CollabCloudCapability = typeof COLLAB_CLOUD_CAPABILITIES[number];
+export declare const COLLAB_CLOUD_JSON_OPERATIONS: readonly ["getProjectSnapshot", ...(keyof import("./CollabProtocol").CollabControlOperationMap)[]];
+export type CollabCloudJsonOperation = typeof COLLAB_CLOUD_JSON_OPERATIONS[number];
+export declare const COLLAB_CLOUD_BINDING_LIMITS: Readonly<{
+    readonly bootstrapAttemptTtlMs: number;
+    readonly defaultMaxConcurrentBootstrapUploads: 1;
+    readonly eventHeartbeatMs: 30000;
+    readonly eventMissedHeartbeatLimit: 2;
+    readonly maxCloudOpenRequests: 100;
+    readonly maxCloudProjectMembers: 100;
+    readonly maxCloudSnapshotUtf8Bytes: number;
+    readonly maxCloudTicketHighlights: 5;
+    readonly maxDevelopmentBootstrapGitBundleBytes: number;
+    readonly maxDevelopmentBootstrapManifestUtf8Bytes: number;
+    readonly maxDevelopmentBootstrapReportUtf8Bytes: number;
+    readonly maxDevelopmentBootstrapRepositoryBytes: number;
+    readonly maxDevelopmentBootstrapStagingBytes: number;
+    readonly maxEventReplay: 500;
+    readonly maxGitReceivePackBytes: number;
+    readonly maxRepositoryBytes: number;
+    readonly minRetainedEventCount: 10000;
+    readonly maxUploadsPerBootstrapAttempt: 1;
+    readonly minEventRetentionDays: 30;
+    readonly uploadDeadlineMs: number;
+    readonly uploadIdleTimeoutMs: 30000;
+}>;
+export interface CollabCloudCapabilityLimits {
+    readonly maxDevelopmentBootstrapGitBundleBytes: number;
+    readonly maxDevelopmentBootstrapManifestUtf8Bytes: number;
+    readonly maxDevelopmentBootstrapReportUtf8Bytes: number;
+    readonly maxEventReplay: number;
+    readonly maxGitReceivePackBytes: number;
+    readonly maxJsonPayloadUtf8Bytes: number;
+    readonly maxRepositoryBytes: number;
+}
+export interface CollabCloudCapabilityDocument {
+    readonly bindingVersions: readonly number[];
+    readonly capabilities: readonly string[];
+    readonly limits: CollabCloudCapabilityLimits;
+    readonly protocolVersions: readonly number[];
+    readonly schemaVersion: typeof COLLAB_CLOUD_CAPABILITY_DOCUMENT_SCHEMA_VERSION;
+}
+export type DevelopmentBootstrapOperation = 'beginDevelopmentBootstrap' | 'submitDevelopmentBootstrapReport' | 'getDevelopmentBootstrap' | 'activateDevelopmentBootstrap' | 'cancelDevelopmentBootstrap' | 'putDevelopmentBootstrapGitBundle';
+export type CollabCloudGitService = 'git-upload-pack' | 'git-receive-pack';
+export type CollabCloudRouteMatch = {
+    readonly kind: 'capabilities';
+} | {
+    readonly kind: 'project-operation';
+    readonly operation: CollabCloudJsonOperation;
+    readonly projectId: string;
+} | {
+    readonly afterSequence: number;
+    readonly kind: 'project-events';
+    readonly projectId: string;
+} | {
+    readonly kind: 'git-info-refs';
+    readonly projectId: string;
+    readonly service: CollabCloudGitService;
+} | {
+    readonly kind: 'git-upload-pack' | 'git-receive-pack';
+    readonly projectId: string;
+} | {
+    readonly attemptId?: string;
+    readonly kind: 'development-bootstrap';
+    readonly operation: DevelopmentBootstrapOperation;
+};
+export interface CollabCloudRoute {
+    readonly match: CollabCloudRouteMatch;
+    readonly method: 'GET' | 'POST' | 'PUT';
+    readonly target: string;
+}
+export interface CollabCloudSuccessEnvelope<T> {
+    readonly data: T;
+    readonly protocolVersion: typeof COLLAB_PROTOCOL_VERSION;
+    readonly requestId: string;
+}
+export interface CollabCloudWireError {
+    readonly code: CollabErrorCode;
+    readonly recoveryActions: readonly CollabRecoveryAction[];
+    readonly safeContext: CollabDiagnosticContext;
+}
+export interface CollabCloudErrorEnvelope {
+    readonly error: CollabCloudWireError;
+    readonly protocolVersion: typeof COLLAB_PROTOCOL_VERSION;
+    readonly requestId: string;
+}
+export declare function collabCloudCapabilitiesRoute(): CollabCloudRoute;
+export declare function collabCloudProjectOperationRoute(projectId: string, operation: CollabCloudJsonOperation): CollabCloudRoute;
+export declare function collabCloudProjectEventsRoute(projectId: string, afterSequence: number): CollabCloudRoute;
+export declare function collabCloudGitRoute(projectId: string, routeKind: 'info-refs', service: CollabCloudGitService): CollabCloudRoute;
+export declare function collabCloudGitRoute(projectId: string, routeKind: CollabCloudGitService): CollabCloudRoute;
+export declare function collabDevelopmentBootstrapRoute(operation: 'beginDevelopmentBootstrap'): CollabCloudRoute;
+export declare function collabDevelopmentBootstrapRoute(operation: Exclude<DevelopmentBootstrapOperation, 'beginDevelopmentBootstrap'>, attemptId: string): CollabCloudRoute;
+export declare function matchCollabCloudRoute(method: string, target: string): CollabCloudRouteMatch | null;
+export declare function decodeCollabCloudCapabilityDocument(value: unknown): CollabCloudCapabilityDocument;
+export declare function collabCloudCapabilityDocument(capabilities: readonly CollabCloudCapability[], limits: CollabCloudCapabilityLimits): CollabCloudCapabilityDocument;
+export declare function collabCloudCapabilitySupported(document: CollabCloudCapabilityDocument, capability: CollabCloudCapability): boolean;
+export declare function collabCloudSuccessEnvelope<T>(requestId: string, data: T): CollabCloudSuccessEnvelope<T>;
+export declare function decodeCollabCloudSuccessEnvelope<T = unknown>(value: unknown): CollabCloudSuccessEnvelope<T>;
+export declare function collabCloudErrorEnvelope(requestId: string, error: CollabError): CollabCloudErrorEnvelope;
+export declare function decodeCollabCloudErrorEnvelope(value: unknown): CollabCloudErrorEnvelope;

package/dist/CollabCloudBinding.js

@@ -0,0 +1,431 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.COLLAB_CLOUD_BINDING_LIMITS = exports.COLLAB_CLOUD_JSON_OPERATIONS = exports.COLLAB_CLOUD_CAPABILITIES = exports.COLLAB_CLOUD_CAPABILITY_DOCUMENT_SCHEMA_VERSION = exports.COLLAB_CLOUD_BINDING_VERSION = void 0;
+exports.collabCloudCapabilitiesRoute = collabCloudCapabilitiesRoute;
+exports.collabCloudProjectOperationRoute = collabCloudProjectOperationRoute;
+exports.collabCloudProjectEventsRoute = collabCloudProjectEventsRoute;
+exports.collabCloudGitRoute = collabCloudGitRoute;
+exports.collabDevelopmentBootstrapRoute = collabDevelopmentBootstrapRoute;
+exports.matchCollabCloudRoute = matchCollabCloudRoute;
+exports.decodeCollabCloudCapabilityDocument = decodeCollabCloudCapabilityDocument;
+exports.collabCloudCapabilityDocument = collabCloudCapabilityDocument;
+exports.collabCloudCapabilitySupported = collabCloudCapabilitySupported;
+exports.collabCloudSuccessEnvelope = collabCloudSuccessEnvelope;
+exports.decodeCollabCloudSuccessEnvelope = decodeCollabCloudSuccessEnvelope;
+exports.collabCloudErrorEnvelope = collabCloudErrorEnvelope;
+exports.decodeCollabCloudErrorEnvelope = decodeCollabCloudErrorEnvelope;
+const CollabConstants_1 = require("./CollabConstants");
+const CollabControlOperationCodecs_1 = require("./CollabControlOperationCodecs");
+const CollabError_1 = require("./CollabError");
+const CollabValidation_1 = require("./CollabValidation");
+exports.COLLAB_CLOUD_BINDING_VERSION = 1;
+exports.COLLAB_CLOUD_CAPABILITY_DOCUMENT_SCHEMA_VERSION = 1;
+exports.COLLAB_CLOUD_CAPABILITIES = Object.freeze([
+    'accept',
+    'development-bootstrap',
+    'git-receive-pack-personal-ref',
+    'git-upload-pack',
+    'project-events',
+    'project-snapshot',
+    'requests',
+    'tickets',
+]);
+exports.COLLAB_CLOUD_JSON_OPERATIONS = Object.freeze([
+    'getProjectSnapshot',
+    ...Object.keys(CollabControlOperationCodecs_1.COLLAB_CONTROL_OPERATION_CODECS),
+]);
+exports.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,
+    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(exports.COLLAB_CLOUD_CAPABILITIES);
+const CLOUD_JSON_OPERATION_SET = new Set(exports.COLLAB_CLOUD_JSON_OPERATIONS);
+const COLLAB_ERROR_CODE_SET = new Set(CollabError_1.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;
+function invalidPayload(field) {
+    return new CollabError_1.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_1.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 (!(0, CollabValidation_1.isCollabProjectId)(projectId))
+        invalidRoute();
+}
+function assertAttemptId(attemptId) {
+    if (!(0, CollabValidation_1.isCollabOpaqueId)(attemptId))
+        invalidRoute();
+}
+function isCloudJsonOperation(value) {
+    return CLOUD_JSON_OPERATION_SET.has(value);
+}
+function collabCloudCapabilitiesRoute() {
+    return route('GET', '/collab/capabilities', { kind: 'capabilities' });
+}
+function collabCloudProjectOperationRoute(projectId, operation) {
+    assertProjectId(projectId);
+    if (!isCloudJsonOperation(operation))
+        invalidRoute();
+    return route('POST', `/v1/projects/${projectId}/operations/${operation}`, {
+        kind: 'project-operation',
+        operation,
+        projectId,
+    });
+}
+function collabCloudProjectEventsRoute(projectId, afterSequence) {
+    assertProjectId(projectId);
+    if (!Number.isSafeInteger(afterSequence) || afterSequence < 0)
+        invalidRoute();
+    return route('GET', `/v1/projects/${projectId}/events?afterSequence=${afterSequence}`, {
+        afterSequence,
+        kind: 'project-events',
+        projectId,
+    });
+}
+function collabCloudGitRoute(projectId, routeKind, service) {
+    assertProjectId(projectId);
+    if (routeKind === 'info-refs') {
+        if (service !== 'git-upload-pack' && service !== 'git-receive-pack')
+            invalidRoute();
+        return route('GET', `/v1/projects/${projectId}/repository.git/info/refs?service=${service}`, { kind: 'git-info-refs', projectId, service });
+    }
+    if (service !== undefined)
+        invalidRoute();
+    return route('POST', `/v1/projects/${projectId}/repository.git/${routeKind}`, {
+        kind: routeKind,
+        projectId,
+    });
+}
+function collabDevelopmentBootstrapRoute(operation, attemptId) {
+    const base = '/v1/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;
+}
+function matchCollabCloudRoute(method, target) {
+    if (!target.startsWith('/') || target.includes('#'))
+        return null;
+    let url;
+    try {
+        url = new URL(target, 'http://collab.invalid');
+    }
+    catch {
+        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] === 'v1'
+        && segments[1] === 'projects'
+        && (0, CollabValidation_1.isCollabProjectId)(segments[2])) {
+        const projectId = segments[2];
+        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] !== 'v1'
+        || 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 (!(0, CollabValidation_1.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;
+}
+function decodeCollabCloudCapabilityDocument(value) {
+    const source = exactRecord(value, 'capabilities', [
+        'bindingVersions',
+        'capabilities',
+        'limits',
+        'protocolVersions',
+        'schemaVersion',
+    ]);
+    if (source.schemaVersion !== exports.COLLAB_CLOUD_CAPABILITY_DOCUMENT_SCHEMA_VERSION) {
+        throw invalidPayload('schemaVersion');
+    }
+    const bindingVersions = sortedUniqueIntegers(source.bindingVersions, 'bindingVersions');
+    const protocolVersions = sortedUniqueIntegers(source.protocolVersions, 'protocolVersions');
+    requireSupportedVersion(bindingVersions, exports.COLLAB_CLOUD_BINDING_VERSION, 'cloud-binding');
+    requireSupportedVersion(protocolVersions, CollabConstants_1.COLLAB_PROTOCOL_VERSION, 'canonical-wire');
+    const capabilities = sortedUniqueTokens(source.capabilities, 'capabilities');
+    const limitsSource = exactRecord(source.limits, 'limits', [
+        'maxDevelopmentBootstrapGitBundleBytes',
+        'maxDevelopmentBootstrapManifestUtf8Bytes',
+        'maxDevelopmentBootstrapReportUtf8Bytes',
+        'maxEventReplay',
+        'maxGitReceivePackBytes',
+        'maxJsonPayloadUtf8Bytes',
+        'maxRepositoryBytes',
+    ]);
+    const limits = Object.freeze({
+        maxDevelopmentBootstrapGitBundleBytes: positiveSafeInteger(limitsSource.maxDevelopmentBootstrapGitBundleBytes, 'maxDevelopmentBootstrapGitBundleBytes', exports.COLLAB_CLOUD_BINDING_LIMITS.maxDevelopmentBootstrapGitBundleBytes),
+        maxDevelopmentBootstrapManifestUtf8Bytes: positiveSafeInteger(limitsSource.maxDevelopmentBootstrapManifestUtf8Bytes, 'maxDevelopmentBootstrapManifestUtf8Bytes', exports.COLLAB_CLOUD_BINDING_LIMITS.maxDevelopmentBootstrapManifestUtf8Bytes),
+        maxDevelopmentBootstrapReportUtf8Bytes: positiveSafeInteger(limitsSource.maxDevelopmentBootstrapReportUtf8Bytes, 'maxDevelopmentBootstrapReportUtf8Bytes', exports.COLLAB_CLOUD_BINDING_LIMITS.maxDevelopmentBootstrapReportUtf8Bytes),
+        maxEventReplay: positiveSafeInteger(limitsSource.maxEventReplay, 'maxEventReplay', exports.COLLAB_CLOUD_BINDING_LIMITS.maxEventReplay),
+        maxGitReceivePackBytes: positiveSafeInteger(limitsSource.maxGitReceivePackBytes, 'maxGitReceivePackBytes', exports.COLLAB_CLOUD_BINDING_LIMITS.maxGitReceivePackBytes),
+        maxJsonPayloadUtf8Bytes: positiveSafeInteger(limitsSource.maxJsonPayloadUtf8Bytes, 'maxJsonPayloadUtf8Bytes', CollabConstants_1.COLLAB_LIMITS.maxJsonPayloadUtf8Bytes),
+        maxRepositoryBytes: positiveSafeInteger(limitsSource.maxRepositoryBytes, 'maxRepositoryBytes', exports.COLLAB_CLOUD_BINDING_LIMITS.maxRepositoryBytes),
+    });
+    return Object.freeze({
+        bindingVersions,
+        capabilities,
+        limits,
+        protocolVersions,
+        schemaVersion: exports.COLLAB_CLOUD_CAPABILITY_DOCUMENT_SCHEMA_VERSION,
+    });
+}
+function collabCloudCapabilityDocument(capabilities, limits) {
+    if (!capabilities.every(capability => CLOUD_CAPABILITY_SET.has(capability))) {
+        throw invalidPayload('capabilities');
+    }
+    return decodeCollabCloudCapabilityDocument({
+        bindingVersions: [exports.COLLAB_CLOUD_BINDING_VERSION],
+        capabilities: [...capabilities].sort((left, right) => left.localeCompare(right, 'en-US')),
+        limits,
+        protocolVersions: [CollabConstants_1.COLLAB_PROTOCOL_VERSION],
+        schemaVersion: exports.COLLAB_CLOUD_CAPABILITY_DOCUMENT_SCHEMA_VERSION,
+    });
+}
+function collabCloudCapabilitySupported(document, capability) {
+    return CLOUD_CAPABILITY_SET.has(capability) && document.capabilities.includes(capability);
+}
+function collabCloudSuccessEnvelope(requestId, data) {
+    if (!(0, CollabValidation_1.isCollabOpaqueId)(requestId))
+        throw invalidPayload('requestId');
+    return Object.freeze({ data, protocolVersion: CollabConstants_1.COLLAB_PROTOCOL_VERSION, requestId });
+}
+function decodeCollabCloudSuccessEnvelope(value) {
+    const source = exactRecord(value, 'envelope', ['data', 'protocolVersion', 'requestId']);
+    if (source.protocolVersion !== CollabConstants_1.COLLAB_PROTOCOL_VERSION || !(0, CollabValidation_1.isCollabOpaqueId)(source.requestId)) {
+        throw invalidPayload('envelope');
+    }
+    return Object.freeze({
+        data: source.data,
+        protocolVersion: CollabConstants_1.COLLAB_PROTOCOL_VERSION,
+        requestId: source.requestId,
+    });
+}
+function collabCloudErrorEnvelope(requestId, error) {
+    if (!(0, CollabValidation_1.isCollabOpaqueId)(requestId))
+        throw invalidPayload('requestId');
+    return Object.freeze({
+        error: Object.freeze({
+            code: error.code,
+            recoveryActions: Object.freeze([...error.recoveryActions]),
+            safeContext: error.safeContext,
+        }),
+        protocolVersion: CollabConstants_1.COLLAB_PROTOCOL_VERSION,
+        requestId,
+    });
+}
+function decodeCollabCloudErrorEnvelope(value) {
+    const source = exactRecord(value, 'envelope', ['error', 'protocolVersion', 'requestId']);
+    const wireError = exactRecord(source.error, 'error', [
+        'code',
+        'recoveryActions',
+        'safeContext',
+    ]);
+    if (source.protocolVersion !== CollabConstants_1.COLLAB_PROTOCOL_VERSION
+        || !(0, CollabValidation_1.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 = (0, CollabError_1.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: CollabConstants_1.COLLAB_PROTOCOL_VERSION,
+        requestId: source.requestId,
+    });
+}