@simplexable/kc2-client 0.3.0 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplexable/kc2-client",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Host-neutral KC2 contracts for platform integrations.",
   "main": "./src/index.js",
   "type": "commonjs",
@@ -20,9 +20,11 @@
     "./reconciliation/kc2ReconciliationStageContracts": "./src/reconciliation/kc2ReconciliationStageContracts.js",
     "./reconciliation/kc2ReconciliationContract": "./src/reconciliation/kc2ReconciliationContract.js",
     "./reconciliation/stageArtifactEnvelope": "./src/reconciliation/stageArtifactEnvelope.js",
+    "./authority/authorityDecisionContract": "./src/authority/authorityDecisionContract.js",
     "./authority/authorityContracts": "./src/authority/authorityContracts.js",
     "./authority/humanGuidanceContracts": "./src/authority/humanGuidanceContracts.js",
     "./authority/authorityDispositionContracts": "./src/authority/authorityDispositionContracts.js",
+    "./protectedContent/protectedContentReadinessContract": "./src/protectedContent/protectedContentReadinessContract.js",
     "./persistence/kc2WireOperationContracts": "./src/persistence/kc2WireOperationContracts.js",
     "./persistence/kc2GenerationSnapshotPersistenceContract": "./src/persistence/kc2GenerationSnapshotPersistenceContract.js",
     "./persistence/kc2HumanAuthorityReadContract": "./src/persistence/kc2HumanAuthorityReadContract.js",

package/src/authority/authorityDecisionContract.js

