@claudian-collab/protocol 3.1.0 → 3.2.0

package/README.md

@@ -1,6 +1,6 @@
 # @claudian-collab/protocol
 
-The canonical shared Collab wire contract, produced from the
+The canonical shared Collab wire and offline backup 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,
@@ -19,7 +19,7 @@ or compatibility rules.
   `collabMemberRef`)
 - Shared limits that client and server must agree on (`COLLAB_LIMITS`)
 - Protocol-version negotiation (`COLLAB_PROTOCOL_VERSION`, envelope decoding)
-- Canonical Project checkpoint profiles, logical records, authority-generation transfer, exact membership claims, target-signed redemption receipts, and Project retirement contracts
+- Canonical Project checkpoint profiles, logical records, authority-generation transfer, exact membership claims, target-signed redemption receipts, offline backup operational continuity, 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
@@ -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 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.
+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`; authority-transfer and export retain wire-visible coordination format v1, while offline backup format v2 adds lifecycle journals, recovery evidence, claim hashes, public receipt verifiers, exact custody/redemption receipts, terminal replay facts, and protected claim-envelope metadata plus ciphertext. Portable profiles exclude engine storage, paths, credentials, tokens, private keys, and operational refs, and backups exclude raw claims and private keys. 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,7 +62,7 @@ part of the public surface.
 
 Package SemVer, canonical wire version, and Cloud binding version are independent concepts.
 
-- **Package version** (this `package.json`): `3.1.0`. Patch releases preserve
+- **Package version** (this `package.json`): `3.2.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,
@@ -70,7 +70,9 @@ Package SemVer, canonical wire version, and Cloud binding version are independen
   proven additive control operation may use a package minor release without a
   wire-version increase; existing operation declarations and fixtures must stay
   exact. Package 3 and wire 6 support exact transfer-claim batches and a
-  source-pinned target receipt verifier. The package version never signals wire
+  source-pinned target receipt verifier. Package 3.2 adds offline backup
+  coordination format v2 without changing authority-transfer/export format v1,
+  canonical wire v6, or Cloud binding v2. 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

package/dist/CollabProjectBackupCheckpoint.d.ts

