@claudian-collab/protocol 3.3.1 → 4.0.0

package/dist/esm/CollabProjectCheckpoint.mjs

@@ -227,7 +227,7 @@ function gitRefs(value, expectedMainOid) {
         throw invalidPayload('refs');
     return Object.freeze(decoded);
 }
-function manifestObject(source, includeManifestSha256) {
+function manifestObject(source, coordinationFormatVersion) {
     const profile = literal(source, 'profile', COLLAB_CHECKPOINT_PROFILES);
     const expectedMainOid = token(source, 'expectedMainOid', isCollabGitOid);
     const gitObjectFormat = literal(source, 'gitObjectFormat', ['sha1', 'sha256']);
@@ -263,15 +263,13 @@ function manifestObject(source, includeManifestSha256) {
         sourceAuthority,
         targetAuthority,
     };
-    if (common.coordinationFormatVersion !== COLLAB_PROJECT_COORDINATION_FORMAT_VERSION
+    if (common.coordinationFormatVersion !== coordinationFormatVersion
         || common.manifestSchemaVersion !== COLLAB_PROJECT_CHECKPOINT_MANIFEST_SCHEMA_VERSION
         || common.protocolVersion !== COLLAB_PROTOCOL_VERSION)
         throw invalidPayload('manifest');
-    if (!includeManifestSha256)
-        return common;
     return {
         artifacts: common.artifacts,
-        coordinationFormatVersion: COLLAB_PROJECT_COORDINATION_FORMAT_VERSION,
+        coordinationFormatVersion,
         createdAt: common.createdAt,
         expectedMainOid: common.expectedMainOid,
         gitObjectFormat: common.gitObjectFormat,
@@ -286,7 +284,8 @@ function manifestObject(source, includeManifestSha256) {
         targetAuthority: common.targetAuthority,
     };
 }
-export function decodeCollabProjectCheckpointManifest(value) {
+/** @internal Shared field validation; public entry points select their own format. */
+export function decodeCheckpointManifestFields(value, coordinationFormatVersion) {
     const source = exactRecord(value, 'manifest', [
         'artifacts',
         'coordinationFormatVersion',
@@ -303,18 +302,24 @@ export function decodeCollabProjectCheckpointManifest(value) {
         'sourceAuthority',
         'targetAuthority',
     ]);
-    const decoded = manifestObject(source, true);
+    const decoded = manifestObject(source, coordinationFormatVersion);
     const encoded = JSON.stringify(decoded);
     if (!hasUtf8ByteLengthAtMost(encoded, COLLAB_CHECKPOINT_ARTIFACT_LIMITS.maxManifestBytes)) {
         throw invalidPayload('manifest');
     }
     return decoded;
 }
+export function decodeCollabProjectCheckpointManifest(value) {
+    return decodeCheckpointManifestFields(value, COLLAB_PROJECT_COORDINATION_FORMAT_VERSION);
+}
 export function encodeCollabProjectCheckpointManifestCanonicalJson(manifest) {
     return JSON.stringify(decodeCollabProjectCheckpointManifest(manifest));
 }
 export function encodeCollabProjectCheckpointManifestDigestInput(manifest) {
-    const decoded = decodeCollabProjectCheckpointManifest(manifest);
+    return encodeCheckpointManifestDigestInput(decodeCollabProjectCheckpointManifest(manifest));
+}
+/** @internal Encode already validated fields without changing their format. */
+export function encodeCheckpointManifestDigestInput(decoded) {
     const source = {
         artifacts: decoded.artifacts,
         coordinationFormatVersion: decoded.coordinationFormatVersion,
@@ -697,13 +702,13 @@ function idempotencyResultRecord(source, recordId, revision) {
         },
     };
 }
-function principalBindingRecord(source, recordId, revision) {
-    const value = exactRecord(source.value, 'value', [
+function principalBindingRecord(source, recordId, revision, deferPrincipals) {
+    const value = principalRecord(source.value, 'value', [
         'boundAt',
         'memberId',
         'principalId',
         'projectId',
-    ]);
+    ], deferPrincipals);
     const memberId = token(value, 'memberId', isCollabMemberId);
     if (recordId !== memberId)
         throw invalidPayload('recordId');
@@ -714,7 +719,7 @@ function principalBindingRecord(source, recordId, revision) {
         value: {
             boundAt: timestamp(value, 'boundAt'),
             memberId,
-            principalId: token(value, 'principalId'),
+            principalId: deferPrincipals ? value.principalId : token(value, 'principalId'),
             projectId: token(value, 'projectId', isCollabProjectId),
         },
     };
@@ -848,7 +853,13 @@ function lifecycleStateRecord(source, recordId, revision) {
         value: internalState,
     };
 }
-function terminalResponderRecord(source, recordId, revision) {
+function principalRecord(value, field, keys, deferPrincipals) {
+    const source = record(value, field);
+    return exactRecord(source, field, deferPrincipals && !Object.hasOwn(source, 'principalId')
+        ? keys.filter(key => key !== 'principalId')
+        : keys);
+}
+function terminalResponderRecord(source, recordId, revision, deferPrincipals) {
     const value = exactRecord(source.value, 'value', [
         'acknowledgements',
         'eligibleMemberIds',
@@ -900,22 +911,24 @@ function terminalResponderRecord(source, recordId, revision) {
     if (!Array.isArray(value.acknowledgements))
         throw invalidPayload('acknowledgements');
     const acknowledgements = value.acknowledgements.map((item) => {
-        const acknowledgement = exactRecord(item, 'acknowledgement', [
+        const acknowledgement = principalRecord(item, 'acknowledgement', [
             'acknowledgedAt',
             'memberId',
             'principalId',
-        ]);
+        ], deferPrincipals);
         return {
             acknowledgedAt: timestamp(acknowledgement, 'acknowledgedAt'),
             memberId: token(acknowledgement, 'memberId', isCollabMemberId),
-            principalId: token(acknowledgement, 'principalId'),
+            principalId: deferPrincipals
+                ? acknowledgement.principalId
+                : token(acknowledgement, 'principalId'),
         };
     });
     const acknowledgementPrincipals = new Set();
     acknowledgements.forEach((item, index) => {
         if (!eligibleMemberIds.includes(item.memberId)
             || (index > 0 && acknowledgements[index - 1].memberId.localeCompare(item.memberId, 'en-US') >= 0)
-            || acknowledgementPrincipals.has(item.principalId))
+            || (!deferPrincipals && acknowledgementPrincipals.has(item.principalId)))
             throw invalidPayload('acknowledgements');
         acknowledgementPrincipals.add(item.principalId);
     });
@@ -924,7 +937,7 @@ function terminalResponderRecord(source, recordId, revision) {
         recordId,
         revision,
         value: {
-            acknowledgements: Object.freeze(acknowledgements),
+            acknowledgements,
             eligibleMemberIds: Object.freeze(eligibleMemberIds),
             expiresAt,
             operation,
@@ -1097,8 +1110,9 @@ function authorityVolumePairRecord(source, recordId, revision) {
         },
     };
 }
-function decodeCheckpointRecord(value) {
+export function decodeCheckpointRecord(value, principalPhase) {
     const { kind, recordId, revision, source } = recordEnvelope(value);
+    const deferPrincipals = principalPhase === 'deferred';
     switch (kind) {
         case 'project': return projectRecord(source, recordId, revision);
         case 'member': return memberRecord(source, recordId, revision);
@@ -1111,10 +1125,12 @@ function decodeCheckpointRecord(value) {
         case 'cloud-event': return cloudEventRecord(source, recordId, revision);
         case 'cloud-event-cursor': return cloudEventCursorRecord(source, recordId, revision);
         case 'idempotency-result': return idempotencyResultRecord(source, recordId, revision);
-        case 'principal-binding': return principalBindingRecord(source, recordId, revision);
+        case 'principal-binding':
+            return principalBindingRecord(source, recordId, revision, deferPrincipals);
         case 'repository-placement': return repositoryPlacementRecord(source, recordId, revision);
         case 'lifecycle-state': return lifecycleStateRecord(source, recordId, revision);
-        case 'terminal-responder': return terminalResponderRecord(source, recordId, revision);
+        case 'terminal-responder':
+            return terminalResponderRecord(source, recordId, revision, deferPrincipals);
         case 'protected-claim-envelope':
             return protectedClaimEnvelopeRecord(source, recordId, revision);
         case 'tombstone': return tombstoneRecord(source, recordId, revision);
@@ -1130,7 +1146,8 @@ function compareRecords(left, right) {
     const kindOrder = recordKindOrder(left.kind) - recordKindOrder(right.kind);
     return kindOrder !== 0 ? kindOrder : left.recordId.localeCompare(right.recordId, 'en-US');
 }
-function validateRecordSequence(records, profile) {
+/** @internal V3 decoding checks terminal principals separately; consistency binds current principals. */
+export function validateCheckpointRecordSequence(records, profile, acknowledgementBinding = 'current-principal') {
     if (records.length === 0 || records[0].kind !== 'project')
         throw invalidPayload('records');
     const projectId = records[0].recordId;
@@ -1233,7 +1250,9 @@ function validateRecordSequence(records, profile) {
             throw invalidPayload('records');
         }
         if (item.kind === 'terminal-responder' && (item.value.eligibleMemberIds.some(memberId => !members.has(memberId))
-            || item.value.acknowledgements.some(acknowledgement => (principalBindings.get(acknowledgement.memberId) !== acknowledgement.principalId))))
+            || item.value.acknowledgements.some(acknowledgement => (acknowledgementBinding === 'current-principal'
+                ? principalBindings.get(acknowledgement.memberId) !== acknowledgement.principalId
+                : !principalBindings.has(acknowledgement.memberId)))))
             throw invalidPayload('records');
     }
     if (profile === 'backup') {
@@ -1260,11 +1279,13 @@ export function decodeCollabProjectCheckpointCoordinationNdjson(value, profile)
             throw invalidPayload('coordination');
         }
         const result = decodeCheckpointRecord(parsed);
+        if (result.kind === 'terminal-responder')
+            Object.freeze(result.value.acknowledgements);
         if (JSON.stringify(result) !== line)
             throw invalidPayload('coordination');
         return result;
     });
-    validateRecordSequence(decoded, profile);
+    validateCheckpointRecordSequence(decoded, profile);
     return Object.freeze(decoded);
 }
 export function encodeCollabProjectCheckpointCoordinationNdjson(records, profile) {
@@ -1296,7 +1317,11 @@ function checkpointRecordGitOids(checkpointRecord) {
 }
 export function validateCollabProjectCheckpointConsistency(manifest, records) {
     const decodedManifest = decodeCollabProjectCheckpointManifest(manifest);
-    validateRecordSequence(records, decodedManifest.profile);
+    validateCheckpointRecordSequence(records, decodedManifest.profile);
+    return validateCheckpointManifestConsistency(decodedManifest, records);
+}
+/** @internal Cross-artifact checks operate on validated fields, not another format. */
+export function validateCheckpointManifestConsistency(decodedManifest, records) {
     const project = records[0];
     if (project.kind !== 'project'
         || project.value.projectId !== decodedManifest.projectId

package/dist/esm/CollabProjectMembership.mjs

@@ -333,23 +333,37 @@ function decodeMemberSummary(value) {
     const source = exactRecord(value, 'member', [
         'bindingState',
         'displayName',
+        'importedClaimGeneration',
         'importedClaimState',
         'memberId',
         'membershipRevision',
         'role',
     ]);
+    const importedClaimState = literal(source, 'importedClaimState', [
+        'not-applicable',
+        'original-active',
+        'override-active',
+        'revoked',
+        'expired',
+        'redeemed',
+        'hidden',
+    ]);
+    const importedClaimGeneration = source.importedClaimGeneration === null
+        ? null
+        : nonNegativeInteger(source, 'importedClaimGeneration');
+    if (importedClaimState === 'hidden' || importedClaimState === 'not-applicable') {
+        if (importedClaimGeneration !== null)
+            throw invalidPayload('importedClaimGeneration');
+    }
+    else if (importedClaimGeneration === null
+        || (importedClaimState === 'original-active' && importedClaimGeneration !== 0)
+        || (importedClaimState === 'override-active' && importedClaimGeneration === 0))
+        throw invalidPayload('importedClaimGeneration');
     return {
         bindingState: literal(source, 'bindingState', ['bound', 'unbound', 'hidden']),
         displayName: boundedText(source, 'displayName', COLLAB_PROJECT_MEMBERSHIP_LIMITS.maxDisplayNameUtf8Bytes),
-        importedClaimState: literal(source, 'importedClaimState', [
-            'not-applicable',
-            'original-active',
-            'override-active',
-            'revoked',
-            'expired',
-            'redeemed',
-            'hidden',
-        ]),
+        importedClaimGeneration,
+        importedClaimState,
         memberId: token(source, 'memberId', isCollabMemberId),
         membershipRevision: positiveInteger(source, 'membershipRevision'),
         role: literal(source, 'role', ['manager', 'member']),
@@ -396,6 +410,8 @@ function decodeReissueClaimResponse(value) {
         'memberId',
         'projectId',
         'secretReplayExpiresAt',
+        'targetAuthorityGeneration',
+        'transferId',
     ]);
     const createdAt = timestamp(source, 'createdAt');
     const expiresAt = timestamp(source, 'expiresAt');
@@ -411,6 +427,8 @@ function decodeReissueClaimResponse(value) {
         memberId: token(source, 'memberId', isCollabMemberId),
         projectId: token(source, 'projectId', isCollabProjectId),
         secretReplayExpiresAt,
+        targetAuthorityGeneration: positiveInteger(source, 'targetAuthorityGeneration'),
+        transferId: token(source, 'transferId'),
     };
 }
 function decodeRevokeClaimResponse(value) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@claudian-collab/protocol",
-  "version": "3.3.1",
+  "version": "4.0.0",
   "description": "Canonical Collab wire and Cloud binding contract for Claudian clients and servers.",
   "license": "MIT",
   "repository": {
@@ -46,7 +46,7 @@
     "release:candidate": "node scripts/release-candidate.mjs --output .context/release",
     "test": "jest && node --test tests/*.test.mjs",
     "typecheck": "tsc --noEmit -p tsconfig.jest.json",
-    "verify": "npm run lint && npm run typecheck && npm run build && npm run test && npm run check:compatibility && npm run check:migration-provenance && npm run verify:pack && npm run release:candidate",
+    "verify": "npm run lint && npm run typecheck && npm run release:candidate && npm run test && npm run check:compatibility && npm run check:migration-provenance && npm run verify:pack",
     "verify:pack": "node scripts/verify-pack.mjs"
   },
   "dependencies": {