@claudian-collab/protocol 3.3.1 → 4.0.0

package/README.md

@@ -20,7 +20,7 @@ or compatibility rules.
 - 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, 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
+- Cloud binding v3 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,9 @@ 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`, eighteen capability tokens, the exact ordinary Project/Git route catalog, bounded authority-transfer artifact routes, and six private-development bootstrap bindings. Wire v6 includes the additive Cloud Project-membership operation family while preserving every existing operation contract. The shared checkpoint container is exactly `checkpoint.json`, `coordination.ndjson`, and `repository.bundle`; authority-transfer and export retain wire-visible coordination format v1, while the pre-production offline backup contract is directly replaced by format v3. Backup v3 adds Project invitations, protected invitation and transferred-claim override envelopes, manager-responsibility offers, membership recovery journals, secret-replay tombstones, and compacted Manager-responsibility idempotency tombstones to the existing continuity records. Portable profiles exclude engine storage, paths, credentials, tokens, private keys, and operational refs, and backups exclude plaintext invitation secrets, 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.
+Cloud binding v3 retains the authority-neutral Project snapshot, nine redacted durable event kinds plus `snapshot.required`, eighteen capability tokens, the exact ordinary Project/Git route catalog, bounded authority-transfer artifact routes, and six private-development bootstrap bindings. Wire v7 adds the required logical Project generation, state-consistent imported-claim generation, and complete reissued-claim transfer identity to the existing Cloud Project-membership read contracts. The shared checkpoint container is exactly `checkpoint.json`, `coordination.ndjson`, and `repository.bundle`; authority-transfer and export use wire-visible coordination format v1, and offline backup uses format v3. Backup v3 adds Project invitations, protected invitation and transferred-claim override envelopes, manager-responsibility offers, membership recovery journals, secret-replay tombstones, and compacted Manager-responsibility idempotency tombstones to the existing continuity records. Portable profiles exclude engine storage, paths, credentials, tokens, private keys, and operational refs, and backups exclude plaintext invitation secrets, 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.
+
+Backup coordination artifacts are limited to 256 MiB of actual UTF-8 bytes, including the final newline. The decoder, encoder, and consistency checker apply this same inclusive limit without rewriting principals into an intermediate format. Valid current-format artifacts at the limit are accepted; an additional byte is rejected.
 
 ## Usage
 
@@ -62,31 +64,9 @@ part of the public surface.
 
 Package SemVer, canonical wire version, and Cloud binding version are independent concepts.
 
-- **Package version** (this `package.json`): `3.3.1`. 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. An independently
-  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. Package 3.3 adds the Cloud Project-membership
-  operation family and capability tokens and directly replaces the pre-production
-  offline backup contract with coordination format v3, without changing
-  authority-transfer/export format v1, canonical wire v6, or Cloud binding v2.
-  Backup v2 has no supported decoder or migration path. The pre-production
-  `3.3.1` corrective patch adds only the missing backup-v3 tombstone needed to
-  compact terminal Manager-responsibility offers and exact responses without
-  allowing their idempotency identities to be reused. 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 existing envelope, DTO, operation
-  payload shape, or operation definition is wire-breaking and requires a new
-  wire-protocol version. A strictly additive operation may remain on the
-  current wire version when the compatibility classifier proves that every
-  existing operation contract is unchanged.
-- **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.
+- **Package version** (this `package.json`): `4.0.0`. Behavior-preserving implementation refactors and reviewed compatible defect corrections may use a patch release when public declarations, runtime exports, and accepted wire/binding semantics remain unchanged. Minor releases may add backward-compatible API. Removing or incompatibly changing an existing declaration, export, runtime behavior, codec, error, limit, ref rule, operation, or compatibility rule requires a major release. Package API SemVer is classified independently from the wire and Cloud binding contracts, but a compatible package addition cannot exempt a changed wire contract from a wire-version increase or a changed Cloud binding contract from a binding-version increase. The package version never signals wire compatibility by itself.
+- **Wire version** (`COLLAB_PROTOCOL_VERSION`): currently `7`. The supported range is exactly `[7, 7]`. This is independent from Cloud binding version `3` and the existing application LAN control version `9`. Any change to an existing envelope, DTO, operation payload shape, or operation definition requires a new wire-protocol version. This includes additive operations: every wire-contract change increases the canonical wire version.
+- **Cloud binding version** (`COLLAB_CLOUD_BINDING_VERSION`): currently `3`. It versions Cloud routes, bounded transfer streams, and capabilities independently from package and wire versions. Every Cloud binding-contract change increases this version. Bindings before v3 and wire versions before v7 are unsupported rather than translated or dual-interpreted.
 
 ### Compatibility behavior
 
@@ -105,14 +85,18 @@ Compatibility is tested with executable fixtures in this package
 (`tests/`), and cross-repository contract fixtures pin client and server to
 the same behavior.
 
+The compatibility snapshot also fingerprints implementation tokens. Those fingerprints detect edits but cannot establish whether behavior changed. A reviewed implementation-only refactor or approved compatible defect correction uses `compatibility-review.json`, generated with `npm run check:compatibility -- --base <base-sha> --record-implementation-only-review "<reviewed reason>"` after updating the generated snapshot and characterizing the public seams. The reason distinguishes preserved behavior from any approved correction and its executable evidence. The record binds the exact base and candidate snapshots; the classifier independently rejects any changed public declaration, export, or wire/binding semantic fact. Missing or stale evidence cannot authorize an implementation change, and the record never applies to another version or later edit merely because an earlier change was accepted. This review requirement is general, not a prelaunch or one-release compatibility exception, and it is not an automated proof of behavioral equivalence.
+
 ## 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
+npm run release:candidate # build and verify the reviewed release artifact
+npm run verify:pack  # smoke-test that exact artifact in a clean consumer
 ```
 
 `dist/` is generated output and is never committed. The packed artifact is
 reproducible from source: `npm pack` rebuilds via `prepack`.