@@ -0,0 +1,402 @@
+'use strict';
+
+const {
+  AUTHORITY_DISPOSITION,
+  AUTHORITY_OVERALL_OUTCOME,
+} = require('./authorityContracts');
+const { AUTHORITY_CONFLICT_KIND } = require('./authorityDispositionContracts');
+
+const CONTRACT_VERSION = 'authority-decision.v1';
+const DISPOSITION_REPORT_VERSION = 'kc2-human-authority-disposition.v1';
+const OPERATION = 'authority-decision';
+const MAX_STRING_LENGTH = 512;
+const MAX_ARRAY_LENGTH = 64;
+const MAX_VIOLATIONS = 64;
+const MAX_REASONS = 16;
+
+const ERROR_CATEGORIES = Object.freeze([
+  'invalid-payload',
+  'unauthorized',
+  'unavailable',
+  'unsupported-operation',
+  'semantic-failure',
+]);
+const ERROR_CODES = Object.freeze([
+  'invalid-payload',
+  'unauthorized',
+  'provider-unavailable',
+  'unsupported-operation',
+  'semantic-failure',
+]);
+const CONFLICT_KINDS = Object.freeze(Object.values(AUTHORITY_CONFLICT_KIND));
+const POTENTIAL_CONFLICT_KIND = 'potential-human-authority-conflict';
+const POTENTIAL_CONFLICT_KINDS = Object.freeze([...CONFLICT_KINDS, POTENTIAL_CONFLICT_KIND]);
+const CURRENTNESS_REASON_CODES = Object.freeze([
+  'authority-context-fingerprint-changed',
+  'evidence-fingerprint-changed',
+  'policy-version-changed',
+  'authority-fingerprint-unavailable',
+]);
+const FINGERPRINT_KEYS = Object.freeze(['authorityContext', 'evidence', 'policyVersion']);
+const ACTIVE_RECORD_SECTIONS = Object.freeze([
+  'domainAssertions',
+  'authoringGuidance',
+  'addenda',
+  'protectedOverrides',
+]);
+const DISPOSITION_ENTRY_ID_FIELDS = Object.freeze({
+  addenda: 'addendumId',
+  authoringGuidance: 'guidanceId',
+  domainAssertions: 'assertionId',
+  protectedOverrides: 'protectionId',
+});
+
+function contractError(message) {
+  const error = new TypeError(message);
+  error.code = 'invalid-payload';
+  return error;
+}
+
+function assertPlainObject(value, label) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw contractError(`${label} must be an object`);
+  }
+}
+
+function assertNoUnknownKeys(value, allowed, label) {
+  for (const key of Object.keys(value)) {
+    if (!allowed.includes(key)) throw contractError(`${label}.${key} is not supported`);
+  }
+}
+
+function assertString(value, label, { nullable = false } = {}) {
+  if (nullable && value === null) return;
+  if (typeof value !== 'string' || value.length === 0 || value.length > MAX_STRING_LENGTH) {
+    throw contractError(`${label} must be a bounded non-empty string${nullable ? ' or null' : ''}`);
+  }
+}
+
+function assertNullableString(value, label) {
+  assertString(value, label, { nullable: true });
+}
+
+function assertNullableBoolean(value, label) {
+  if (value !== null && typeof value !== 'boolean') throw contractError(`${label} must be boolean or null`);
+}
+
+function assertBoolean(value, label) {
+  if (typeof value !== 'boolean') throw contractError(`${label} must be boolean`);
+}
+
+function assertEnum(value, values, label, { nullable = false } = {}) {
+  if (nullable && value === null) return;
+  if (typeof value !== 'string' || !values.includes(value)) {
+    throw contractError(`${label} is not a supported value`);
+  }
+}
+
+function assertBoundedArray(value, label) {
+  if (!Array.isArray(value) || value.length > MAX_ARRAY_LENGTH) {
+    throw contractError(`${label} must be a bounded array`);
+  }
+}
+
+function assertFingerprintMap(value, label) {
+  assertPlainObject(value, label);
+  assertNoUnknownKeys(value, [...FINGERPRINT_KEYS], label);
+  for (const key of FINGERPRINT_KEYS) {
+    if (Object.hasOwn(value, key)) assertNullableString(value[key], `${label}.${key}`);
+  }
+}
+
+function validateDispositionEntry(entry, idField, label) {
+  assertPlainObject(entry, label);
+  assertNoUnknownKeys(entry, [idField, 'disposition', 'incorporation', 'rationale'], label);
+  assertString(entry[idField], `${label}.${idField}`);
+  assertEnum(entry.disposition, AUTHORITY_DISPOSITION, `${label}.disposition`);
+  if (Object.hasOwn(entry, 'incorporation') && entry.incorporation !== null) {
+    assertPlainObject(entry.incorporation, `${label}.incorporation`);
+    assertNoUnknownKeys(entry.incorporation, ['articleLayer', 'passageIndex'], `${label}.incorporation`);
+  }
+  if (Object.hasOwn(entry, 'rationale') && entry.rationale !== null) {
+    assertString(entry.rationale, `${label}.rationale`);
+  }
+}
+
+function validateDispositionReport(report, label) {
+  assertPlainObject(report, label);
+  assertNoUnknownKeys(report, [
+    'articleKey',
+    'conflicts',
+    'contractVersion',
+    'domainAssertions',
+    'authoringGuidance',
+    'addenda',
+    'protectedOverrides',
+    'overallOutcome',
+    'policy',
+  ], label);
+  if (report.contractVersion !== DISPOSITION_REPORT_VERSION) {
+    throw contractError(`${label}.contractVersion is unsupported`);
+  }
+  if (Object.hasOwn(report, 'overallOutcome')) {
+    assertEnum(report.overallOutcome, AUTHORITY_OVERALL_OUTCOME, `${label}.overallOutcome`);
+  }
+  for (const section of ACTIVE_RECORD_SECTIONS) {
+    if (Object.hasOwn(report, section)) {
+      assertBoundedArray(report[section], `${label}.${section}`);
+      report[section].forEach((entry, index) => {
+        validateDispositionEntry(entry, DISPOSITION_ENTRY_ID_FIELDS[section], `${label}.${section}[${index}]`);
+      });
+    }
+  }
+  if (Object.hasOwn(report, 'conflicts')) {
+    assertBoundedArray(report.conflicts, `${label}.conflicts`);
+    report.conflicts.forEach((conflict, index) => {
+      validateConflictRecord(conflict, `${label}.conflicts[${index}]`);
+    });
+  }
+}
+
+function validateConflictRecord(conflict, label, { potential = false } = {}) {
+  assertPlainObject(conflict, label);
+  assertNoUnknownKeys(conflict, [
+    'authorities',
+    'kind',
+    'scope',
+    'reason',
+    'targetIdentity',
+    'subjectKey',
+    'guidanceId',
+    'guidanceTypes',
+    'assertionTextHashes',
+    'normalizedScopeIdentity',
+    'scopeKey',
+    'narrationMatches',
+  ], label);
+  if (Object.hasOwn(conflict, 'kind')) {
+    assertEnum(
+      conflict.kind,
+      potential ? POTENTIAL_CONFLICT_KINDS : CONFLICT_KINDS,
+      `${label}.kind`,
+      { nullable: true },
+    );
+  }
+  if (Object.hasOwn(conflict, 'authorities')) {
+    assertBoundedArray(conflict.authorities, `${label}.authorities`);
+    conflict.authorities.forEach((entry, index) => {
+      assertString(entry, `${label}.authorities[${index}]`);
+    });
+  }
+  if (Object.hasOwn(conflict, 'scope') && conflict.scope !== null) {
+    assertPlainObject(conflict.scope, `${label}.scope`);
+    assertNoUnknownKeys(conflict.scope, ['articleKey', 'layer'], `${label}.scope`);
+    if (Object.hasOwn(conflict.scope, 'articleKey')) {
+      assertString(conflict.scope.articleKey, `${label}.scope.articleKey`);
+    }
+  }
+  if (Object.hasOwn(conflict, 'reason')) assertNullableString(conflict.reason, `${label}.reason`);
+}
+
+function validateAuthorityConflicts(value, label) {
+  assertPlainObject(value, label);
+  assertNoUnknownKeys(value, ['conflicts', 'potentialHumanAuthorityConflicts'], label);
+  for (const key of ['conflicts', 'potentialHumanAuthorityConflicts']) {
+    assertBoundedArray(value[key], `${label}.${key}`);
+    value[key].forEach((entry, index) => validateConflictRecord(
+      entry,
+      `${label}.${key}[${index}]`,
+      { potential: key === 'potentialHumanAuthorityConflicts' },
+    ));
+  }
+}
+
+function validateAuthorityCurrentness(value, label) {
+  if (value === null) return;
+  assertPlainObject(value, label);
+  assertNoUnknownKeys(value, ['current', 'stale', 'unavailable', 'reasons'], label);
+  if (Object.hasOwn(value, 'current')) assertNullableBoolean(value.current, `${label}.current`);
+  if (Object.hasOwn(value, 'stale')) assertNullableBoolean(value.stale, `${label}.stale`);
+  if (Object.hasOwn(value, 'unavailable')) assertBoolean(value.unavailable, `${label}.unavailable`);
+  if (Object.hasOwn(value, 'reasons')) {
+    assertBoundedArray(value.reasons, `${label}.reasons`);
+    value.reasons.forEach((reason, index) => {
+      assertEnum(reason, CURRENTNESS_REASON_CODES, `${label}.reasons[${index}]`, { nullable: true });
+    });
+  }
+}
+
+function validateAuthorityDecisionRequest(input) {
+  assertPlainObject(input, 'request');
+  assertNoUnknownKeys(input, [
+    'contractVersion',
+    'platformId',
+    'articleKey',
+    'authorityPresent',
+    'domainAssertions',
+    'authoringGuidance',
+    'guidancePolicyFindings',
+    'policy',
+    'dispositionReport',
+    'articleStageReport',
+    'decisionStageReport',
+    'activeRecords',
+    'deterministicProtectedConflicts',
+    'currentAuthorityFingerprints',
+    'persistedAuthorityFingerprints',
+    'contextArticleKey',
+    'contextPolicyVersion',
+    'requestId',
+  ], 'request');
+  if (input.contractVersion !== CONTRACT_VERSION) throw contractError('request.contractVersion is unsupported');
+  assertString(input.platformId, 'request.platformId');
+  assertString(input.articleKey, 'request.articleKey');
+  if (Object.hasOwn(input, 'authorityPresent')) assertBoolean(input.authorityPresent, 'request.authorityPresent');
+  if (Object.hasOwn(input, 'domainAssertions')) {
+    assertBoundedArray(input.domainAssertions, 'request.domainAssertions');
+  }
+  if (Object.hasOwn(input, 'authoringGuidance')) {
+    assertBoundedArray(input.authoringGuidance, 'request.authoringGuidance');
+  }
+  if (Object.hasOwn(input, 'guidancePolicyFindings')) {
+    assertBoundedArray(input.guidancePolicyFindings, 'request.guidancePolicyFindings');
+  }
+  if (Object.hasOwn(input, 'policy') && input.policy !== null) assertPlainObject(input.policy, 'request.policy');
+  if (Object.hasOwn(input, 'dispositionReport') && input.dispositionReport !== null) {
+    validateDispositionReport(input.dispositionReport, 'request.dispositionReport');
+  }
+  if (Object.hasOwn(input, 'articleStageReport') && input.articleStageReport !== null) {
+    validateDispositionReport(input.articleStageReport, 'request.articleStageReport');
+  }
+  if (Object.hasOwn(input, 'decisionStageReport') && input.decisionStageReport !== null) {
+    validateDispositionReport(input.decisionStageReport, 'request.decisionStageReport');
+  }
+  if (Object.hasOwn(input, 'activeRecords') && input.activeRecords !== null) {
+    assertPlainObject(input.activeRecords, 'request.activeRecords');
+    assertNoUnknownKeys(input.activeRecords, ACTIVE_RECORD_SECTIONS, 'request.activeRecords');
+  }
+  if (Object.hasOwn(input, 'deterministicProtectedConflicts')) {
+    assertBoundedArray(input.deterministicProtectedConflicts, 'request.deterministicProtectedConflicts');
+  }
+  if (Object.hasOwn(input, 'currentAuthorityFingerprints') && input.currentAuthorityFingerprints !== null) {
+    assertFingerprintMap(input.currentAuthorityFingerprints, 'request.currentAuthorityFingerprints');
+  }
+  if (Object.hasOwn(input, 'persistedAuthorityFingerprints') && input.persistedAuthorityFingerprints !== null) {
+    assertFingerprintMap(input.persistedAuthorityFingerprints, 'request.persistedAuthorityFingerprints');
+  }
+  if (Object.hasOwn(input, 'contextArticleKey')) assertNullableString(input.contextArticleKey, 'request.contextArticleKey');
+  if (Object.hasOwn(input, 'contextPolicyVersion')) {
+    assertNullableString(input.contextPolicyVersion, 'request.contextPolicyVersion');
+  }
+  if (Object.hasOwn(input, 'requestId')) assertNullableString(input.requestId, 'request.requestId');
+  return input;
+}
+
+function validateAuthorityDecisionResponse(input) {
+  assertPlainObject(input, 'response');
+  assertNoUnknownKeys(input, [
+    'contractVersion',
+    'success',
+    'operation',
+    'provider',
+    'result',
+    'error',
+  ], 'response');
+  if (input.contractVersion !== CONTRACT_VERSION) throw contractError('response.contractVersion is unsupported');
+  assertBoolean(input.success, 'response.success');
+  if (input.operation !== OPERATION) throw contractError('response.operation is unsupported');
+  assertPlainObject(input.provider, 'response.provider');
+  assertNoUnknownKeys(input.provider, ['providerId', 'providerVersion'], 'response.provider');
+  assertString(input.provider.providerId, 'response.provider.providerId');
+  assertString(input.provider.providerVersion, 'response.provider.providerVersion');
+  if (input.success) {
+    if (input.error !== null) throw contractError('response.error must be null on success');
+    assertPlainObject(input.result, 'response.result');
+    assertNoUnknownKeys(input.result, [
+      'authorityConflicts',
+      'authorityDisposition',
+      'validation',
+      'conflictsAddressed',
+      'authorityCurrentness',
+    ], 'response.result');
+    validateAuthorityConflicts(input.result.authorityConflicts, 'response.result.authorityConflicts');
+    if (Object.hasOwn(input.result, 'authorityDisposition') && input.result.authorityDisposition !== null) {
+      assertPlainObject(input.result.authorityDisposition, 'response.result.authorityDisposition');
+      assertNoUnknownKeys(input.result.authorityDisposition, [
+        'contractVersion',
+        'articleKey',
+        'conflicts',
+        'domainAssertions',
+        'authoringGuidance',
+        'addenda',
+        'protectedOverrides',
+        'overallOutcome',
+        'policy',
+        'source',
+      ], 'response.result.authorityDisposition');
+      if (Object.hasOwn(input.result.authorityDisposition, 'contractVersion')) {
+        assertEnum(
+          input.result.authorityDisposition.contractVersion,
+          [DISPOSITION_REPORT_VERSION],
+          'response.result.authorityDisposition.contractVersion',
+        );
+      }
+      if (Object.hasOwn(input.result.authorityDisposition, 'source')) {
+        assertNullableString(input.result.authorityDisposition.source, 'response.result.authorityDisposition.source');
+      }
+    }
+    assertPlainObject(input.result.validation, 'response.result.validation');
+    assertNoUnknownKeys(input.result.validation, ['valid', 'applyEligible', 'violations'], 'response.result.validation');
+    assertBoolean(input.result.validation.valid, 'response.result.validation.valid');
+    assertBoolean(input.result.validation.applyEligible, 'response.result.validation.applyEligible');
+    assertBoundedArray(input.result.validation.violations, 'response.result.validation.violations');
+    if (input.result.validation.violations.length > MAX_VIOLATIONS) {
+      throw contractError('response.result.validation.violations must be a bounded array');
+    }
+    assertBoundedArray(input.result.conflictsAddressed, 'response.result.conflictsAddressed');
+    validateAuthorityCurrentness(input.result.authorityCurrentness, 'response.result.authorityCurrentness');
+  } else {
+    if (input.result !== null) throw contractError('response.result must be null on failure');
+    assertPlainObject(input.error, 'response.error');
+    assertNoUnknownKeys(input.error, ['code', 'category', 'message'], 'response.error');
+    for (const key of ['code', 'category', 'message']) {
+      if (!Object.hasOwn(input.error, key)) throw contractError(`response.error.${key} is required`);
+    }
+    assertEnum(input.error.code, ERROR_CODES, 'response.error.code');
+    assertEnum(input.error.category, ERROR_CATEGORIES, 'response.error.category');
+    assertString(input.error.message, 'response.error.message');
+  }
+  return input;
+}
+
+function normalizeAuthorityDecisionRequest(input) {
+  validateAuthorityDecisionRequest(input);
+  return JSON.parse(JSON.stringify(input));
+}
+
+function normalizeAuthorityDecisionResponse(input) {
+  validateAuthorityDecisionResponse(input);
+  return JSON.parse(JSON.stringify(input));
+}
+
+module.exports = {
+  ACTIVE_RECORD_SECTIONS,
+  AUTHORITY_DISPOSITION,
+  AUTHORITY_OVERALL_OUTCOME,
+  CONFLICT_KINDS,
+  POTENTIAL_CONFLICT_KIND,
+  POTENTIAL_CONFLICT_KINDS,
+  CONTRACT_VERSION,
+  CURRENTNESS_REASON_CODES,
+  DISPOSITION_REPORT_VERSION,
+  ERROR_CATEGORIES,
+  ERROR_CODES,
+  MAX_ARRAY_LENGTH,
+  MAX_STRING_LENGTH,
+  MAX_VIOLATIONS,
+  OPERATION,
+  normalizeAuthorityDecisionRequest,
+  normalizeAuthorityDecisionResponse,
+  validateAuthorityDecisionRequest,
+  validateAuthorityDecisionResponse,
+};

