@claudian-collab/protocol 1.0.0 → 2.0.0

package/dist/CollabProjectCheckpoint.d.ts

@@ -0,0 +1,275 @@
+import { type CollabAuthorityRelinquishmentProof, type CollabAuthorityTransferDirection, type CollabAuthorityTransferStatus } from './CollabAuthorityTransfer';
+import { type CollabCloudProjectEvent } from './CollabCloudProjectEvent';
+import { COLLAB_PROTOCOL_VERSION } from './CollabConstants';
+import { type CollabControlOperation } from './CollabControlOperationCodecs';
+import type { CollabGitOid, CollabIsoTimestamp, CollabMemberId, CollabProjectId } from './types';
+export declare const COLLAB_PROJECT_CHECKPOINT_MANIFEST_SCHEMA_VERSION: 1;
+export declare const COLLAB_PROJECT_COORDINATION_FORMAT_VERSION: 1;
+export declare const COLLAB_PROTECTED_CLAIM_ENVELOPE_VERSION: 1;
+export declare const COLLAB_PROTECTED_CLAIM_ENVELOPE_LIMITS: Readonly<{
+    readonly maxCiphertextBytes: 4096;
+    readonly nonceBytes: 24;
+    readonly tagBytes: 16;
+}>;
+export declare const COLLAB_CHECKPOINT_PROFILES: readonly ["authority-transfer", "backup", "export"];
+export declare const COLLAB_PROJECT_CHECKPOINT_ARTIFACTS: readonly ["checkpoint.json", "coordination.ndjson", "repository.bundle"];
+export declare const COLLAB_CHECKPOINT_ARTIFACT_LIMITS: Readonly<{
+    readonly maxCoordinationBytes: number;
+    readonly maxManifestBytes: number;
+    readonly maxRepositoryBundleBytes: number;
+    readonly maxStagingBytes: number;
+}>;
+export declare const COLLAB_CHECKPOINT_PORTABLE_RECORD_KINDS: readonly ["project", "member", "request", "request-comment", "ticket", "ticket-comment", "ticket-relation", "ticket-mention"];
+export declare const COLLAB_CHECKPOINT_BACKUP_RECORD_KINDS: readonly ["project", "member", "request", "request-comment", "ticket", "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"];
+export type CollabCheckpointProfile = typeof COLLAB_CHECKPOINT_PROFILES[number];
+export type CollabCheckpointAuthorityKind = 'cloud' | 'lan';
+export type CollabCheckpointObjectFormat = 'sha1' | 'sha256';
+export type CollabCheckpointPortableRecordKind = typeof COLLAB_CHECKPOINT_PORTABLE_RECORD_KINDS[number];
+export type CollabCheckpointBackupRecordKind = typeof COLLAB_CHECKPOINT_BACKUP_RECORD_KINDS[number];
+export interface CollabCheckpointAuthority {
+    readonly generation: number;
+    readonly kind: CollabCheckpointAuthorityKind;
+}
+export interface CollabCheckpointArtifactFact {
+    readonly byteCount: number;
+    readonly name: 'coordination.ndjson' | 'repository.bundle';
+    readonly sha256: string;
+}
+export interface CollabCheckpointGitRef {
+    readonly name: string;
+    readonly oid: CollabGitOid;
+}
+export interface CollabProjectCheckpointManifest {
+    readonly artifacts: readonly CollabCheckpointArtifactFact[];
+    readonly coordinationFormatVersion: typeof COLLAB_PROJECT_COORDINATION_FORMAT_VERSION;
+    readonly createdAt: CollabIsoTimestamp;
+    readonly expectedMainOid: CollabGitOid;
+    readonly gitObjectFormat: CollabCheckpointObjectFormat;
+    readonly manifestSchemaVersion: typeof COLLAB_PROJECT_CHECKPOINT_MANIFEST_SCHEMA_VERSION;
+    readonly manifestSha256: string;
+    readonly operationId: string;
+    readonly profile: CollabCheckpointProfile;
+    readonly projectId: CollabProjectId;
+    readonly protocolVersion: typeof COLLAB_PROTOCOL_VERSION;
+    readonly refs: readonly CollabCheckpointGitRef[];
+    readonly sourceAuthority: CollabCheckpointAuthority;
+    readonly targetAuthority: CollabCheckpointAuthority | null;
+}
+interface CollabCheckpointRecordBase<Kind extends string, Value> {
+    readonly kind: Kind;
+    readonly recordId: string;
+    readonly revision: number;
+    readonly value: Value;
+}
+export type CollabCheckpointProjectRecord = CollabCheckpointRecordBase<'project', {
+    readonly activatedAt: CollabIsoTimestamp;
+    readonly authorityGeneration: number;
+    readonly createdAt: CollabIsoTimestamp;
+    readonly expectedMainOid: CollabGitOid;
+    readonly managerSetGeneration: number;
+    readonly name: string;
+    readonly projectId: CollabProjectId;
+}>;
+export type CollabCheckpointMemberRecord = CollabCheckpointRecordBase<'member', {
+    readonly activatedAt: CollabIsoTimestamp | null;
+    readonly createdAt: CollabIsoTimestamp;
+    readonly displayName: string;
+    readonly memberId: CollabMemberId;
+    readonly personalRef: string;
+    readonly projectId: CollabProjectId;
+    readonly role: 'manager' | 'member';
+    readonly status: 'active' | 'left' | 'revoked';
+    readonly revokedAt: CollabIsoTimestamp | null;
+    readonly updatedAt: CollabIsoTimestamp;
+}>;
+export type CollabCheckpointRequestRecord = CollabCheckpointRecordBase<'request', {
+    readonly createdAt: CollabIsoTimestamp;
+    readonly description: string;
+    readonly firstBaseOid: CollabGitOid;
+    readonly latestHeadOid: CollabGitOid;
+    readonly memberId: CollabMemberId;
+    readonly mergedOid: CollabGitOid | null;
+    readonly projectId: CollabProjectId;
+    readonly requestId: string;
+    readonly status: 'discarded' | 'merged' | 'open';
+    readonly updatedAt: CollabIsoTimestamp;
+}>;
+export type CollabCheckpointRequestCommentRecord = CollabCheckpointRecordBase<'request-comment', {
+    readonly authorMemberId: CollabMemberId;
+    readonly body: string;
+    readonly commentId: string;
+    readonly createdAt: CollabIsoTimestamp;
+    readonly projectId: CollabProjectId;
+    readonly requestId: string;
+}>;
+export type CollabCheckpointTicketRecord = CollabCheckpointRecordBase<'ticket', {
+    readonly authorMemberId: CollabMemberId;
+    readonly body: string;
+    readonly closedAt: CollabIsoTimestamp | null;
+    readonly closedByMemberId: CollabMemberId | null;
+    readonly createdAt: CollabIsoTimestamp;
+    readonly number: number;
+    readonly projectId: CollabProjectId;
+    readonly status: 'closed' | 'open';
+    readonly ticketId: string;
+    readonly title: string;
+    readonly updatedAt: CollabIsoTimestamp;
+}>;
+export type CollabCheckpointTicketCommentRecord = CollabCheckpointRecordBase<'ticket-comment', {
+    readonly authorMemberId: CollabMemberId;
+    readonly body: string;
+    readonly commentId: string;
+    readonly createdAt: CollabIsoTimestamp;
+    readonly projectId: CollabProjectId;
+    readonly ticketId: string;
+}>;
+export type CollabCheckpointTicketRelationRecord = CollabCheckpointRecordBase<'ticket-relation', {
+    readonly acceptedAt: CollabIsoTimestamp | null;
+    readonly acceptedMergeOid: CollabGitOid | null;
+    readonly commitOid: CollabGitOid;
+    readonly createdAt: CollabIsoTimestamp;
+    readonly createdByMemberId: CollabMemberId;
+    readonly kind: 'references' | 'resolves';
+    readonly projectId: CollabProjectId;
+    readonly relationId: string;
+    readonly requestId: string;
+    readonly state: 'accepted' | 'pending';
+    readonly ticketId: string;
+    readonly updatedAt: CollabIsoTimestamp;
+}>;
+export type CollabCheckpointTicketMentionRecord = CollabCheckpointRecordBase<'ticket-mention', {
+    readonly createdAt: CollabIsoTimestamp;
+    readonly mentionedMemberId: CollabMemberId;
+    readonly projectId: CollabProjectId;
+    readonly sourceId: string;
+    readonly sourceKind: 'comment' | 'description';
+    readonly ticketId: string;
+}>;
+export type CollabCheckpointCloudEventRecord = CollabCheckpointRecordBase<'cloud-event', {
+    readonly event: CollabCloudProjectEvent;
+}>;
+export type CollabCheckpointCloudEventCursorRecord = CollabCheckpointRecordBase<'cloud-event-cursor', {
+    readonly currentSequence: number;
+    readonly projectId: CollabProjectId;
+    readonly updatedAt: CollabIsoTimestamp;
+}>;
+export type CollabCheckpointIdempotencyResultRecord = CollabCheckpointRecordBase<'idempotency-result', {
+    readonly createdAt: CollabIsoTimestamp;
+    readonly idempotencyKey: string;
+    readonly memberId: CollabMemberId;
+    readonly operation: CollabControlOperation;
+    readonly projectId: CollabProjectId;
+    readonly requestFingerprint: string;
+    readonly responseJson: string;
+}>;
+export type CollabCheckpointPrincipalBindingRecord = CollabCheckpointRecordBase<'principal-binding', {
+    readonly boundAt: CollabIsoTimestamp;
+    readonly memberId: CollabMemberId;
+    readonly principalId: string;
+    readonly projectId: CollabProjectId;
+}>;
+export type CollabCheckpointRepositoryPlacementRecord = CollabCheckpointRecordBase<'repository-placement', {
+    readonly nodeId: string;
+    readonly placementGeneration: number;
+    readonly projectId: CollabProjectId;
+    readonly repositoryIdentity: string;
+}>;
+type CollabCheckpointAuthorityTransferLifecycleState = {
+    readonly batchRevision: number | null;
+    readonly batchSha256: string | null;
+    readonly checkpointSha256: string | null;
+    readonly direction: CollabAuthorityTransferDirection;
+    readonly operationId: string;
+    readonly operationKind: 'authority-transfer';
+    readonly phase: CollabAuthorityTransferStatus['phase'];
+    readonly projectId: CollabProjectId;
+    readonly relinquishmentProof: CollabAuthorityRelinquishmentProof | null;
+    readonly updatedAt: CollabIsoTimestamp;
+};
+type CollabCheckpointInternalLifecycleState = {
+    readonly batchRevision: null;
+    readonly batchSha256: null;
+    readonly direction: null;
+    readonly operationId: string;
+    readonly phase: string;
+    readonly projectId: CollabProjectId;
+    readonly relinquishmentProof: null;
+    readonly updatedAt: CollabIsoTimestamp;
+} & ({
+    readonly checkpointSha256: string | null;
+    readonly operationKind: 'backup';
+} | {
+    readonly checkpointSha256: null;
+    readonly operationKind: 'delete' | 'retire';
+});
+export type CollabCheckpointLifecycleStateRecord = CollabCheckpointRecordBase<'lifecycle-state', CollabCheckpointAuthorityTransferLifecycleState | CollabCheckpointInternalLifecycleState>;
+export interface CollabCheckpointTerminalAcknowledgement {
+    readonly acknowledgedAt: CollabIsoTimestamp;
+    readonly memberId: CollabMemberId;
+    readonly principalId: string;
+}
+export type CollabCheckpointTerminalResponderRecord = CollabCheckpointRecordBase<'terminal-responder', {
+    readonly acknowledgements: readonly CollabCheckpointTerminalAcknowledgement[];
+    readonly eligibleMemberIds: readonly CollabMemberId[];
+    readonly expiresAt: CollabIsoTimestamp;
+    readonly operation: 'getProjectAuthorityTransfer' | 'retireProject';
+    readonly operationId: string;
+    readonly projectId: CollabProjectId;
+    readonly responseJson: string;
+}>;
+export interface CollabProtectedClaimAssociatedData {
+    readonly authorityGeneration: number;
+    readonly checkpointSha256: string;
+    readonly claimSha256: string;
+    readonly envelopeVersion: typeof COLLAB_PROTECTED_CLAIM_ENVELOPE_VERSION;
+    readonly environmentIdentity: string;
+    readonly memberId: CollabMemberId;
+    readonly projectId: CollabProjectId;
+    readonly transferId: string;
+}
+export type CollabCheckpointProtectedClaimEnvelopeRecord = CollabCheckpointRecordBase<'protected-claim-envelope', {
+    readonly associatedData: CollabProtectedClaimAssociatedData;
+    readonly associatedDataSha256: string;
+    readonly ciphertext: string;
+    readonly encryptionAlgorithm: 'xchacha20-poly1305';
+    readonly expiresAt: CollabIsoTimestamp;
+    readonly keyId: string;
+    readonly keyVersion: number;
+    readonly memberId: CollabMemberId;
+    readonly nonce: string;
+    readonly receiptKeyId: string;
+    readonly tag: string;
+    readonly transferId: string;
+}>;
+export type CollabCheckpointTombstoneRecord = CollabCheckpointRecordBase<'tombstone', {
+    readonly authorityGeneration: number;
+    readonly projectId: CollabProjectId;
+    readonly retiredAt: CollabIsoTimestamp;
+    readonly terminalExpiresAt: CollabIsoTimestamp;
+}>;
+export type CollabCheckpointSchemaCatalogRecord = CollabCheckpointRecordBase<'schema-catalog', {
+    readonly coordinationSchemaVersion: number;
+    readonly projectId: CollabProjectId;
+    readonly repositoryFormatVersion: number;
+}>;
+export type CollabCheckpointServerCompatibilityRecord = CollabCheckpointRecordBase<'server-compatibility', {
+    readonly maximumBuild: string;
+    readonly minimumBuild: string;
+    readonly projectId: CollabProjectId;
+}>;
+export type CollabCheckpointAuthorityVolumePairRecord = CollabCheckpointRecordBase<'authority-volume-pair', {
+    readonly authorityId: string;
+    readonly authorityVolumeIdentity: string;
+    readonly projectId: CollabProjectId;
+    readonly restoreEpoch: number;
+}>;
+export type CollabCheckpointPortableRecord = CollabCheckpointProjectRecord | CollabCheckpointMemberRecord | CollabCheckpointRequestRecord | CollabCheckpointRequestCommentRecord | CollabCheckpointTicketRecord | CollabCheckpointTicketCommentRecord | CollabCheckpointTicketRelationRecord | CollabCheckpointTicketMentionRecord;
+export type CollabCheckpointBackupRecord = CollabCheckpointPortableRecord | CollabCheckpointCloudEventRecord | CollabCheckpointCloudEventCursorRecord | CollabCheckpointIdempotencyResultRecord | CollabCheckpointPrincipalBindingRecord | CollabCheckpointRepositoryPlacementRecord | CollabCheckpointLifecycleStateRecord | CollabCheckpointTerminalResponderRecord | CollabCheckpointProtectedClaimEnvelopeRecord | CollabCheckpointTombstoneRecord | CollabCheckpointSchemaCatalogRecord | CollabCheckpointServerCompatibilityRecord | CollabCheckpointAuthorityVolumePairRecord;
+export declare function decodeCollabProjectCheckpointManifest(value: unknown): CollabProjectCheckpointManifest;
+export declare function encodeCollabProjectCheckpointManifestCanonicalJson(manifest: CollabProjectCheckpointManifest): string;
+export declare function encodeCollabProjectCheckpointManifestDigestInput(manifest: CollabProjectCheckpointManifest): string;
+export declare function encodeCollabProtectedClaimAssociatedData(associatedData: CollabProtectedClaimAssociatedData): string;
+export declare function decodeCollabProjectCheckpointCoordinationNdjson(value: string, profile: CollabCheckpointProfile): readonly CollabCheckpointBackupRecord[];
+export declare function encodeCollabProjectCheckpointCoordinationNdjson(records: readonly CollabCheckpointBackupRecord[], profile: CollabCheckpointProfile): string;
+export declare function validateCollabProjectCheckpointConsistency(manifest: CollabProjectCheckpointManifest, records: readonly CollabCheckpointBackupRecord[]): readonly CollabCheckpointBackupRecord[];
+export {};