+The full verification gate constructs one release candidate and uses those same reviewed tarball bytes for clean-consumer smoke tests and publication.

package/dist/CollabCloudBinding.d.ts

@@ -2,7 +2,7 @@ import { COLLAB_PROTOCOL_VERSION } from './CollabConstants';
 import { CollabError, type CollabDiagnosticContext, type CollabErrorCode, type CollabRecoveryAction } from './CollabError';
 import { COLLAB_PROJECT_CHECKPOINT_ARTIFACTS } from './CollabProjectCheckpoint';
 import type { CollabIsoTimestamp, CollabProjectId } from './types';
-export declare const COLLAB_CLOUD_BINDING_VERSION: 2;
+export declare const COLLAB_CLOUD_BINDING_VERSION: 3;
 export declare const COLLAB_CLOUD_CAPABILITY_DOCUMENT_SCHEMA_VERSION: 2;
 export declare const COLLAB_CLOUD_CAPABILITIES: readonly ["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 type CollabCloudCapability = typeof COLLAB_CLOUD_CAPABILITIES[number];

package/dist/CollabCloudBinding.js

@@ -23,7 +23,7 @@ const CollabControlOperationCodecs_1 = require("./CollabControlOperationCodecs")
 const CollabError_1 = require("./CollabError");
 const CollabValidation_1 = require("./CollabValidation");
 const CollabProjectCheckpoint_1 = require("./CollabProjectCheckpoint");
-exports.COLLAB_CLOUD_BINDING_VERSION = 2;
+exports.COLLAB_CLOUD_BINDING_VERSION = 3;
 exports.COLLAB_CLOUD_CAPABILITY_DOCUMENT_SCHEMA_VERSION = 2;
 exports.COLLAB_CLOUD_CAPABILITIES = Object.freeze([
     'accept',
@@ -188,7 +188,7 @@ function collabCloudProjectOperationRoute(projectId, operation) {
     assertProjectId(projectId);
     if (!isCloudJsonOperation(operation))
         invalidRoute();
-    return route('POST', `/v2/projects/${projectId}/operations/${operation}`, {
+    return route('POST', `/v3/projects/${projectId}/operations/${operation}`, {
         kind: 'project-operation',
         operation,
         projectId,
@@ -198,7 +198,7 @@ function collabCloudProjectEventsRoute(projectId, afterSequence) {
     assertProjectId(projectId);
     if (!Number.isSafeInteger(afterSequence) || afterSequence < 0)
         invalidRoute();
-    return route('GET', `/v2/projects/${projectId}/events?afterSequence=${afterSequence}`, {
+    return route('GET', `/v3/projects/${projectId}/events?afterSequence=${afterSequence}`, {
         afterSequence,
         kind: 'project-events',
         projectId,
@@ -209,11 +209,11 @@ function collabCloudGitRoute(projectId, routeKind, service) {
     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 });
+        return route('GET', `/v3/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}`, {
+    return route('POST', `/v3/projects/${projectId}/repository.git/${routeKind}`, {
         kind: routeKind,
         projectId,
     });
@@ -224,7 +224,7 @@ function collabCloudAuthorityTransferArtifactRoute(projectId, transferId, direct
     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}`, {
+    return route(direction === 'upload' ? 'PUT' : 'GET', `/v3/projects/${projectId}/authority-transfers/${transferId}/checkpoint/${artifact}`, {
         artifact,
         direction,
         kind: 'authority-transfer-artifact',
@@ -237,7 +237,7 @@ function collabCloudProjectCheckpointExportArtifactRoute(projectId, exportId, ar
     assertAttemptId(exportId);
     if (!COLLAB_PROJECT_CHECKPOINT_ARTIFACTS_SET.has(artifact))
         invalidRoute();
-    return route('GET', `/v2/projects/${projectId}/checkpoint-exports/${exportId}/checkpoint/${artifact}`, {
+    return route('GET', `/v3/projects/${projectId}/checkpoint-exports/${exportId}/checkpoint/${artifact}`, {
         artifact,
         exportId,
         kind: 'project-checkpoint-export-artifact',
@@ -249,7 +249,7 @@ function collabCloudProjectCheckpointExportRoute(projectId, exportId, operation)
     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 });
+    return route(operation === 'begin' ? 'POST' : 'GET', `/v3/projects/${projectId}/checkpoint-exports/${exportId}`, { exportId, kind: 'project-checkpoint-export', operation, projectId });
 }
 function decodeCollabCloudProjectCheckpointExportStatus(value) {
     const source = exactRecord(value, 'checkpointExport', [
@@ -287,7 +287,7 @@ function decodeCollabCloudProjectCheckpointExportStatus(value) {
     });
 }
 function collabDevelopmentBootstrapRoute(operation, attemptId) {
-    const base = '/v2/development/bootstrap/attempts';
+    const base = '/v3/development/bootstrap/attempts';
     if (operation === 'beginDevelopmentBootstrap') {
         if (attemptId !== undefined)
             invalidRoute();
@@ -346,7 +346,7 @@ function matchCollabCloudRoute(method, target) {
         && url.pathname === '/collab/capabilities'
         && exactQuery(url, []))
         return { kind: 'capabilities' };
-    if (segments[0] === 'v2'
+    if (segments[0] === 'v3'
         && segments[1] === 'projects'
         && (0, CollabValidation_1.isCollabProjectId)(segments[2])) {
         const projectId = segments[2];
@@ -425,7 +425,7 @@ function matchCollabCloudRoute(method, target) {
             && exactQuery(url, []))
             return { kind: segments[4], projectId };
     }
-    if (segments[0] !== 'v2'
+    if (segments[0] !== 'v3'
         || segments[1] !== 'development'
         || segments[2] !== 'bootstrap'
         || segments[3] !== 'attempts'

package/dist/CollabCloudProjectSnapshot.d.ts

@@ -2,6 +2,7 @@ import { COLLAB_MAIN_REF } from './CollabConstants';
 import type { CollabDecodeResult } from './CollabProtocol';
 import type { CollabChangeRequest, CollabGitOid, CollabIsoTimestamp, CollabMemberId, CollabProjectId, CollabRole, CollabTicketSummary } from './types';
 export interface CollabCloudProjectSummary {
+    readonly authorityGeneration: number;
     readonly createdAt: CollabIsoTimestamp;
     readonly expectedMainOid: CollabGitOid;
     readonly id: CollabProjectId;

package/dist/CollabCloudProjectSnapshot.js

@@ -67,6 +67,7 @@ function positiveInteger(source, field) {
 }
 function decodeProject(value) {
     const source = exactRecord(value, 'project', [
+        'authorityGeneration',
         'createdAt',
         'expectedMainOid',
         'id',
@@ -76,6 +77,7 @@ function decodeProject(value) {
     if (source.mainRef !== CollabConstants_1.COLLAB_MAIN_REF)
         throw invalidPayload('mainRef');
     return {
+        authorityGeneration: positiveInteger(source, 'authorityGeneration'),
         createdAt: timestamp(source, 'createdAt'),
         expectedMainOid: stringField(source, 'expectedMainOid', 64, CollabValidation_1.isCollabGitOid),
         id: stringField(source, 'id', 64, CollabValidation_1.isCollabProjectId),

package/dist/CollabConstants.d.ts

@@ -1,4 +1,4 @@
-export declare const COLLAB_PROTOCOL_VERSION: 6;
+export declare const COLLAB_PROTOCOL_VERSION: 7;
 export declare const COLLAB_MAIN_REF: "refs/heads/main";
 export declare const COLLAB_MEMBER_REF_PREFIX: "refs/heads/members/";
 export declare const COLLAB_LIMITS: Readonly<{

package/dist/CollabConstants.js

@@ -1,7 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.COLLAB_LIMITS = exports.COLLAB_MEMBER_REF_PREFIX = exports.COLLAB_MAIN_REF = exports.COLLAB_PROTOCOL_VERSION = void 0;
-exports.COLLAB_PROTOCOL_VERSION = 6;
+exports.COLLAB_PROTOCOL_VERSION = 7;
 exports.COLLAB_MAIN_REF = 'refs/heads/main';
 exports.COLLAB_MEMBER_REF_PREFIX = 'refs/heads/members/';
 exports.COLLAB_LIMITS = Object.freeze({

package/dist/CollabProjectBackupCheckpoint.js

@@ -208,65 +208,19 @@ function absoluteTargetUrl(source) {
 function principal(source, field) {
     return token(source, field, value => (typeof value === 'string' && PRINCIPAL_PATTERN.test(value)));
 }
-function sanitizeBackupBasePrincipalRecord(item) {
-    const source = record(item, 'record');
-    const value = record(source.value, 'value');
-    if (source.kind === 'principal-binding') {
-        return {
-            ...source,
-            value: { ...value, principalId: `principal_${String(value.memberId)}` },
-        };
-    }
-    if (source.kind === 'terminal-responder' && Array.isArray(value.acknowledgements)) {
-        return {
-            ...source,
-            value: {
-                ...value,
-                acknowledgements: value.acknowledgements.map(item => ({
-                    ...record(item, 'acknowledgement'),
-                    principalId: `principal_${String(record(item, 'acknowledgement').memberId)}`,
-                })),
-            },
-        };
-    }
-    return item;
-}
-function restoreBackupBasePrincipals(source, base) {
-    if (base.kind === 'principal-binding') {
-        const value = exactRecord(source.value, 'value', [
-            'boundAt', 'memberId', 'principalId', 'projectId',
-        ]);
-        return {
-            ...base,
-            value: { ...base.value, principalId: principal(value, 'principalId') },
-        };
-    }
+function validateBackupBasePrincipals(base) {
+    if (base.kind === 'principal-binding')
+        principal(base.value, 'principalId');
     if (base.kind === 'terminal-responder') {
-        const value = exactRecord(source.value, 'value', [
-            'acknowledgements',
-            'eligibleMemberIds',
-            'expiresAt',
-            'operation',
-            'operationId',
-            'projectId',
-            'responseJson',
-        ]);
-        const sourceAcknowledgements = value.acknowledgements;
-        if (!Array.isArray(sourceAcknowledgements)
-            || sourceAcknowledgements.length !== base.value.acknowledgements.length)
-            throw invalidPayload('acknowledgements');
-        const acknowledgements = base.value.acknowledgements.map((item, index) => {
-            const original = exactRecord(sourceAcknowledgements[index], 'acknowledgement', [
-                'acknowledgedAt', 'memberId', 'principalId',
-            ]);
-            return { ...item, principalId: principal(original, 'principalId') };
-        });
-        if (new Set(acknowledgements.map(item => item.principalId)).size !== acknowledgements.length) {
-            throw invalidPayload('acknowledgements');
+        for (const acknowledgement of base.value.acknowledgements) {
+            if (acknowledgement.principalId === undefined)
+                throw invalidPayload('acknowledgement');
+            principal(acknowledgement, 'principalId');
         }
-        return { ...base, value: { ...base.value, acknowledgements } };
+        if (new Set(base.value.acknowledgements.map(item => item.principalId)).size
+            !== base.value.acknowledgements.length)
+            throw invalidPayload('acknowledgements');
     }
-    return base;
 }
 function repositoryPublicationRef(value) {
     const source = exactRecord(value, 'ref', ['name', 'oid']);
@@ -2010,55 +1964,18 @@ function validateContinuity(records) {
         }
     }
 }
-function manifestWithFormatOne(value) {
+function decodeCollabProjectBackupCheckpointManifest(value) {
     const source = record(value, 'manifest');
     if (source.profile !== 'backup'
         || source.coordinationFormatVersion !== exports.COLLAB_PROJECT_BACKUP_COORDINATION_FORMAT_VERSION)
         throw invalidPayload('manifest');
-    return (0, CollabProjectCheckpoint_1.decodeCollabProjectCheckpointManifest)({
-        ...source,
-        coordinationFormatVersion: CollabProjectCheckpoint_1.COLLAB_PROJECT_COORDINATION_FORMAT_VERSION,
-    });
-}
-function decodeCollabProjectBackupCheckpointManifest(value) {
-    const decoded = manifestWithFormatOne(value);
-    return {
-        artifacts: decoded.artifacts,
-        coordinationFormatVersion: exports.COLLAB_PROJECT_BACKUP_COORDINATION_FORMAT_VERSION,
-        createdAt: decoded.createdAt,
-        expectedMainOid: decoded.expectedMainOid,
-        gitObjectFormat: decoded.gitObjectFormat,
-        manifestSchemaVersion: decoded.manifestSchemaVersion,
-        manifestSha256: decoded.manifestSha256,
-        operationId: decoded.operationId,
-        profile: 'backup',
-        projectId: decoded.projectId,
-        protocolVersion: decoded.protocolVersion,
-        refs: decoded.refs,
-        sourceAuthority: decoded.sourceAuthority,
-        targetAuthority: decoded.targetAuthority,
-    };
+    return (0, CollabProjectCheckpoint_1.decodeCheckpointManifestFields)(source, exports.COLLAB_PROJECT_BACKUP_COORDINATION_FORMAT_VERSION);
 }
 function encodeCollabProjectBackupCheckpointManifestCanonicalJson(manifest) {
     return JSON.stringify(decodeCollabProjectBackupCheckpointManifest(manifest));
 }
 function encodeCollabProjectBackupCheckpointManifestDigestInput(manifest) {
-    const decoded = decodeCollabProjectBackupCheckpointManifest(manifest);
-    return JSON.stringify({
-        artifacts: decoded.artifacts,
-        coordinationFormatVersion: decoded.coordinationFormatVersion,
-        createdAt: decoded.createdAt,
-        expectedMainOid: decoded.expectedMainOid,
-        gitObjectFormat: decoded.gitObjectFormat,
-        manifestSchemaVersion: decoded.manifestSchemaVersion,
-        operationId: decoded.operationId,
-        profile: decoded.profile,
-        projectId: decoded.projectId,
-        protocolVersion: decoded.protocolVersion,
-        refs: decoded.refs,
-        sourceAuthority: decoded.sourceAuthority,
-        targetAuthority: decoded.targetAuthority,
-    });
+    return (0, CollabProjectCheckpoint_1.encodeCheckpointManifestDigestInput)(decodeCollabProjectBackupCheckpointManifest(manifest));
 }
 function decodeCollabProjectBackupCheckpointCoordinationNdjson(value) {
     if (typeof value !== 'string'
@@ -2078,22 +1995,43 @@ function decodeCollabProjectBackupCheckpointCoordinationNdjson(value) {
         }
         if (JSON.stringify(item) !== line)
             throw invalidPayload('coordination');
-        return { envelope: recordEnvelope(item), item };
+        return {
+            envelope: recordEnvelope(item),
+            item,
+            base: undefined,
+        };
     });
     const baseItems = parsed.filter(({ envelope }) => (!CONTINUITY_KIND_SET.has(envelope.kind) && envelope.kind !== 'idempotency-result'));
-    const baseDecoded = (0, CollabProjectCheckpoint_1.decodeCollabProjectCheckpointCoordinationNdjson)(baseItems.map(({ item }) => JSON.stringify(sanitizeBackupBasePrincipalRecord(item))).join('\n') + '\n', 'backup');
-    const baseByIdentity = new Map(baseDecoded.map(item => [`${item.kind}\0${item.recordId}`, item]));
-    const decoded = parsed.map(({ envelope }) => {
+    for (const { envelope } of baseItems) {
+        const value = record(envelope.source.value, 'value');
+        if (envelope.kind === 'terminal-responder' && Array.isArray(value.acknowledgements)) {
+            for (const acknowledgement of value.acknowledgements)
+                record(acknowledgement, 'acknowledgement');
+        }
+    }
+    const baseRecords = [];
+    for (const entry of baseItems) {
+        entry.base = (0, CollabProjectCheckpoint_1.decodeCheckpointRecord)(entry.item, 'deferred');
+        if (JSON.stringify(entry.base) !== JSON.stringify(entry.item)
+            || (entry.base.kind === 'principal-binding' && entry.base.value.principalId === undefined)) {
+            throw invalidPayload('coordination');
+        }
+        baseRecords.push(entry.base);
+    }
+    if (baseRecords.length === 0)
+        throw invalidPayload('coordination');
+    (0, CollabProjectCheckpoint_1.validateCheckpointRecordSequence)(baseRecords, 'backup', 'member');
+    const decoded = parsed.map(({ envelope, base }) => {
         if (envelope.kind === 'idempotency-result') {
             return idempotencyResultRecord(envelope.source, envelope.recordId, envelope.revision);
         }
         if (CONTINUITY_KIND_SET.has(envelope.kind)) {
             return decodeContinuityRecord(envelope.kind, envelope.source, envelope.recordId, envelope.revision);
         }
-        const base = baseByIdentity.get(`${envelope.kind}\0${envelope.recordId}`);
         if (base === undefined)
             throw invalidPayload('records');
-        return restoreBackupBasePrincipals(envelope.source, base);
+        validateBackupBasePrincipals(base);
+        return base;
     });
     if (decoded.some((item, index) => JSON.stringify(item) !== lines[index])) {
         throw invalidPayload('coordination');
@@ -2157,9 +2095,7 @@ function validateCollabProjectBackupCheckpointConsistency(manifest, records) {
     }))
         throw invalidPayload('records');
     const baseRecords = decodedRecords.filter(item => (!CONTINUITY_KIND_SET.has(item.kind) && item.kind !== 'idempotency-result'));
-    (0, CollabProjectCheckpoint_1.validateCollabProjectCheckpointConsistency)((0, CollabProjectCheckpoint_1.decodeCollabProjectCheckpointManifest)({
-        ...decodedManifest,
-        coordinationFormatVersion: CollabProjectCheckpoint_1.COLLAB_PROJECT_COORDINATION_FORMAT_VERSION,
-    }), baseRecords);
+    (0, CollabProjectCheckpoint_1.validateCheckpointRecordSequence)(baseRecords, 'backup');
+    (0, CollabProjectCheckpoint_1.validateCheckpointManifestConsistency)(decodedManifest, baseRecords);
     return records;
 }

package/dist/CollabProjectCheckpoint.d.ts

@@ -265,11 +265,36 @@ export type CollabCheckpointAuthorityVolumePairRecord = CollabCheckpointRecordBa
 }>;
 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;
+type ParsedCheckpointPrincipalBindingRecord = CollabCheckpointRecordBase<'principal-binding', Omit<CollabCheckpointPrincipalBindingRecord['value'], 'principalId'> & {
+    readonly principalId: unknown;
+}>;
+type ParsedCheckpointTerminalResponderRecord = CollabCheckpointRecordBase<'terminal-responder', Omit<CollabCheckpointTerminalResponderRecord['value'], 'acknowledgements'> & {
+    readonly acknowledgements: readonly (Omit<CollabCheckpointTerminalAcknowledgement, 'principalId'> & {
+        readonly principalId: unknown;
+    })[];
+}>;
+/** @internal Format v3 validates principal fields after the shared base-record phase. */
+export type ParsedCheckpointRecord = Exclude<CollabCheckpointBackupRecord, CollabCheckpointPrincipalBindingRecord | CollabCheckpointTerminalResponderRecord> | ParsedCheckpointPrincipalBindingRecord | ParsedCheckpointTerminalResponderRecord;
+type CheckpointManifestFields<CoordinationVersion extends number> = Omit<CollabProjectCheckpointManifest, 'coordinationFormatVersion'> & {
+    readonly coordinationFormatVersion: CoordinationVersion;
+};
+/** @internal Shared field validation; public entry points select their own format. */
+export declare function decodeCheckpointManifestFields<CoordinationVersion extends number>(value: unknown, coordinationFormatVersion: CoordinationVersion): CheckpointManifestFields<CoordinationVersion>;
 export declare function decodeCollabProjectCheckpointManifest(value: unknown): CollabProjectCheckpointManifest;
 export declare function encodeCollabProjectCheckpointManifestCanonicalJson(manifest: CollabProjectCheckpointManifest): string;
 export declare function encodeCollabProjectCheckpointManifestDigestInput(manifest: CollabProjectCheckpointManifest): string;
+/** @internal Encode already validated fields without changing their format. */
+export declare function encodeCheckpointManifestDigestInput(decoded: CheckpointManifestFields<number>): string;
 export declare function encodeCollabProtectedClaimAssociatedData(associatedData: CollabProtectedClaimAssociatedData): string;
+/** @internal Public v1 decoding validates principals in each record. */
+export declare function decodeCheckpointRecord(value: unknown): CollabCheckpointBackupRecord;
+/** @internal Offline v3 decoding validates principals after the base-record sequence. */
+export declare function decodeCheckpointRecord(value: unknown, principalPhase: 'deferred'): ParsedCheckpointRecord;
+/** @internal V3 decoding checks terminal principals separately; consistency binds current principals. */
+export declare function validateCheckpointRecordSequence(records: readonly ParsedCheckpointRecord[], profile: CollabCheckpointProfile, acknowledgementBinding?: 'current-principal' | 'member'): void;
 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[];
+/** @internal Cross-artifact checks operate on validated fields, not another format. */
+export declare function validateCheckpointManifestConsistency(decodedManifest: CheckpointManifestFields<number>, records: readonly CollabCheckpointBackupRecord[]): readonly CollabCheckpointBackupRecord[];
 export {};