package/src/index.js

@@ -24,10 +24,14 @@ module.exports = {
     stageArtifactEnvelope: require('./reconciliation/stageArtifactEnvelope'),
   },
   authority: {
+    authorityDecisionContract: require('./authority/authorityDecisionContract'),
     authorityContracts: require('./authority/authorityContracts'),
     authorityDispositionContracts: require('./authority/authorityDispositionContracts'),
     humanGuidanceContracts: require('./authority/humanGuidanceContracts'),
   },
+  protectedContent: {
+    protectedContentReadinessContract: require('./protectedContent/protectedContentReadinessContract'),
+  },
   persistence: {
     kc2WireOperationContracts: require('./persistence/kc2WireOperationContracts'),
     kc2GenerationSnapshotPersistenceContract: require('./persistence/kc2GenerationSnapshotPersistenceContract'),

package/src/protectedContent/protectedContentReadinessContract.js

@@ -0,0 +1,266 @@
+'use strict';
+
+const CONTRACT_VERSION = 'protected-content-readiness.v1';
+const OPERATION = 'protected-content-readiness';
+const MAX_STRING_LENGTH = 512;
+const MAX_REASONS = 16;
+
+const OUTCOMES = Object.freeze([
+  'ready-for-adoption',
+  'ready-for-human-decision',
+  'blocked-recovery',
+  'blocked-repository-changed',
+  'blocked-authority-context-changed',
+  'blocked-protection-changed',
+  'blocked-candidate-invalid',
+  'blocked-addendum-duplication',
+  'unavailable',
+]);
+
+const BLOCKING_REASON_CODES = Object.freeze([
+  'inspection-artifact-unavailable',
+  'fingerprint-unavailable',
+  'authority-context-fingerprint-changed',
+  'repository-fingerprint-changed',
+  'candidate-fingerprint-changed',
+  'candidate-fingerprint-unavailable',
+  'candidate-facts-unavailable',
+  'human-authority-context-failed',
+  'human-authority-context-unavailable',
+  'protection-facts-unavailable',
+  'protection-not-current',
+  'protection-identity-changed',
+  'protection-not-active',
+  'addendum-facts-unavailable',
+  'addendum-duplication-observed',
+  'human-decision-pending',
+]);
+
+const HUMAN_AUTHORITY_CONTEXT_OUTCOMES = Object.freeze([
+  'success',
+  'failed',
+  'not-applicable',
+]);
+
+const LEGACY_REJECTED_REQUEST_KEYS = Object.freeze([
+  'blockingReasons',
+  'humanAuthorityContextStatus',
+  'humanAuthorityContextSuccess',
+  'dispositionOverallOutcome',
+  'authorityCurrent',
+  'repositoryCurrent',
+  'protectionCurrent',
+  'candidateValid',
+  'addendumValid',
+]);
+
+const ERROR_CATEGORIES = Object.freeze([
+  'invalid-payload',
+  'unauthorized',
+  'unavailable',
+  'unsupported-operation',
+  'semantic-failure',
+]);
+
+const ERROR_CODES = Object.freeze([
+  'invalid-payload',
+  'unauthorized',
+  'provider-unavailable',
+  'unsupported-operation',
+  'semantic-failure',
+]);
+
+function contractError(message) {
+  const error = new TypeError(message);
+  error.code = 'invalid-payload';
+  return error;
+}
+
+function assertPlainObject(value, label) {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw contractError(`${label} must be an object`);
+  }
+}
+
+function assertNoUnknownKeys(value, allowed, label) {
+  for (const key of Object.keys(value)) {
+    if (!allowed.includes(key)) throw contractError(`${label}.${key} is not supported`);
+  }
+}
+
+function assertString(value, label, { nullable = false } = {}) {
+  if (nullable && value === null) return;
+  if (typeof value !== 'string' || value.length === 0 || value.length > MAX_STRING_LENGTH) {
+    throw contractError(`${label} must be a bounded non-empty string${nullable ? ' or null' : ''}`);
+  }
+}
+
+function assertBoolean(value, label) {
+  if (typeof value !== 'boolean') throw contractError(`${label} must be boolean`);
+}
+
+function assertEnum(value, values, label) {
+  if (typeof value !== 'string' || !values.includes(value)) {
+    throw contractError(`${label} is not a supported value`);
+  }
+}
+
+function assertLegacyRejectedKeys(input, label) {
+  for (const key of LEGACY_REJECTED_REQUEST_KEYS) {
+    if (Object.hasOwn(input, key)) {
+      throw contractError(`${label}.${key} is not supported`);
+    }
+  }
+}
+
+function validateProtectionObserved(value, label) {
+  assertPlainObject(value, label);
+  assertNoUnknownKeys(value, ['present', 'active', 'protectionId', 'targetIdentity'], label);
+  assertBoolean(value.present, `${label}.present`);
+  if (Object.hasOwn(value, 'active')) assertBoolean(value.active, `${label}.active`);
+  if (Object.hasOwn(value, 'protectionId') && value.protectionId !== null) {
+    assertString(value.protectionId, `${label}.protectionId`);
+  }
+  if (Object.hasOwn(value, 'targetIdentity') && value.targetIdentity !== null) {
+    assertString(value.targetIdentity, `${label}.targetIdentity`);
+  }
+}
+
+function validateProtectedContentReadinessRequest(input) {
+  assertPlainObject(input, 'request');
+  assertLegacyRejectedKeys(input, 'request');
+  assertNoUnknownKeys(input, [
+    'contractVersion',
+    'platformId',
+    'articleKey',
+    'inspectionAvailable',
+    'blockingRecovery',
+    'persistedAuthorityFingerprint',
+    'observedAuthorityFingerprint',
+    'persistedRepositoryFingerprint',
+    'observedRepositoryFingerprint',
+    'persistedCandidateFingerprint',
+    'observedCandidateFingerprint',
+    'protectionObserved',
+    'protectionInspectedId',
+    'humanAuthorityContextOutcome',
+    'addendumPresent',
+    'addendumDuplicateLikely',
+    'humanDecisionPending',
+    'requestId',
+  ], 'request');
+  if (input.contractVersion !== CONTRACT_VERSION) {
+    throw contractError('request.contractVersion is unsupported');
+  }
+  assertString(input.platformId, 'request.platformId');
+  assertString(input.articleKey, 'request.articleKey');
+  assertBoolean(input.inspectionAvailable, 'request.inspectionAvailable');
+  if (Object.hasOwn(input, 'blockingRecovery')) {
+    assertBoolean(input.blockingRecovery, 'request.blockingRecovery');
+  }
+  for (const key of [
+    'persistedAuthorityFingerprint',
+    'observedAuthorityFingerprint',
+    'persistedRepositoryFingerprint',
+    'observedRepositoryFingerprint',
+    'persistedCandidateFingerprint',
+    'observedCandidateFingerprint',
+    'protectionInspectedId',
+  ]) {
+    if (Object.hasOwn(input, key)) assertString(input[key], `request.${key}`);
+  }
+  if (Object.hasOwn(input, 'protectionObserved')) {
+    validateProtectionObserved(input.protectionObserved, 'request.protectionObserved');
+  }
+  if (Object.hasOwn(input, 'humanAuthorityContextOutcome')) {
+    assertEnum(
+      input.humanAuthorityContextOutcome,
+      HUMAN_AUTHORITY_CONTEXT_OUTCOMES,
+      'request.humanAuthorityContextOutcome',
+    );
+  }
+  if (Object.hasOwn(input, 'addendumPresent')) {
+    assertBoolean(input.addendumPresent, 'request.addendumPresent');
+  }
+  if (Object.hasOwn(input, 'addendumDuplicateLikely')) {
+    assertBoolean(input.addendumDuplicateLikely, 'request.addendumDuplicateLikely');
+  }
+  if (Object.hasOwn(input, 'humanDecisionPending')) {
+    assertBoolean(input.humanDecisionPending, 'request.humanDecisionPending');
+  }
+  if (Object.hasOwn(input, 'requestId') && input.requestId !== null) {
+    assertString(input.requestId, 'request.requestId');
+  }
+  return input;
+}
+
+function validateProtectedContentReadinessResponse(input) {
+  assertPlainObject(input, 'response');
+  assertNoUnknownKeys(input, [
+    'contractVersion',
+    'success',
+    'operation',
+    'provider',
+    'result',
+    'error',
+  ], 'response');
+  if (input.contractVersion !== CONTRACT_VERSION) {
+    throw contractError('response.contractVersion is unsupported');
+  }
+  assertBoolean(input.success, 'response.success');
+  if (input.operation !== OPERATION) throw contractError('response.operation is unsupported');
+  assertPlainObject(input.provider, 'response.provider');
+  assertNoUnknownKeys(input.provider, ['providerId', 'providerVersion'], 'response.provider');
+  assertString(input.provider.providerId, 'response.provider.providerId');
+  assertString(input.provider.providerVersion, 'response.provider.providerVersion');
+  if (input.success) {
+    if (input.error !== null) throw contractError('response.error must be null on success');
+    assertPlainObject(input.result, 'response.result');
+    assertNoUnknownKeys(input.result, ['outcome', 'blockingReasonCodes'], 'response.result');
+    assertEnum(input.result.outcome, OUTCOMES, 'response.result.outcome');
+    if (!Array.isArray(input.result.blockingReasonCodes)
+      || input.result.blockingReasonCodes.length > MAX_REASONS) {
+      throw contractError('response.result.blockingReasonCodes must be a bounded array');
+    }
+    const seen = new Set();
+    input.result.blockingReasonCodes.forEach((reason, index) => {
+      assertEnum(reason, BLOCKING_REASON_CODES, `response.result.blockingReasonCodes[${index}]`);
+      if (seen.has(reason)) {
+        throw contractError(`response.result.blockingReasonCodes[${index}] is duplicated`);
+      }
+      seen.add(reason);
+    });
+  } else if (input.error !== null) {
+    assertPlainObject(input.error, 'response.error');
+    assertNoUnknownKeys(input.error, ['category', 'code', 'message'], 'response.error');
+    assertEnum(input.error.category, ERROR_CATEGORIES, 'response.error.category');
+    assertEnum(input.error.code, ERROR_CODES, 'response.error.code');
+    assertString(input.error.message, 'response.error.message');
+  }
+  return input;
+}
+
+function normalizeProtectedContentReadinessRequest(input) {
+  return validateProtectedContentReadinessRequest(input);
+}
+
+function normalizeProtectedContentReadinessResponse(input) {
+  return validateProtectedContentReadinessResponse(input);
+}
+
+module.exports = {
+  BLOCKING_REASON_CODES,
+  CONTRACT_VERSION,
+  ERROR_CATEGORIES,
+  ERROR_CODES,
+  HUMAN_AUTHORITY_CONTEXT_OUTCOMES,
+  LEGACY_REJECTED_REQUEST_KEYS,
+  MAX_REASONS,
+  MAX_STRING_LENGTH,
+  OPERATION,
+  OUTCOMES,
+  normalizeProtectedContentReadinessRequest,
+  normalizeProtectedContentReadinessResponse,
+  validateProtectedContentReadinessRequest,
+  validateProtectedContentReadinessResponse,
+};