@@ -0,0 +1,164 @@
+import { type CollabAuthorityRelinquishmentProof, type CollabAuthorityTransferReceiptVerifier, type CollabTransferredMembershipClaimCustodyReceipt, type CollabTransferredMembershipRedemptionReceipt } from './CollabAuthorityTransfer';
+import { type CollabControlOperation } from './CollabControlOperationCodecs';
+import { type CollabCheckpointAuthority, type CollabCheckpointBackupRecord, type CollabCheckpointGitRef, type CollabProjectCheckpointManifest } from './CollabProjectCheckpoint';
+import type { CollabIsoTimestamp, CollabMemberId, CollabProjectId } from './types';
+export declare const COLLAB_PROJECT_BACKUP_COORDINATION_FORMAT_VERSION: 2;
+export declare const COLLAB_PROJECT_BACKUP_RECORD_KINDS: readonly ("member" | "request" | "ticket" | "project" | "request-comment" | "ticket-comment" | "ticket-relation" | "ticket-mention" | "cloud-event" | "cloud-event-cursor" | "idempotency-result" | "principal-binding" | "repository-placement" | "lifecycle-state" | "terminal-responder" | "protected-claim-envelope" | "tombstone" | "schema-catalog" | "server-compatibility" | "authority-volume-pair" | "lifecycle-journal" | "authority-transfer-recovery" | "transferred-membership-claim" | "transfer-receipt-key" | "transfer-claim-batch-receipt" | "transfer-redemption-receipt" | "terminal-principal" | "terminal-responder-replay" | "leave-former-principal-replay")[];
+export type CollabProjectBackupRecordKind = typeof COLLAB_PROJECT_BACKUP_RECORD_KINDS[number];
+interface BackupRecordBase<Kind extends string, Value> {
+    readonly kind: Kind;
+    readonly recordId: string;
+    readonly revision: number;
+    readonly value: Value;
+}
+export type CollabProjectBackupLifecycleKind = 'authority-transfer' | 'backup' | 'delete' | 'export' | 'leave' | 'retire';
+export type CollabProjectBackupLifecycleState = 'active' | 'cancelled' | 'completed' | 'recovery-required';
+export interface CollabProjectBackupInactiveRepositoryPublication {
+    readonly artifactKey: string;
+    readonly bundleByteCount: number;
+    readonly bundleSha256: string;
+    readonly objectFormat: 'sha1' | 'sha256';
+    readonly operationId: string;
+    readonly placementGeneration: number;
+    readonly projectId: CollabProjectId;
+    readonly publicationMarkerSha256: string;
+    readonly refs: readonly CollabCheckpointGitRef[];
+    readonly repositoryStorageKey: string;
+    readonly status: 'inactive';
+    readonly storageNodeId: string;
+    readonly validationMarkerSha256: string;
+}
+export interface CollabProjectBackupLanToCloudSourceEvidence {
+    readonly checkpointManifestSha256: string;
+    readonly principalId: string;
+    readonly proof: string;
+    readonly receiptKeyId: string;
+    readonly receiptPublicKey: string;
+    readonly schemaVersion: 1;
+}
+export interface CollabProjectBackupCloudToLanTargetEvidence {
+    readonly acceptanceIntentId: string;
+    readonly principalId: string;
+    readonly proof: string;
+    readonly receiptKeyId: string;
+    readonly receiptPublicKey: string;
+    readonly schemaVersion: 1;
+}
+export type CollabProjectBackupLifecycleJournalRecord = BackupRecordBase<'lifecycle-journal', {
+    readonly actorMemberId: CollabMemberId | null;
+    readonly batchRevision: number | null;
+    readonly batchSha256: string | null;
+    readonly checkpointSha256: string | null;
+    readonly createdAt: CollabIsoTimestamp;
+    readonly direction: 'cloud-to-lan' | 'lan-to-cloud' | null;
+    readonly expectedAuthorityGeneration: number;
+    readonly expectedPersonalRefOid: string | null;
+    readonly idempotencyKey: string;
+    readonly operationId: string;
+    readonly operationKind: CollabProjectBackupLifecycleKind;
+    readonly phase: string;
+    readonly projectId: CollabProjectId;
+    readonly recoveryFromPhase: string | null;
+    readonly requestFingerprint: string;
+    readonly resultSha256: string | null;
+    readonly scheduledAt: CollabIsoTimestamp;
+    readonly state: CollabProjectBackupLifecycleState;
+    readonly updatedAt: CollabIsoTimestamp;
+}>;
+export type CollabProjectBackupAuthorityTransferRecoveryRecord = BackupRecordBase<'authority-transfer-recovery', {
+    readonly cancellationRequestSha256: string | null;
+    readonly createdAt: CollabIsoTimestamp;
+    readonly expiresAt: CollabIsoTimestamp;
+    readonly inactivePublication: CollabProjectBackupInactiveRepositoryPublication | null;
+    readonly projectId: CollabProjectId;
+    readonly relinquishmentProof: CollabAuthorityRelinquishmentProof | null;
+    readonly sourceAuthority: CollabCheckpointAuthority;
+    readonly sourceHostMemberId: CollabMemberId | null;
+    readonly sourceEvidence: CollabProjectBackupLanToCloudSourceEvidence | null;
+    readonly sourceReopenSha256: string | null;
+    readonly stageSha256: string | null;
+    readonly targetActivationProof: string | null;
+    readonly targetActivationRequestSha256: string | null;
+    readonly targetAuthority: CollabCheckpointAuthority;
+    readonly targetHostMemberId: CollabMemberId | null;
+    readonly targetEvidence: CollabProjectBackupCloudToLanTargetEvidence | null;
+    readonly targetUrl: string;
+    readonly transferId: string;
+    readonly updatedAt: CollabIsoTimestamp;
+}>;
+export type CollabProjectBackupTransferredMembershipClaimRecord = BackupRecordBase<'transferred-membership-claim', {
+    readonly batchRevision: number;
+    readonly checkpointSha256: string;
+    readonly claimSha256: string;
+    readonly createdAt: CollabIsoTimestamp;
+    readonly expiresAt: CollabIsoTimestamp;
+    readonly memberId: CollabMemberId;
+    readonly operationIntentId: string | null;
+    readonly projectId: CollabProjectId;
+    readonly redemptionReceiptId: string | null;
+    readonly state: 'redeemed' | 'revoked' | 'unclaimed';
+    readonly targetPrincipalId: string | null;
+    readonly transferId: string;
+    readonly updatedAt: CollabIsoTimestamp;
+}>;
+export type CollabProjectBackupTransferReceiptKeyRecord = BackupRecordBase<'transfer-receipt-key', CollabAuthorityTransferReceiptVerifier & {
+    readonly createdAt: CollabIsoTimestamp;
+}>;
+export type CollabProjectBackupTransferClaimBatchReceiptRecord = BackupRecordBase<'transfer-claim-batch-receipt', {
+    readonly receipt: CollabTransferredMembershipClaimCustodyReceipt;
+}>;
+export type CollabProjectBackupTransferRedemptionReceiptRecord = BackupRecordBase<'transfer-redemption-receipt', {
+    readonly acknowledgedAt: CollabIsoTimestamp | null;
+    readonly projectId: CollabProjectId;
+    readonly receipt: CollabTransferredMembershipRedemptionReceipt;
+}>;
+export type CollabProjectBackupTerminalPrincipalRecord = BackupRecordBase<'terminal-principal', {
+    readonly acknowledgedAt: CollabIsoTimestamp | null;
+    readonly memberId: CollabMemberId;
+    readonly operationId: string;
+    readonly operationKind: 'authority-transfer' | 'retire';
+    readonly principalId: string;
+    readonly projectId: CollabProjectId;
+}>;
+export type CollabProjectBackupTerminalResponderReplayRecord = BackupRecordBase<'terminal-responder-replay', {
+    readonly memberId: CollabMemberId;
+    readonly operationId: string;
+    readonly projectId: CollabProjectId;
+    readonly requestSha256: string;
+}>;
+export type CollabProjectBackupLeaveFormerPrincipalReplayRecord = BackupRecordBase<'leave-former-principal-replay', {
+    readonly completedAt: CollabIsoTimestamp | null;
+    readonly createdAt: CollabIsoTimestamp;
+    readonly expectedPersonalRefOid: string;
+    readonly expiresAt: CollabIsoTimestamp;
+    readonly intentId: string;
+    readonly memberId: CollabMemberId;
+    readonly operationId: string;
+    readonly principalSha256: string;
+    readonly projectId: CollabProjectId;
+    readonly requestFingerprint: string;
+    readonly resultSha256: string | null;
+    readonly state: 'completed' | 'recovering';
+}>;
+export type CollabProjectBackupContinuityRecord = CollabProjectBackupLifecycleJournalRecord | CollabProjectBackupAuthorityTransferRecoveryRecord | CollabProjectBackupTransferredMembershipClaimRecord | CollabProjectBackupTransferReceiptKeyRecord | CollabProjectBackupTransferClaimBatchReceiptRecord | CollabProjectBackupTransferRedemptionReceiptRecord | CollabProjectBackupTerminalPrincipalRecord | CollabProjectBackupTerminalResponderReplayRecord | CollabProjectBackupLeaveFormerPrincipalReplayRecord;
+type CollabProjectBackupBaseRecord = Exclude<CollabCheckpointBackupRecord, {
+    readonly kind: 'lifecycle-state';
+}>;
+export type CollabProjectBackupRecord = CollabProjectBackupBaseRecord | CollabProjectBackupContinuityRecord;
+export type CollabProjectBackupCheckpointManifest = Omit<CollabProjectCheckpointManifest, 'coordinationFormatVersion' | 'profile'> & {
+    readonly coordinationFormatVersion: typeof COLLAB_PROJECT_BACKUP_COORDINATION_FORMAT_VERSION;
+    readonly profile: 'backup';
+};
+export declare function collabProjectBackupIdempotencyRecordId(input: Readonly<{
+    readonly idempotencyKey: string;
+    readonly memberId: CollabMemberId;
+    readonly operation: CollabControlOperation;
+    readonly projectId: CollabProjectId;
+}>): string;
+export declare function decodeCollabProjectBackupCheckpointManifest(value: unknown): CollabProjectBackupCheckpointManifest;
+export declare function encodeCollabProjectBackupCheckpointManifestCanonicalJson(manifest: CollabProjectBackupCheckpointManifest): string;
+export declare function encodeCollabProjectBackupCheckpointManifestDigestInput(manifest: CollabProjectBackupCheckpointManifest): string;
+export declare function decodeCollabProjectBackupCheckpointCoordinationNdjson(value: string): readonly CollabProjectBackupRecord[];
+export declare function encodeCollabProjectBackupCheckpointCoordinationNdjson(records: readonly CollabProjectBackupRecord[]): string;
+export declare function validateCollabProjectBackupCheckpointConsistency(manifest: CollabProjectBackupCheckpointManifest, records: readonly CollabProjectBackupRecord[]): readonly CollabProjectBackupRecord[];
+export {};