@claudian-collab/protocol 1.0.0 → 3.0.0

package/README.md

@@ -19,14 +19,14 @@ or compatibility rules.
   `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
+- Canonical Project checkpoint profiles, logical records, authority-generation transfer, exact membership claims, target-signed redemption receipts, and Project retirement contracts
+- Cloud binding v2 route construction/matching, bounded checkpoint streams, 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
+The current registry contains the decision-complete, transport-neutral request, Ticket, metadata, Accept, Project authority-transfer, transferred-membership claim, and Project retirement 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
@@ -37,7 +37,7 @@ fixed part of the detail so the whole detail stays within
 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.
+Cloud binding v2 adds the authority-neutral Project snapshot, nine redacted durable event kinds plus `snapshot.required`, eleven capability tokens, the exact ordinary Project/Git route catalog, bounded authority-transfer artifact routes, and six private-development bootstrap bindings. The shared checkpoint container is exactly `checkpoint.json`, `coordination.ndjson`, and `repository.bundle`; portable profiles exclude engine storage, paths, credentials, tokens, private keys, and operational refs, while the backup profile may carry only protected claim-envelope metadata and ciphertext. Domain-separated canonical UTF-8 inputs define protected-claim AEAD associated data and bind every declared field of transferred-membership redemption receipts and authority-relinquishment proofs before consumer-owned Ed25519 signing or verification. Existing LAN v9 Join, invitation, endpoint, membership lifecycle, Host-transfer, snapshot, event, and HTTP bindings remain independently application-owned; the dedicated LAN authority-transfer transport binds these shared payloads without creating another shared operation registry.
 
 ## Usage
 
@@ -62,18 +62,17 @@ part of the public surface.
 
 Package SemVer, canonical wire version, and Cloud binding version are independent concepts.
 
-- **Package version** (this `package.json`): `1.0.0`. Patch releases preserve
+- **Package version** (this `package.json`): `3.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
+  operation, or compatibility rule requires a major release. Package 3 and wire 6 add an exact empty transfer-claim batch for a Project whose only Member is the already-bound Host. The package version never signals wire compatibility by itself.
+- **Wire version** (`COLLAB_PROTOCOL_VERSION`): currently `6`. The supported
+  range is exactly `[6, 6]`. This is independent from Cloud binding version `2` 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.
+- **Cloud binding version** (`COLLAB_CLOUD_BINDING_VERSION`): currently `2`. It versions Cloud routes, bounded transfer streams, and capabilities independently from package and wire versions. Binding v1 and wire versions before v6 are unsupported rather than translated or dual-interpreted.
 
 ### Compatibility behavior
 

package/dist/CollabAuthorityTransfer.d.ts

@@ -0,0 +1,296 @@
+import type { CollabCheckpointAuthority, CollabCheckpointAuthorityKind } from './CollabProjectCheckpoint';
+import type { CollabIsoTimestamp, CollabMemberId, CollabProjectId } from './types';
+export declare const COLLAB_LAN_TO_CLOUD_TRANSFER_PHASES: readonly ["collecting-readiness", "source-quiesced", "checkpoint-received", "checkpoint-validated", "claims-retained", "repository-published", "source-relinquished", "cloud-activated", "completed"];
+export declare const COLLAB_CLOUD_TO_LAN_TRANSFER_PHASES: readonly ["collecting-readiness", "cloud-quiesced", "checkpoint-captured", "target-staged", "claims-retained", "cloud-relinquished", "lan-activated", "completed"];
+export declare const COLLAB_AUTHORITY_TRANSFER_CANCELLATION_PHASES: readonly ["cancel-intent", "target-invalidated", "target-cleaned", "source-reopened", "cancelled"];
+export declare const COLLAB_AUTHORITY_TRANSFER_CANCELLABLE_PHASES: readonly ["collecting-readiness", "source-quiesced", "checkpoint-received", "checkpoint-validated", "claims-retained", "repository-published", "cloud-quiesced", "checkpoint-captured", "target-staged", "cancel-intent", "target-invalidated", "target-cleaned", "source-reopened"];
+export type CollabLanToCloudTransferPhase = typeof COLLAB_LAN_TO_CLOUD_TRANSFER_PHASES[number];
+export type CollabCloudToLanTransferPhase = typeof COLLAB_CLOUD_TO_LAN_TRANSFER_PHASES[number];
+export type CollabAuthorityTransferCancellationPhase = typeof COLLAB_AUTHORITY_TRANSFER_CANCELLATION_PHASES[number];
+export type CollabAuthorityTransferCancellablePhase = typeof COLLAB_AUTHORITY_TRANSFER_CANCELLABLE_PHASES[number];
+export type CollabAuthorityTransferDirection = 'cloud-to-lan' | 'lan-to-cloud';
+export interface CollabAuthorityTransferProposal {
+    readonly expectedSourceAuthority: CollabCheckpointAuthority;
+    readonly idempotencyKey: string;
+    readonly projectId: CollabProjectId;
+    readonly proposedByMemberId: CollabMemberId;
+    readonly proposedAt: CollabIsoTimestamp;
+    readonly targetAuthorityKind: CollabCheckpointAuthorityKind;
+    readonly targetUrl: string;
+}
+export interface CollabTransferredMembershipClaimItem {
+    readonly claim: string;
+    readonly memberId: CollabMemberId;
+}
+export interface CollabTransferredMembershipClaimBatch {
+    readonly batchRevision: number;
+    readonly batchSha256: string;
+    readonly checkpointSha256: string;
+    readonly claims: readonly CollabTransferredMembershipClaimItem[];
+    readonly expiresAt: CollabIsoTimestamp;
+    readonly projectId: CollabProjectId;
+    readonly targetAuthorityGeneration: number;
+    readonly transferId: string;
+}
+export interface CollabTransferredMembershipClaimCustodyReceipt {
+    readonly batchRevision: number;
+    readonly batchSha256: string;
+    readonly checkpointSha256: string;
+    readonly committedAt: CollabIsoTimestamp;
+    readonly custodyAuthority: CollabCheckpointAuthority;
+    readonly operationIntentId: string;
+    readonly projectId: CollabProjectId;
+    readonly receiptId: string;
+    readonly submittedByMemberId: CollabMemberId;
+    readonly targetAuthorityGeneration: number;
+    readonly transferId: string;
+}
+export interface CollabTransferredMembershipClaim {
+    readonly claim: string;
+    readonly expiresAt: CollabIsoTimestamp;
+    readonly memberId: CollabMemberId;
+    readonly projectId: CollabProjectId;
+    readonly targetAuthorityGeneration: number;
+    readonly transferId: string;
+}
+export interface CollabTransferredMembershipRedemptionReceiptSigningPayload {
+    readonly checkpointSha256: string;
+    readonly claimSha256: string;
+    readonly memberId: CollabMemberId;
+    readonly operationIntentId: string;
+    readonly projectId: CollabProjectId;
+    readonly receiptId: string;
+    readonly receiptKeyId: string;
+    readonly redeemedAt: CollabIsoTimestamp;
+    readonly signatureAlgorithm: 'ed25519';
+    readonly targetAuthorityGeneration: number;
+    readonly transferId: string;
+}
+export interface CollabTransferredMembershipRedemptionReceipt extends CollabTransferredMembershipRedemptionReceiptSigningPayload {
+    readonly signature: string;
+}
+interface CollabAuthorityRelinquishmentProofSigningPayloadBase {
+    readonly batchRevision: number;
+    readonly batchSha256: string;
+    readonly certificateAlgorithm: 'ed25519';
+    readonly checkpointSha256: string;
+    readonly committedAt: CollabIsoTimestamp;
+    readonly operationIntentId: string;
+    readonly projectId: CollabProjectId;
+    readonly transferId: string;
+}
+export type CollabAuthorityRelinquishmentProofSigningPayload = CollabAuthorityRelinquishmentProofSigningPayloadBase & ({
+    readonly sourceAuthority: CollabCheckpointAuthority & {
+        readonly kind: 'lan';
+    };
+    readonly sourceHostMemberId: CollabMemberId;
+    readonly targetAuthority: CollabCheckpointAuthority & {
+        readonly kind: 'cloud';
+    };
+} | {
+    readonly sourceAuthority: CollabCheckpointAuthority & {
+        readonly kind: 'cloud';
+    };
+    readonly sourceHostMemberId: null;
+    readonly targetAuthority: CollabCheckpointAuthority & {
+        readonly kind: 'lan';
+    };
+});
+export type CollabAuthorityRelinquishmentProof = CollabAuthorityRelinquishmentProofSigningPayload & {
+    readonly certificate: string;
+};
+export interface CollabAuthorityTransferStatus {
+    readonly batchRevision: number | null;
+    readonly batchSha256: string | null;
+    readonly checkpointSha256: string | null;
+    readonly createdAt: CollabIsoTimestamp;
+    readonly direction: CollabAuthorityTransferDirection;
+    readonly expiresAt: CollabIsoTimestamp;
+    readonly phase: CollabLanToCloudTransferPhase | CollabCloudToLanTransferPhase | CollabAuthorityTransferCancellationPhase;
+    readonly projectId: CollabProjectId;
+    readonly relinquishmentProof: CollabAuthorityRelinquishmentProof | null;
+    readonly sourceAuthority: CollabCheckpointAuthority;
+    readonly state: 'active' | 'cancelled' | 'completed';
+    readonly targetAuthority: CollabCheckpointAuthority;
+    readonly targetUrl: string;
+    readonly transferId: string;
+    readonly updatedAt: CollabIsoTimestamp;
+}
+interface CollabAuthorityMutationRequest {
+    readonly idempotencyKey: string;
+    readonly projectId: CollabProjectId;
+}
+export interface RequestLanToCloudTransferRequest extends CollabAuthorityMutationRequest {
+    readonly expectedAuthorityGeneration: number;
+    readonly targetUrl: string;
+}
+export interface AcceptLanToCloudTransferTargetRequest extends CollabAuthorityMutationRequest {
+    readonly expectedAuthorityGeneration: number;
+    readonly targetUrl: string;
+    readonly transferId: string;
+}
+export interface BeginLanToCloudTransferRequest extends CollabAuthorityMutationRequest {
+    readonly checkpointManifestSha256: string;
+    readonly expectedSourceAuthorityGeneration: number;
+    readonly sourceHostMemberId: CollabMemberId;
+    readonly sourceProof: string;
+    readonly targetUrl: string;
+    readonly transferId: string;
+}
+export interface GetProjectAuthorityTransferRequest {
+    readonly projectId: CollabProjectId;
+    readonly transferId: string;
+}
+export interface RotateTransferredMembershipClaimsRequest extends CollabAuthorityMutationRequest {
+    readonly expectedBatchRevision: number;
+    readonly expectedBatchSha256: string;
+    readonly transferId: string;
+}
+export interface AcknowledgeTransferredMembershipClaimBatchRequest extends CollabAuthorityMutationRequest {
+    readonly batchRevision: number;
+    readonly batchSha256: string;
+    readonly operationIntentId: string;
+    readonly transferId: string;
+}
+export interface GetTransferredMembershipClaimRequest {
+    readonly projectId: CollabProjectId;
+    readonly transferId: string;
+}
+interface ClaimTransferredMembershipRequestBase extends CollabAuthorityMutationRequest {
+    readonly claim: string;
+    readonly transferId: string;
+}
+export interface ClaimTransferredCloudMembershipRequest extends ClaimTransferredMembershipRequestBase {
+    readonly credentialHash?: never;
+}
+export interface ClaimTransferredLanMembershipRequest extends ClaimTransferredMembershipRequestBase {
+    readonly credentialHash: string;
+}
+export type ClaimTransferredMembershipRequest = ClaimTransferredCloudMembershipRequest | ClaimTransferredLanMembershipRequest;
+export interface AcknowledgeTransferredMembershipClaimRedemptionRequest extends CollabAuthorityMutationRequest {
+    readonly receipt: CollabTransferredMembershipRedemptionReceipt;
+    readonly transferId: string;
+}
+export interface CollabTransferredMembershipRedemptionAcknowledgement {
+    readonly acknowledgedAt: CollabIsoTimestamp;
+    readonly memberId: CollabMemberId;
+    readonly projectId: CollabProjectId;
+    readonly receiptId: string;
+    readonly transferId: string;
+}
+export interface CommitLanToCloudRelinquishmentRequest extends CollabAuthorityMutationRequest {
+    readonly proof: CollabAuthorityRelinquishmentProof;
+    readonly transferId: string;
+}
+export interface BeginCloudToLanTransferRequest extends CollabAuthorityMutationRequest {
+    readonly expectedAuthorityGeneration: number;
+    readonly targetHostMemberId: CollabMemberId;
+    readonly targetUrl: string;
+}
+export interface AcceptCloudToLanTransferTargetRequest extends CollabAuthorityMutationRequest {
+    readonly targetHostMemberId: CollabMemberId;
+    readonly targetProof: string;
+    readonly transferId: string;
+}
+export interface ReportCloudToLanTargetStagedRequest extends CollabAuthorityMutationRequest {
+    readonly checkpointSha256: string;
+    readonly claimBatch: CollabTransferredMembershipClaimBatch;
+    readonly stageSha256: string;
+    readonly targetAuthority: CollabCheckpointAuthority;
+    readonly targetProof: string;
+    readonly transferId: string;
+}
+export interface ConfirmCloudToLanTargetActiveRequest extends CollabAuthorityMutationRequest {
+    readonly relinquishmentProof: CollabAuthorityRelinquishmentProof;
+    readonly targetActivationProof: string;
+    readonly transferId: string;
+}
+export interface CancelProjectAuthorityTransferRequest extends CollabAuthorityMutationRequest {
+    readonly expectedPhase: CollabAuthorityTransferCancellablePhase;
+    readonly transferId: string;
+}
+export declare const COLLAB_AUTHORITY_TRANSFER_OPERATIONS: readonly ["requestLanToCloudTransfer", "acceptLanToCloudTransferTarget", "beginLanToCloudTransfer", "getProjectAuthorityTransfer", "rotateTransferredMembershipClaims", "acknowledgeTransferredMembershipClaimBatch", "getTransferredMembershipClaim", "claimTransferredMembership", "acknowledgeTransferredMembershipClaimRedemption", "commitLanToCloudRelinquishment", "beginCloudToLanTransfer", "acceptCloudToLanTransferTarget", "reportCloudToLanTargetStaged", "confirmCloudToLanTargetActive", "cancelProjectAuthorityTransfer"];
+export type CollabAuthorityTransferOperation = typeof COLLAB_AUTHORITY_TRANSFER_OPERATIONS[number];
+export interface CollabAuthorityTransferOperationMap {
+    readonly requestLanToCloudTransfer: {
+        readonly request: RequestLanToCloudTransferRequest;
+        readonly response: CollabAuthorityTransferStatus;
+    };
+    readonly acceptLanToCloudTransferTarget: {
+        readonly request: AcceptLanToCloudTransferTargetRequest;
+        readonly response: CollabAuthorityTransferStatus;
+    };
+    readonly beginLanToCloudTransfer: {
+        readonly request: BeginLanToCloudTransferRequest;
+        readonly response: CollabAuthorityTransferStatus;
+    };
+    readonly getProjectAuthorityTransfer: {
+        readonly request: GetProjectAuthorityTransferRequest;
+        readonly response: CollabAuthorityTransferStatus;
+    };
+    readonly rotateTransferredMembershipClaims: {
+        readonly request: RotateTransferredMembershipClaimsRequest;
+        readonly response: CollabTransferredMembershipClaimBatch;
+    };
+    readonly acknowledgeTransferredMembershipClaimBatch: {
+        readonly request: AcknowledgeTransferredMembershipClaimBatchRequest;
+        readonly response: CollabTransferredMembershipClaimCustodyReceipt;
+    };
+    readonly getTransferredMembershipClaim: {
+        readonly request: GetTransferredMembershipClaimRequest;
+        readonly response: CollabTransferredMembershipClaim;
+    };
+    readonly claimTransferredMembership: {
+        readonly request: ClaimTransferredMembershipRequest;
+        readonly response: CollabTransferredMembershipRedemptionReceipt;
+    };
+    readonly acknowledgeTransferredMembershipClaimRedemption: {
+        readonly request: AcknowledgeTransferredMembershipClaimRedemptionRequest;
+        readonly response: CollabTransferredMembershipRedemptionAcknowledgement;
+    };
+    readonly commitLanToCloudRelinquishment: {
+        readonly request: CommitLanToCloudRelinquishmentRequest;
+        readonly response: CollabAuthorityTransferStatus;
+    };
+    readonly beginCloudToLanTransfer: {
+        readonly request: BeginCloudToLanTransferRequest;
+        readonly response: CollabAuthorityTransferStatus;
+    };
+    readonly acceptCloudToLanTransferTarget: {
+        readonly request: AcceptCloudToLanTransferTargetRequest;
+        readonly response: CollabAuthorityTransferStatus;
+    };
+    readonly reportCloudToLanTargetStaged: {
+        readonly request: ReportCloudToLanTargetStagedRequest;
+        readonly response: CollabTransferredMembershipClaimCustodyReceipt;
+    };
+    readonly confirmCloudToLanTargetActive: {
+        readonly request: ConfirmCloudToLanTargetActiveRequest;
+        readonly response: CollabAuthorityTransferStatus;
+    };
+    readonly cancelProjectAuthorityTransfer: {
+        readonly request: CancelProjectAuthorityTransferRequest;
+        readonly response: CollabAuthorityTransferStatus;
+    };
+}
+export declare function decodeCollabAuthorityTransferProposal(value: unknown): CollabAuthorityTransferProposal;
+export declare function decodeCollabTransferredMembershipClaimBatch(value: unknown): CollabTransferredMembershipClaimBatch;
+export declare function encodeCollabTransferredMembershipClaimBatchDigestInput(batch: CollabTransferredMembershipClaimBatch): string;
+export declare function decodeCollabTransferredMembershipClaimCustodyReceipt(value: unknown): CollabTransferredMembershipClaimCustodyReceipt;
+export declare function decodeCollabTransferredMembershipClaim(value: unknown): CollabTransferredMembershipClaim;
+export declare function encodeCollabTransferredMembershipRedemptionReceiptSigningInput(payload: CollabTransferredMembershipRedemptionReceiptSigningPayload): string;
+export declare function decodeCollabTransferredMembershipRedemptionReceipt(value: unknown): CollabTransferredMembershipRedemptionReceipt;
+export declare function encodeCollabAuthorityRelinquishmentProofSigningInput(payload: CollabAuthorityRelinquishmentProofSigningPayload): string;
+export declare function decodeCollabAuthorityRelinquishmentProof(value: unknown): CollabAuthorityRelinquishmentProof;
+export declare function decodeCollabAuthorityTransferLifecycleFence(value: unknown): {
+    batchRevision: number | null;
+    batchSha256: string | null;
+    checkpointSha256: string | null;
+    direction: "cloud-to-lan" | "lan-to-cloud";
+    phase: "collecting-readiness" | "source-quiesced" | "checkpoint-received" | "checkpoint-validated" | "claims-retained" | "repository-published" | "source-relinquished" | "cloud-activated" | "completed" | "cloud-quiesced" | "checkpoint-captured" | "target-staged" | "cloud-relinquished" | "lan-activated" | "cancel-intent" | "target-invalidated" | "target-cleaned" | "source-reopened" | "cancelled";
+    relinquishmentRequired: boolean;
+};
+export declare function decodeCollabAuthorityTransferStatus(value: unknown): CollabAuthorityTransferStatus;
+export declare function decodeCollabAuthorityTransferOperationRequest<Operation extends CollabAuthorityTransferOperation>(operation: Operation, value: unknown): CollabAuthorityTransferOperationMap[Operation]['request'];
+export declare function decodeCollabAuthorityTransferOperationResponse<Operation extends CollabAuthorityTransferOperation>(operation: Operation, value: unknown): CollabAuthorityTransferOperationMap[Operation]['response'];
+export {};