@simplexable/kc2-client 0.3.0

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@simplexable/kc2-client",
+  "version": "0.3.0",
+  "description": "Host-neutral KC2 contracts for platform integrations.",
+  "main": "./src/index.js",
+  "type": "commonjs",
+  "exports": {
+    ".": "./src/index.js",
+    "./fingerprints/stableHash": "./src/fingerprints/stableHash.js",
+    "./platform/kc2PlatformIdentity": "./src/platform/kc2PlatformIdentity.js",
+    "./platform/kc2PlatformAdapterErrors": "./src/platform/kc2PlatformAdapterErrors.js",
+    "./platform/kc2PlatformAdapterContract": "./src/platform/kc2PlatformAdapterContract.js",
+    "./platform/kc2ObserveContract": "./src/platform/kc2ObserveContract.js",
+    "./platform/kc2SignalContract": "./src/platform/kc2SignalContract.js",
+    "./platform/kc2MaterializeContract": "./src/platform/kc2MaterializeContract.js",
+    "./ia/articleTopologyContracts": "./src/ia/articleTopologyContracts.js",
+    "./ia/authorabilityContracts": "./src/ia/authorabilityContracts.js",
+    "./generation/generationDecisionContract": "./src/generation/generationDecisionContract.js",
+    "./relationships/articleRelationshipContracts": "./src/relationships/articleRelationshipContracts.js",
+    "./reconciliation/kc2ReconciliationStageContracts": "./src/reconciliation/kc2ReconciliationStageContracts.js",
+    "./reconciliation/kc2ReconciliationContract": "./src/reconciliation/kc2ReconciliationContract.js",
+    "./reconciliation/stageArtifactEnvelope": "./src/reconciliation/stageArtifactEnvelope.js",
+    "./authority/authorityContracts": "./src/authority/authorityContracts.js",
+    "./authority/humanGuidanceContracts": "./src/authority/humanGuidanceContracts.js",
+    "./authority/authorityDispositionContracts": "./src/authority/authorityDispositionContracts.js",
+    "./persistence/kc2WireOperationContracts": "./src/persistence/kc2WireOperationContracts.js",
+    "./persistence/kc2GenerationSnapshotPersistenceContract": "./src/persistence/kc2GenerationSnapshotPersistenceContract.js",
+    "./persistence/kc2HumanAuthorityReadContract": "./src/persistence/kc2HumanAuthorityReadContract.js",
+    "./persistence/kc2HumanAuthorityWriteContract": "./src/persistence/kc2HumanAuthorityWriteContract.js",
+    "./errors/Kc2ClientError": "./src/errors/Kc2ClientError.js",
+    "./transport/requestJson": "./src/transport/requestJson.js",
+    "./clients/helpClient": "./src/clients/helpClient.js"
+  },
+  "files": [
+    "src"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "UNLICENSED"
+}

package/src/authority/authorityContracts.js

@@ -0,0 +1,7 @@
+'use strict';
+const AUTHORITY_CLASSIFICATION = Object.freeze({ AUTHORITATIVE_DOMAIN_KNOWLEDGE: 'authoritative-domain-knowledge', EXPERIENTIAL_OPERATOR_KNOWLEDGE: 'experiential-operator-knowledge', SOFTWARE_BEHAVIOR_CORRECTION: 'software-behavior-correction' });
+const AUTHORITY_DISPOSITION = Object.freeze(['incorporated', 'preserved-unchanged', 'not-applicable', 'superseded-by-newer-human-authority', 'conflict-with-software-evidence', 'conflict-with-another-human-authority', 'requires-human-review']);
+const AUTHORITY_OVERALL_OUTCOME = Object.freeze(['complete', 'provisional', 'blocked']);
+const authorityReferenceSchema = Object.freeze({ type: 'object', additionalProperties: false, required: ['kind', 'ref'], properties: { kind: { type: 'string', minLength: 1 }, ref: { type: 'string', minLength: 1 }, classification: { type: 'string', enum: Object.values(AUTHORITY_CLASSIFICATION) } } });
+function validateAuthorityReference(reference = {}) { const violations = []; const kind = String(reference.kind || '').trim(); const ref = String(reference.ref || '').trim(); const classification = String(reference.classification || '').trim() || null; if (!kind) violations.push('authority:missing-kind'); if (!ref) violations.push('authority:missing-ref'); if (classification && !Object.values(AUTHORITY_CLASSIFICATION).includes(classification)) violations.push('authority:invalid-classification'); return { classification, kind: kind || null, ref: ref || null, valid: violations.length === 0, violations }; }
+module.exports = { AUTHORITY_CLASSIFICATION, AUTHORITY_DISPOSITION, AUTHORITY_OVERALL_OUTCOME, authorityReferenceSchema, validateAuthorityReference };

package/src/authority/authorityDispositionContracts.js

@@ -0,0 +1,36 @@
+'use strict';
+
+// Public disposition vocabulary and field descriptors. Conflict analysis and
+// authority application remain KC2 server implementation.
+const AUTHORITY_DISPOSITION_CONTRACT_VERSION = 'kc2-human-authority-disposition.v1';
+const AUTHORITY_CONFLICT_KIND = Object.freeze({
+  DUPLICATE_DOMAIN_ASSERTION: 'duplicate-domain-assertion-text',
+  PROTECTED_CONTENT: 'protected-content-conflict',
+  REQUIRED_COVERAGE_EXCLUSION: 'required-coverage-exclusion-target-conflict',
+  SOFTWARE_EVIDENCE_VS_PROTECTED_OVERRIDE: 'software-evidence-vs-protected-override',
+});
+const AUTHORITY_PROTECTED_CONFLICT_KINDS = Object.freeze([
+  AUTHORITY_CONFLICT_KIND.SOFTWARE_EVIDENCE_VS_PROTECTED_OVERRIDE,
+  AUTHORITY_CONFLICT_KIND.PROTECTED_CONTENT,
+]);
+const AUTHORITY_DISPOSITION_FORBIDDEN_MUTATION_FIELDS = Object.freeze([
+  'mutated',
+  'retired',
+  'released',
+  'superseded',
+  'updatedRecord',
+]);
+const AUTHORITY_DISPOSITION_SECTIONS = Object.freeze([
+  Object.freeze({ dispositionField: 'disposition', idField: 'assertionId', invalidDispositions: Object.freeze(['preserved-unchanged']), key: 'domainAssertions', sourceField: 'domainAssertions' }),
+  Object.freeze({ dispositionField: 'disposition', idField: 'guidanceId', invalidDispositions: Object.freeze(['preserved-unchanged']), key: 'authoringGuidance', sourceField: 'authoringGuidance' }),
+  Object.freeze({ dispositionField: 'disposition', idField: 'addendumId', invalidDispositions: Object.freeze(['incorporated']), key: 'addenda', sourceField: 'addenda' }),
+  Object.freeze({ dispositionField: 'disposition', idField: 'protectionId', invalidDispositions: Object.freeze(['incorporated']), key: 'protectedOverrides', sourceField: 'protectedOverrides' }),
+]);
+
+module.exports = {
+  AUTHORITY_CONFLICT_KIND,
+  AUTHORITY_DISPOSITION_CONTRACT_VERSION,
+  AUTHORITY_DISPOSITION_FORBIDDEN_MUTATION_FIELDS,
+  AUTHORITY_DISPOSITION_SECTIONS,
+  AUTHORITY_PROTECTED_CONFLICT_KINDS,
+};

package/src/authority/humanGuidanceContracts.js

@@ -0,0 +1,9 @@
+'use strict';
+const HUMAN_GUIDANCE_STATUSES = Object.freeze(['active', 'superseded', 'retired']);
+const HUMAN_GUIDANCE_TYPES = Object.freeze(['required-coverage', 'emphasis', 'terminology', 'exclusion', 'sequencing', 'caution']);
+const HUMAN_GUIDANCE_MUTUALLY_EXCLUSIVE_TYPE_PAIRS = Object.freeze([Object.freeze(['required-coverage', 'exclusion'])]);
+function textOrEmpty(value) { return String(value || '').trim(); }
+function validateHumanGuidanceType(value) { const guidanceType = textOrEmpty(value); const valid = HUMAN_GUIDANCE_TYPES.includes(guidanceType); return { guidanceType: guidanceType || null, valid, violations: valid ? [] : [`human-guidance:invalid-type:${guidanceType || 'missing'}`] }; }
+function validateHumanGuidanceStatus(value) { const status = textOrEmpty(value); const valid = HUMAN_GUIDANCE_STATUSES.includes(status); return { status: status || null, valid, violations: valid ? [] : [`human-guidance:invalid-status:${status || 'missing'}`] }; }
+function areHumanGuidanceTypesMutuallyExclusive(left, right) { const a = textOrEmpty(left); const b = textOrEmpty(right); return HUMAN_GUIDANCE_MUTUALLY_EXCLUSIVE_TYPE_PAIRS.some(([first, second]) => (a === first && b === second) || (a === second && b === first)); }
+module.exports = { HUMAN_GUIDANCE_MUTUALLY_EXCLUSIVE_TYPE_PAIRS, HUMAN_GUIDANCE_STATUSES, HUMAN_GUIDANCE_TYPES, areHumanGuidanceTypesMutuallyExclusive, validateHumanGuidanceStatus, validateHumanGuidanceType };

package/src/clients/helpClient.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const Kc2ClientError = require('../errors/Kc2ClientError');
+const { requestJson } = require('../transport/requestJson');
+
+async function resolveKc2Help({
+  baseUrl,
+  input = {},
+  masterKey,
+  platformId,
+  request = requestJson,
+  timeoutMs,
+} = {}) {
+  const normalizedBaseUrl = String(baseUrl || '').trim().replace(/\/+$/, '');
+  if (!normalizedBaseUrl) {
+    throw new Kc2ClientError('KC2 help location is missing', {
+      code: 'kc2-client-invalid-url',
+      statusCode: 503,
+    });
+  }
+  if (platformId == null || String(platformId).trim() === '') {
+    throw new Kc2ClientError('KC2 help platform identity is missing', {
+      code: 'kc2-client-invalid-request',
+      statusCode: 400,
+    });
+  }
+  let response;
+  try {
+    response = await request({
+      body: { input, masterKey },
+      method: 'POST',
+      timeoutMs,
+      url: `${normalizedBaseUrl}/api/platforms/${encodeURIComponent(platformId)}/help/resolve`,
+    });
+  } catch (cause) {
+    if (cause instanceof Kc2ClientError) throw cause;
+    throw new Kc2ClientError('KC2 help request failed', { cause });
+  }
+  if (!response || response.statusCode >= 400 || response.body?.success === false) {
+    throw new Kc2ClientError(response?.body?.failure || 'KC2 help request failed', {
+      code: response?.body?.code || 'kc2-client-response-failed',
+      statusCode: response?.statusCode || 503,
+    });
+  }
+  return response.body?.result === undefined ? null : response.body.result;
+}
+
+module.exports = {
+  resolveKc2Help,
+};

package/src/errors/Kc2ClientError.js

@@ -0,0 +1,13 @@
+'use strict';
+
+class Kc2ClientError extends Error {
+  constructor(message, { code = 'kc2-client-request-failed', statusCode = 503, cause } = {}) {
+    super(message, cause === undefined ? undefined : { cause });
+    this.name = 'Kc2ClientError';
+    this.code = code;
+    this.statusCode = statusCode;
+    if (cause !== undefined) this.cause = cause;
+  }
+}
+
+module.exports = Kc2ClientError;

package/src/fingerprints/stableHash.js

@@ -0,0 +1,20 @@
+'use strict';
+
+const crypto = require('node:crypto');
+
+function stableStringify(value) {
+  if (value === null || value === undefined) return 'null';
+  if (typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`;
+  return `{${Object.keys(value).sort().map((key) => (
+    `${JSON.stringify(key)}:${stableStringify(value[key])}`
+  )).join(',')}}`;
+}
+
+function hashContent(value) {
+  return crypto.createHash('sha256')
+    .update(typeof value === 'string' ? value : stableStringify(value))
+    .digest('hex');
+}
+
+module.exports = { hashContent, stableStringify };

package/src/generation/generationDecisionContract.js

@@ -0,0 +1,208 @@
+'use strict';
+
+const CONTRACT_VERSION = 'generation-decision.v1';
+const OPERATION = 'generation-decision';
+const MAX_STRING_LENGTH = 512;
+const MAX_REASONS = 32;
+
+const ATTEMPT_STATUSES = Object.freeze([
+  'pending', 'running', 'resumable', 'completed', 'failed', 'stale', 'abandoned',
+]);
+const OPERATOR_INTENTS = Object.freeze([
+  'reuse', 'generate', 'inspect',
+]);
+const DECISIONS = Object.freeze(['reuse', 'generate', 'blocked', 'not-ready']);
+const READINESS_STATES = Object.freeze([
+  'ready', 'needs-authority', 'needs-inputs', 'stale', 'invalid',
+]);
+const REUSE_DISPOSITIONS = Object.freeze([
+  'allowed', 'not-allowed', 'not-applicable',
+]);
+const GENERATION_ENTRIES = Object.freeze([
+  'reuse-existing', 'start-generation', 'resolve-blockers', 'none',
+]);
+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 AUTHORITY_REASON_CODES = Object.freeze([
+  'authority-required', 'authority-unresolved', 'authority-conflict',
+]);
+const RESULT_REASON_CODES = Object.freeze([
+  'article-invalid', 'article-missing', 'attempt-missing', 'attempt-stale',
+  'artifact-current', 'artifact-stale', 'authority-required',
+  'authority-unresolved', 'authority-conflict', 'inputs-current',
+  'inputs-missing', 'inputs-stale', 'not-authorable', 'ready',
+]);
+
+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 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 assertNullableObject(value, label) {
+  if (value !== null) assertPlainObject(value, label);
+}
+
+function validateGenerationDecisionRequest(input) {
+  assertPlainObject(input, 'request');
+  assertNoUnknownKeys(input, [
+    'contractVersion', 'platformId', 'article', 'attempt', 'currentness',
+    'authority', 'operatorIntent', 'requestId',
+  ], 'request');
+  if (input.contractVersion !== CONTRACT_VERSION) throw contractError('request.contractVersion is unsupported');
+  assertString(input.platformId, 'request.platformId');
+  assertPlainObject(input.article, 'request.article');
+  assertNoUnknownKeys(input.article, ['canonicalKey', 'title'], 'request.article');
+  assertString(input.article.canonicalKey, 'request.article.canonicalKey');
+  if (Object.hasOwn(input.article, 'title')) assertNullableString(input.article.title, 'request.article.title');
+
+  if (Object.hasOwn(input, 'attempt')) assertNullableObject(input.attempt, 'request.attempt');
+  if (input.attempt && input.attempt !== null) {
+    assertNoUnknownKeys(input.attempt, ['attemptKey', 'inputFingerprint', 'status'], 'request.attempt');
+    if (Object.hasOwn(input.attempt, 'attemptKey')) assertNullableString(input.attempt.attemptKey, 'request.attempt.attemptKey');
+    if (Object.hasOwn(input.attempt, 'inputFingerprint')) assertNullableString(input.attempt.inputFingerprint, 'request.attempt.inputFingerprint');
+    if (Object.hasOwn(input.attempt, 'status')) assertEnum(input.attempt.status, ATTEMPT_STATUSES, 'request.attempt.status', { nullable: true });
+  }
+  if (Object.hasOwn(input, 'currentness')) assertNullableObject(input.currentness, 'request.currentness');
+  if (input.currentness && input.currentness !== null) {
+    assertNoUnknownKeys(input.currentness, ['inputCurrent', 'artifactCurrent'], 'request.currentness');
+    for (const key of ['inputCurrent', 'artifactCurrent']) {
+      if (Object.hasOwn(input.currentness, key)) assertNullableBoolean(input.currentness[key], `request.currentness.${key}`);
+    }
+  }
+  if (Object.hasOwn(input, 'authority')) assertNullableObject(input.authority, 'request.authority');
+  if (input.authority && input.authority !== null) {
+    assertNoUnknownKeys(input.authority, ['required', 'resolved', 'blockingReasons'], 'request.authority');
+    if (Object.hasOwn(input.authority, 'required')) assertNullableBoolean(input.authority.required, 'request.authority.required');
+    if (Object.hasOwn(input.authority, 'resolved')) assertNullableBoolean(input.authority.resolved, 'request.authority.resolved');
+    if (Object.hasOwn(input.authority, 'blockingReasons') && (!Array.isArray(input.authority.blockingReasons)
+      || input.authority.blockingReasons.length > MAX_REASONS)) {
+      throw contractError('request.authority.blockingReasons must be a bounded array');
+    }
+    (input.authority.blockingReasons || []).forEach((reason, index) => {
+      assertEnum(reason, AUTHORITY_REASON_CODES, `request.authority.blockingReasons[${index}]`);
+    });
+  }
+  if (Object.hasOwn(input, 'operatorIntent')) assertEnum(input.operatorIntent, OPERATOR_INTENTS, 'request.operatorIntent', { nullable: true });
+  if (Object.hasOwn(input, 'requestId')) assertNullableString(input.requestId, 'request.requestId');
+  return input;
+}
+
+function validateGenerationDecisionResponse(input) {
+  assertPlainObject(input, 'response');
+  assertNoUnknownKeys(input, [
+    'contractVersion', 'success', 'operation', 'provider', 'result', 'error',
+  ], 'response');
+  if (input.contractVersion !== CONTRACT_VERSION) throw contractError('response.contractVersion is unsupported');
+  if (typeof input.success !== 'boolean') throw contractError('response.success must be boolean');
+  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, [
+      'decision', 'readiness', 'reuse', 'generationEntry', 'reasons',
+      'inputFingerprint', 'evaluatedAt',
+    ], 'response.result');
+    for (const key of ['decision', 'readiness', 'reuse', 'generationEntry', 'reasons']) {
+      if (!Object.hasOwn(input.result, key)) throw contractError(`response.result.${key} is required`);
+    }
+    assertEnum(input.result.decision, DECISIONS, 'response.result.decision');
+    assertEnum(input.result.readiness, READINESS_STATES, 'response.result.readiness');
+    assertEnum(input.result.reuse, REUSE_DISPOSITIONS, 'response.result.reuse');
+    assertEnum(input.result.generationEntry, GENERATION_ENTRIES, 'response.result.generationEntry');
+    if (!Array.isArray(input.result.reasons) || input.result.reasons.length > MAX_REASONS) {
+      throw contractError('response.result.reasons must be a bounded array');
+    }
+    input.result.reasons.forEach((reason, index) => {
+      assertEnum(reason, RESULT_REASON_CODES, `response.result.reasons[${index}]`);
+    });
+    assertNullableString(input.result.inputFingerprint, 'response.result.inputFingerprint');
+    assertNullableString(input.result.evaluatedAt, 'response.result.evaluatedAt');
+  } 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 normalizeGenerationDecisionRequest(input) {
+  validateGenerationDecisionRequest(input);
+  return JSON.parse(JSON.stringify(input));
+}
+
+function normalizeGenerationDecisionResponse(input) {
+  validateGenerationDecisionResponse(input);
+  return JSON.parse(JSON.stringify(input));
+}
+
+module.exports = {
+  ATTEMPT_STATUSES,
+  AUTHORITY_REASON_CODES,
+  CONTRACT_VERSION,
+  DECISIONS,
+  ERROR_CATEGORIES,
+  ERROR_CODES,
+  GENERATION_ENTRIES,
+  OPERATION,
+  OPERATOR_INTENTS,
+  READINESS_STATES,
+  RESULT_REASON_CODES,
+  REUSE_DISPOSITIONS,
+  MAX_REASONS,
+  MAX_STRING_LENGTH,
+  normalizeGenerationDecisionRequest,
+  normalizeGenerationDecisionResponse,
+  validateGenerationDecisionRequest,
+  validateGenerationDecisionResponse,
+};

package/src/ia/articleTopologyContracts.js

@@ -0,0 +1,7 @@
+'use strict';
+const KC2_ARTICLE_MAPPING_AUTHORITY = Object.freeze({ ACCEPTED_KC2_STATE: 'accepted-kc2-state', COMPONENT_HUB: 'shared-primary-component-hub', DEFAULT_ONE_TO_ONE: 'default-one-to-one', KC2_MANUAL_REGISTRATION: 'kc2-manual-registration', OPERATOR_CONFIRM_ARTICLE_GROUP: 'operator-confirm-article-group', OPERATOR_CONVERGE: 'operator-converge-into', OPERATOR_KEEP_INDEPENDENT: 'operator-keep-independent', OPERATOR_NOT_AN_ARTICLE: 'operator-not-an-article', UNRESOLVED: 'unresolved-mapping' });
+const KC2_ARTICLE_MAPPING_CONFIDENCE = Object.freeze({ DETERMINISTIC: 'deterministic', OPERATOR: 'operator', RECOMMENDATION: 'recommendation', UNRESOLVED: 'unresolved' });
+const KC2_ARTICLE_GROUP_ISSUES = Object.freeze({ COMPETING_MAPPINGS: 'competing-primary-mappings', IDENTITY_UNRESOLVED: 'identity-unresolved', MAPPING_UNRESOLVED: 'mapping-unresolved', NOT_AN_ARTICLE: 'not-an-article', PENDING_IA_DECISION: 'pending-ia-decision', PLACEMENT_UNRESOLVED: 'placement-unresolved', STRUCTURAL_BLOCKER: 'structural-blocker' });
+function isOperatorIndependentMappingAuthority(value) { return [KC2_ARTICLE_MAPPING_AUTHORITY.OPERATOR_KEEP_INDEPENDENT, KC2_ARTICLE_MAPPING_AUTHORITY.OPERATOR_CONFIRM_ARTICLE_GROUP].includes(value); }
+function isOperatorIndependentDecisionType(value) { return ['keep-independent', 'confirm-article-group'].includes(value); }
+module.exports = { KC2_ARTICLE_GROUP_ISSUES, KC2_ARTICLE_MAPPING_AUTHORITY, KC2_ARTICLE_MAPPING_CONFIDENCE, isOperatorIndependentDecisionType, isOperatorIndependentMappingAuthority };

package/src/ia/authorabilityContracts.js

@@ -0,0 +1,14 @@
+'use strict';
+const KC2_ARTICLE_ELIGIBILITY_KINDS = Object.freeze({ AMBIGUOUS_REVIEW: 'ambiguous-review', ARTICLE_ELIGIBLE: 'article-eligible', EXISTING_CANONICAL_CONVERGENCE: 'existing-canonical-convergence', EXISTING_KC2_ARTICLE: 'existing-kc2-article', NON_ARTICLE_SOFTWARE_OBJECT: 'non-article-software-object', PRODUCT_SURFACE: 'product-surface', SUBORDINATE_TOPIC: 'subordinate-topic' });
+const KC2_IA_DECISION_TYPES = Object.freeze({ BOUNDARY_VALID_PLACEMENT_REVIEW: 'boundary-valid-placement-review', CONFIRM_ARTICLE_GROUP: 'confirm-article-group', CONVERGE_INTO: 'converge-into', DEFER: 'defer', KEEP_INDEPENDENT: 'keep-independent', MERGE_CANDIDATE: 'merge-candidate', NOT_AN_ARTICLE: 'not-an-article' });
+const KC2_PENDING_IA_DECISION_TYPES = Object.freeze(['boundary-valid-placement-review', 'defer', 'merge-candidate']);
+const KC2_NATIVE_TARGET_REASONS = Object.freeze({ ACCEPTED_KC2_STATE: 'accepted-kc2-state', CURRENT_PRODUCT_SURFACE: 'current-product-surface', HUMAN_IA_DECISION: 'human-ia-decision', KC2_REGISTRATION: 'kc2-registration' });
+const KC2_REPOSITORY_HELP_STATES = Object.freeze({ AUTOMATICALLY_MAINTAINABLE: 'automatically-maintainable', CURRENT: 'current', NEEDS_HUMAN_REVIEW: 'needs-human-review', NEEDS_NEW_KC2_HELP: 'needs-new-kc2-help', NEEDS_UPDATED_KC2_HELP: 'needs-updated-kc2-help' });
+const KC2_REPOSITORY_HELP_REASON_CODES = Object.freeze({ AMBIGUOUS_KC2_PRESENCE: 'ambiguous-kc2-presence', CURRENT: 'kc2-current', DETERMINISTIC_MAINTENANCE_APPLIED: 'deterministic-maintenance-applied', DETERMINISTIC_STALE_KC2_CONTENT: 'deterministic-stale-kc2-content', KC2_ARTICLE_MISSING: 'kc2-article-missing', MISSING_CANONICAL_IDENTITY: 'missing-canonical-identity', PARTIAL_EVIDENCE_CHANGE: 'partial-evidence-change-needs-review', UNRESOLVED_CANONICAL_IDENTITY: 'unresolved-canonical-identity' });
+const KC2_AUTHORABILITY_STATUSES = Object.freeze({ AUTHORABLE: 'authorable', CANONICAL_CONVERGENCE: 'canonical-convergence', CURRENT: 'current', NOT_AUTHORABLE: 'not-authorable', REVIEW_REQUIRED: 'review-required', UNKNOWN: 'unknown' });
+const KC2_AUTHORABILITY_QUEUES = Object.freeze({ IA_REVIEW: 'ia-review', SAFE_TO_AUTHOR: 'safe-to-author', STRUCTURAL_REVIEW: 'structural-review' });
+const KC2_ARTICLE_BOUNDARY_CODES = Object.freeze({ BOUNDARY_RESOLVED: 'boundary-resolved', COMPETING_MAPPINGS: 'competing-mappings', NEEDS_IA_DECISION: 'needs-ia-decision', NOT_AN_ARTICLE: 'not-an-article' });
+function uniqueSortedKeys(values = []) { return [...new Set(values.map((value) => String(value || '').trim()).filter(Boolean))].sort((a, b) => a.localeCompare(b)); }
+function normalizeIaDecision(decision = null) { if (!decision || typeof decision !== 'object') return null; const decisionType = String(decision.decisionType || '').trim() || null; if (!decisionType) return null; return { decisionType, destinationCanonicalKey: String(decision.destinationCanonicalKey || decision.targetArticleKey || '').trim() || null }; }
+function isPendingIaDecisionType(value = '') { return KC2_PENDING_IA_DECISION_TYPES.includes(String(value).trim()); }
+module.exports = { KC2_ARTICLE_BOUNDARY_CODES, KC2_ARTICLE_ELIGIBILITY_KINDS, KC2_AUTHORABILITY_QUEUES, KC2_AUTHORABILITY_STATUSES, KC2_IA_DECISION_TYPES, KC2_NATIVE_TARGET_REASONS, KC2_PENDING_IA_DECISION_TYPES, KC2_REPOSITORY_HELP_REASON_CODES, KC2_REPOSITORY_HELP_STATES, isPendingIaDecisionType, normalizeIaDecision, uniqueSortedKeys };

package/src/index.js

@@ -0,0 +1,40 @@
+'use strict';
+
+module.exports = {
+  fingerprints: { stableHash: require('./fingerprints/stableHash') },
+  platform: {
+    kc2PlatformIdentity: require('./platform/kc2PlatformIdentity'),
+    kc2PlatformAdapterErrors: require('./platform/kc2PlatformAdapterErrors'),
+    kc2PlatformAdapterContract: require('./platform/kc2PlatformAdapterContract'),
+    kc2ObserveContract: require('./platform/kc2ObserveContract'),
+    kc2SignalContract: require('./platform/kc2SignalContract'),
+    kc2MaterializeContract: require('./platform/kc2MaterializeContract'),
+  },
+  ia: {
+    articleTopologyContracts: require('./ia/articleTopologyContracts'),
+    authorabilityContracts: require('./ia/authorabilityContracts'),
+  },
+  generation: {
+    generationDecisionContract: require('./generation/generationDecisionContract'),
+  },
+  relationships: { articleRelationshipContracts: require('./relationships/articleRelationshipContracts') },
+  reconciliation: {
+    kc2ReconciliationContract: require('./reconciliation/kc2ReconciliationContract'),
+    kc2ReconciliationStageContracts: require('./reconciliation/kc2ReconciliationStageContracts'),
+    stageArtifactEnvelope: require('./reconciliation/stageArtifactEnvelope'),
+  },
+  authority: {
+    authorityContracts: require('./authority/authorityContracts'),
+    authorityDispositionContracts: require('./authority/authorityDispositionContracts'),
+    humanGuidanceContracts: require('./authority/humanGuidanceContracts'),
+  },
+  persistence: {
+    kc2WireOperationContracts: require('./persistence/kc2WireOperationContracts'),
+    kc2GenerationSnapshotPersistenceContract: require('./persistence/kc2GenerationSnapshotPersistenceContract'),
+    kc2HumanAuthorityReadContract: require('./persistence/kc2HumanAuthorityReadContract'),
+    kc2HumanAuthorityWriteContract: require('./persistence/kc2HumanAuthorityWriteContract'),
+  },
+  errors: { Kc2ClientError: require('./errors/Kc2ClientError') },
+  transport: { requestJson: require('./transport/requestJson') },
+  clients: { helpClient: require('./clients/helpClient') },
+};

package/src/persistence/kc2GenerationSnapshotPersistenceContract.js

@@ -0,0 +1,47 @@
+'use strict';
+
+const KC2_GENERATION_SNAPSHOT_PERSISTENCE_CAPABILITY = Object.freeze({
+  AVAILABLE: 'available',
+  UNAVAILABLE: 'unavailable',
+});
+
+function firstDefined(...values) {
+  return values.find((value) => value !== undefined && value !== null);
+}
+
+function projectKc2GenerationSnapshotRecord(source = {}) {
+  if (!source || typeof source !== 'object') return null;
+  return {
+    acceptedVersionId: firstDefined(source.acceptedVersionId, source.knowledgeArticleVersionId, source.knowledge_article_version_id, source.versionId, null),
+    articleKey: firstDefined(source.articleKey, source.article_key, null),
+    platformId: firstDefined(source.platformId, source.platform_id, null),
+    contractVersion: firstDefined(source.contractVersion, source.contract_version, null),
+    createdAt: firstDefined(source.createdAt, source.created_at, null),
+    expertGuidanceFingerprint: firstDefined(source.expertGuidanceFingerprint, source.expert_guidance_fingerprint, null),
+    expertGuidanceSnapshot: firstDefined(source.expertGuidanceSnapshot, source.expert_guidance_snapshot, []),
+    generationMetadata: firstDefined(source.generationMetadata, source.generation_metadata, {}),
+    proTipsFingerprint: firstDefined(source.proTipsFingerprint, source.pro_tips_fingerprint, null),
+    proTipsSnapshot: firstDefined(source.proTipsSnapshot, source.pro_tips_snapshot, []),
+    protectedAuthorityFingerprint: firstDefined(source.protectedAuthorityFingerprint, source.protected_authority_fingerprint, null),
+    protectedAuthoritySnapshot: firstDefined(source.protectedAuthoritySnapshot, source.protected_authority_snapshot, []),
+    snapshotId: firstDefined(source.snapshotId, source.knowledgeArticleGenerationSnapshotId, source.knowledge_article_generation_snapshot_id, null),
+    softwareEvidenceFingerprint: firstDefined(source.softwareEvidenceFingerprint, source.software_evidence_fingerprint, null),
+    softwareEvidenceSnapshot: firstDefined(source.softwareEvidenceSnapshot, source.software_evidence_snapshot, {}),
+  };
+}
+
+function assertKc2GenerationSnapshotPersistence(implementation) {
+  if (!implementation || typeof implementation !== 'object') {
+    throw new TypeError('KC2 generation-snapshot persistence must be an object');
+  }
+  if (implementation.capability !== KC2_GENERATION_SNAPSHOT_PERSISTENCE_CAPABILITY.AVAILABLE) {
+    throw new Error('KC2 generation-snapshot persistence is unavailable');
+  }
+  return implementation;
+}
+
+module.exports = {
+  KC2_GENERATION_SNAPSHOT_PERSISTENCE_CAPABILITY,
+  assertKc2GenerationSnapshotPersistence,
+  projectKc2GenerationSnapshotRecord,
+};

package/src/persistence/kc2HumanAuthorityReadContract.js

@@ -0,0 +1,23 @@
+'use strict';
+
+const KC2_HUMAN_AUTHORITY_READ_CAPABILITY = Object.freeze({
+  AVAILABLE: 'available',
+  UNAVAILABLE: 'unavailable',
+});
+const KC2_EXPERT_REVIEW_OBLIGATION_CATEGORY = 'expert-review-required';
+
+function assertKc2HumanAuthorityRead(implementation) {
+  if (!implementation || typeof implementation !== 'object') {
+    throw new TypeError('KC2 human-authority read persistence must be an object');
+  }
+  if (implementation.capability !== KC2_HUMAN_AUTHORITY_READ_CAPABILITY.AVAILABLE) {
+    throw new Error('KC2 human-authority read persistence is unavailable');
+  }
+  return implementation;
+}
+
+module.exports = {
+  KC2_EXPERT_REVIEW_OBLIGATION_CATEGORY,
+  KC2_HUMAN_AUTHORITY_READ_CAPABILITY,
+  assertKc2HumanAuthorityRead,
+};

package/src/persistence/kc2HumanAuthorityWriteContract.js

@@ -0,0 +1,21 @@
+'use strict';
+
+const KC2_HUMAN_AUTHORITY_WRITE_CAPABILITY = Object.freeze({
+  AVAILABLE: 'available',
+  UNAVAILABLE: 'unavailable',
+});
+
+function assertKc2HumanAuthorityWrite(implementation) {
+  if (!implementation || typeof implementation !== 'object') {
+    throw new TypeError('KC2 human-authority write persistence must be an object');
+  }
+  if (implementation.capability !== KC2_HUMAN_AUTHORITY_WRITE_CAPABILITY.AVAILABLE) {
+    throw new Error('KC2 human-authority write persistence is unavailable');
+  }
+  return implementation;
+}
+
+module.exports = {
+  KC2_HUMAN_AUTHORITY_WRITE_CAPABILITY,
+  assertKc2HumanAuthorityWrite,
+};

package/src/persistence/kc2WireOperationContracts.js

@@ -0,0 +1,81 @@
+'use strict';
+
+// Names and direction only: storage, transactions, and CRUD remain server-owned.
+const KC2_ACCEPTANCE_HTTP_OPERATIONS = Object.freeze(['finalize', 'status']);
+const KC2_ATTEMPT_HTTP_READ_OPERATIONS = Object.freeze(['listResumableAttempts', 'readAttempt', 'readLatestCompletedAttempt', 'readLatestResumableAttempt']);
+const KC2_ATTEMPT_HTTP_WRITE_OPERATIONS = Object.freeze(['claimAttemptForStage2', 'createAttempt', 'markAttemptAbandoned', 'markAttemptCompleted', 'markAttemptCompletionPersistenceFailed', 'markAttemptFailed', 'markAttemptResumable', 'markAttemptStale', 'markAttemptSuperseded', 'persistStage1Artifact', 'persistStage2Candidate']);
+const KC2_ATTEMPT_HTTP_OPERATIONS = Object.freeze([...KC2_ATTEMPT_HTTP_READ_OPERATIONS, ...KC2_ATTEMPT_HTTP_WRITE_OPERATIONS]);
+const KC2_EXPERT_REVIEW_HTTP_READ_OPERATIONS = Object.freeze(['loadExpertReviewObligations', 'readExpertReviewObligationById']);
+const KC2_EXPERT_REVIEW_HTTP_WRITE_OPERATIONS = Object.freeze(['resolveExpertReviewObligation']);
+const KC2_SNAPSHOT_HTTP_READ_OPERATIONS = Object.freeze(['listCurrentContent', 'loadAcceptedGenerationSnapshot']);
+const KC2_ATTEMPT_PERSISTENCE_CAPABILITY = Object.freeze({ AVAILABLE: 'available', UNAVAILABLE: 'unavailable' });
+const KC2_GENERATION_SNAPSHOT_PERSISTENCE_CAPABILITY = Object.freeze({ AVAILABLE: 'available', UNAVAILABLE: 'unavailable' });
+const KC2_HUMAN_AUTHORITY_READ_CAPABILITY = Object.freeze({ AVAILABLE: 'available', UNAVAILABLE: 'unavailable' });
+const KC2_HUMAN_AUTHORITY_WRITE_CAPABILITY = Object.freeze({ AVAILABLE: 'available', UNAVAILABLE: 'unavailable' });
+const KC2_HUMAN_AUTHORITY_CORE_OPERATIONS = Object.freeze([
+  'listActiveHumanAddendumArticleKeys', 'listAuthoringGuidance', 'listDomainAssertions',
+  'listHumanAddenda', 'listProtectedContent', 'readActiveProtectedContentByTarget',
+  'readAuthoringGuidanceByCreateRequest', 'readAuthoringGuidanceById',
+  'readDomainAssertionByCreateRequest', 'readDomainAssertionById',
+  'readHumanAddendumByCreateRequest', 'readHumanAddendumById', 'readProtectedContentById',
+  'activateDomainAssertion', 'insertAuthoringGuidance', 'insertDomainAssertion',
+  'insertHumanAddendum', 'insertProtectedContent', 'markAuthoringGuidanceSuperseded',
+  'markDomainAssertionSuperseded', 'markProtectedContentSuperseded',
+  'reactivateAuthoringGuidance', 'reactivateDomainAssertion', 'releaseProtectedContent',
+  'removeHumanAddendum', 'restoreHumanAddendum', 'retireAuthoringGuidance',
+  'retireDomainAssertion', 'updateAuthoringGuidance', 'updateDomainAssertion',
+  'updateHumanAddendum',
+]);
+const KC2_HUMAN_AUTHORITY_CORE_WRITE_OPERATIONS = Object.freeze(KC2_HUMAN_AUTHORITY_CORE_OPERATIONS.slice(13));
+const KC2_EXPERT_REVIEW_OBLIGATION_CATEGORY = 'expert-review-required';
+const HOST_CONVERSION_REVIEW_MARKER_CATEGORY = 'authoritative-domain-knowledge-gap';
+const KC2_WIRE_OPERATION_GROUPS = Object.freeze({
+  acceptance: KC2_ACCEPTANCE_HTTP_OPERATIONS,
+  attemptRead: KC2_ATTEMPT_HTTP_READ_OPERATIONS,
+  attemptWrite: KC2_ATTEMPT_HTTP_WRITE_OPERATIONS,
+  expertReviewRead: KC2_EXPERT_REVIEW_HTTP_READ_OPERATIONS,
+  expertReviewWrite: KC2_EXPERT_REVIEW_HTTP_WRITE_OPERATIONS,
+  snapshotRead: KC2_SNAPSHOT_HTTP_READ_OPERATIONS,
+});
+function isKc2WireOperation(name) { return Object.values(KC2_WIRE_OPERATION_GROUPS).some((operations) => operations.includes(String(name || '').trim())); }
+const isKc2AttemptAcceptanceCoupledOperation = (name) => String(name || '').trim() === 'bindAcceptedCanonicalStage2';
+const isKc2SnapshotHttpOperation = (name) => KC2_SNAPSHOT_HTTP_READ_OPERATIONS.includes(String(name || '').trim());
+const isKc2AcceptanceHttpOperation = (name) => KC2_ACCEPTANCE_HTTP_OPERATIONS.includes(String(name || '').trim());
+const isKc2ExpertReviewHttpOperation = (name) => [...KC2_EXPERT_REVIEW_HTTP_READ_OPERATIONS, ...KC2_EXPERT_REVIEW_HTTP_WRITE_OPERATIONS].includes(String(name || '').trim());
+const isKc2ExpertReviewHttpWriteOperation = (name) => KC2_EXPERT_REVIEW_HTTP_WRITE_OPERATIONS.includes(String(name || '').trim());
+const isKc2ExpertReviewAcceptanceCoupledOperation = (name) => String(name || '').trim() === 'openExpertReviewObligation';
+const isKc2HumanAuthorityCoreOperation = (name) => KC2_HUMAN_AUTHORITY_CORE_OPERATIONS.includes(String(name || '').trim());
+const isKc2HumanAuthorityCoreWriteOperation = (name) => KC2_HUMAN_AUTHORITY_CORE_WRITE_OPERATIONS.includes(String(name || '').trim());
+const isKc2AttemptHttpOperation = (name) => [...KC2_ATTEMPT_HTTP_READ_OPERATIONS, ...KC2_ATTEMPT_HTTP_WRITE_OPERATIONS].includes(String(name || '').trim());
+const isKc2AttemptHttpWriteOperation = (name) => KC2_ATTEMPT_HTTP_WRITE_OPERATIONS.includes(String(name || '').trim());
+const isKc2SnapshotAcceptanceCoupledOperation = (name) => String(name || '').trim() === 'recordAcceptedGenerationSnapshot';
+module.exports = {
+  HOST_CONVERSION_REVIEW_MARKER_CATEGORY,
+  KC2_ACCEPTANCE_HTTP_OPERATIONS,
+  KC2_ATTEMPT_HTTP_READ_OPERATIONS,
+  KC2_ATTEMPT_HTTP_OPERATIONS,
+  KC2_ATTEMPT_HTTP_WRITE_OPERATIONS,
+  KC2_ATTEMPT_PERSISTENCE_CAPABILITY,
+  KC2_EXPERT_REVIEW_HTTP_READ_OPERATIONS,
+  KC2_EXPERT_REVIEW_HTTP_WRITE_OPERATIONS,
+  KC2_EXPERT_REVIEW_OBLIGATION_CATEGORY,
+  KC2_GENERATION_SNAPSHOT_PERSISTENCE_CAPABILITY,
+  KC2_HUMAN_AUTHORITY_CORE_OPERATIONS,
+  KC2_HUMAN_AUTHORITY_CORE_WRITE_OPERATIONS,
+  KC2_HUMAN_AUTHORITY_READ_CAPABILITY,
+  KC2_HUMAN_AUTHORITY_WRITE_CAPABILITY,
+  KC2_SNAPSHOT_HTTP_READ_OPERATIONS,
+  KC2_WIRE_OPERATION_GROUPS,
+  isKc2AcceptanceHttpOperation,
+  isKc2AttemptAcceptanceCoupledOperation,
+  isKc2AttemptHttpOperation,
+  isKc2AttemptHttpWriteOperation,
+  isKc2ExpertReviewAcceptanceCoupledOperation,
+  isKc2ExpertReviewHttpOperation,
+  isKc2ExpertReviewHttpWriteOperation,
+  isKc2HumanAuthorityCoreOperation,
+  isKc2HumanAuthorityCoreWriteOperation,
+  isKc2SnapshotAcceptanceCoupledOperation,
+  isKc2SnapshotHttpOperation,
+  isKc2WireOperation,
+};

package/src/platform/kc2MaterializeContract.js

@@ -0,0 +1,40 @@
+'use strict';
+const { hashContent } = require('../fingerprints/stableHash');
+const { normalizeKc2HostObjectRef, normalizeKc2OpaqueActor, normalizeKc2OpaquePublicationIdentity, normalizeKc2PlatformId } = require('./kc2PlatformIdentity');
+const KC2_MATERIALIZE_CONTRACT_VERSION = 'kc2-materialize.v1';
+const KC2_MATERIALIZE_OPERATIONS = Object.freeze(['publish-article', 'update-article', 'retire-article', 'compensate', 'verify']);
+const KC2_MATERIALIZE_MUTATION_OPERATIONS = Object.freeze(['publish-article', 'update-article', 'retire-article']);
+const KC2_MATERIALIZE_RESULT_FORBIDDEN_KEYS = Object.freeze(['accepted', 'canonicalAcceptance', 'currentness', 'expertReviewDisposition', 'generationRequired']);
+const KC2_COMPENSATE_REASONS = Object.freeze(['kc2-finalize-failed-after-materialization']);
+function rejectPolicyFields(source, label) {
+  for (const key of KC2_MATERIALIZE_RESULT_FORBIDDEN_KEYS) if (source && Object.hasOwn(source, key)) {
+    const error = new Error(`${label} must not include KC2 policy field ${key}`); error.code = 'kc2-platform-materialization-failed'; throw error;
+  }
+}
+function hashKc2MaterializeRequest(request = {}) {
+  return hashContent({ operation: request.operation || null, payload: request.payload || null, platformId: request.platformId || null, subject: request.subject || null });
+}
+function normalizeKc2MaterializeRequest(input = {}, options = {}) {
+  const subject = normalizeKc2HostObjectRef(input.subject || input);
+  const operation = String(input.operation || 'publish-article').trim();
+  if (!KC2_MATERIALIZE_OPERATIONS.includes(operation)) { const error = new Error(`materialize operation is not recognized: ${operation}`); error.code = 'kc2-platform-materialization-rejected'; throw error; }
+  const timeoutMs = input.timeoutMs == null ? 30000 : Number(input.timeoutMs);
+  if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) { const error = new Error('timeoutMs must be a positive integer'); error.code = 'kc2-platform-timeout'; throw error; }
+  const operationId = input.operationId == null ? null : String(input.operationId).trim();
+  if (options.requireOperationId === true && !operationId) { const error = new Error('operationId is required'); error.code = 'kc2-platform-materialization-rejected'; throw error; }
+  const normalized = { actor: normalizeKc2OpaqueActor(input.actor), contractVersion: KC2_MATERIALIZE_CONTRACT_VERSION, operation, operationId, payload: input.payload && typeof input.payload === 'object' ? input.payload : null, platformId: subject.platformId, subject, timeoutMs };
+  return { ...normalized, requestHash: hashKc2MaterializeRequest(normalized) };
+}
+function normalizeKc2MaterializeResult(input = {}) {
+  rejectPolicyFields(input, 'materialize result');
+  return { destinationIdentity: input.destinationIdentity == null ? null : String(input.destinationIdentity), error: input.error && typeof input.error === 'object' ? input.error : null, materializationFingerprint: input.materializationFingerprint == null ? null : String(input.materializationFingerprint), operationId: input.operationId == null ? null : String(input.operationId), publicationIdentity: normalizeKc2OpaquePublicationIdentity(input.publicationIdentity), requestHash: input.requestHash == null ? null : String(input.requestHash), rollbackToken: input.rollbackToken == null ? null : String(input.rollbackToken), success: input.success === true };
+}
+function normalizeKc2CompensateRequest(input = {}) {
+  const operationId = String(input.operationId || '').trim();
+  if (!operationId) { const error = new Error('operationId is required'); error.code = 'kc2-platform-materialization-rejected'; throw error; }
+  const timeoutMs = input.timeoutMs == null ? 30000 : Number(input.timeoutMs);
+  if (!Number.isInteger(timeoutMs) || timeoutMs <= 0) { const error = new Error('timeoutMs must be a positive integer'); error.code = 'kc2-platform-timeout'; throw error; }
+  return { contractVersion: KC2_MATERIALIZE_CONTRACT_VERSION, operation: 'compensate', operationId, platformId: normalizeKc2PlatformId(input.platformId), publicationIdentity: normalizeKc2OpaquePublicationIdentity(input.publicationIdentity || input.materializationIdentity), reason: KC2_COMPENSATE_REASONS.includes(input.reason) ? input.reason : KC2_COMPENSATE_REASONS[0], rollbackToken: input.rollbackToken == null ? null : String(input.rollbackToken), timeoutMs };
+}
+function describeKc2MaterializeSemantics() { return { automaticPublicationRequiresSeparateAuthority: true, capabilityIsNotAuthority: true, compensationIsHostOwned: true, compensationReversesHostSideEffectsOnly: true, distributedTwoPhaseCommit: false, doesNotDecideAcceptance: true, doesNotDecideCurrentness: true, laterObserveMayConfirm: true, noPublicationAvoidsMaterialize: true, operationIdOwnedByKc2Saga: true, payloadIsOpaqueHostContext: true, publicationRequiredUsesSaga: true, replaySamePayloadReturnsPriorResult: true, replayDifferentPayloadConflicts: true, successfulMaterializeDoesNotRefreshAllObservations: true }; }
+module.exports = { KC2_COMPENSATE_REASONS, KC2_MATERIALIZE_CONTRACT_VERSION, KC2_MATERIALIZE_MUTATION_OPERATIONS, KC2_MATERIALIZE_OPERATIONS, KC2_MATERIALIZE_RESULT_FORBIDDEN_KEYS, describeKc2MaterializeSemantics, hashKc2MaterializeRequest, normalizeKc2CompensateRequest, normalizeKc2MaterializeRequest, normalizeKc2MaterializeResult };

package/src/platform/kc2ObserveContract.js

@@ -0,0 +1,30 @@
+'use strict';
+const { normalizeKc2HostObjectRef, normalizeKc2OpaquePublicationIdentity, normalizeKc2PlatformIdentity } = require('./kc2PlatformIdentity');
+const KC2_OBSERVE_FACT_KINDS = Object.freeze(['inventory', 'evidence', 'relationships', 'organization', 'materialization', 'revision']);
+const KC2_OBSERVE_FORBIDDEN_KEYS = Object.freeze(['automaticWorkPermitted', 'bootstrap', 'canonicalStage2', 'currentness', 'docsShouldExist', 'expertReviewRequired', 'generationRequired', 'reconciliationRequired', 'stale', 'workRequired']);
+function rejectPolicyFields(source, label) {
+  if (!source || typeof source !== 'object') return;
+  for (const key of KC2_OBSERVE_FORBIDDEN_KEYS) if (Object.hasOwn(source, key)) {
+    const error = new Error(`${label} must not include KC2 policy field ${key}`); error.code = 'kc2-platform-observation-failed'; throw error;
+  }
+}
+function normalizeKc2ObservationProvenance(input = {}) {
+  const { platformId } = normalizeKc2PlatformIdentity(input);
+  return { adapterVersion: input.adapterVersion == null ? null : String(input.adapterVersion), changedScope: Array.isArray(input.changedScope) ? input.changedScope.slice() : null, evidenceFingerprint: input.evidenceFingerprint == null ? null : String(input.evidenceFingerprint), observedAt: input.observedAt == null ? null : String(input.observedAt), platformId, sourceFingerprint: input.sourceFingerprint == null ? null : String(input.sourceFingerprint), sourceRevision: input.sourceRevision == null ? null : String(input.sourceRevision) };
+}
+function normalizeKc2Observation(input = {}) {
+  rejectPolicyFields(input, 'observation'); rejectPolicyFields(input.facts, 'observation.facts');
+  const provenance = normalizeKc2ObservationProvenance(input);
+  const factKind = String(input.factKind || '').trim();
+  if (!KC2_OBSERVE_FACT_KINDS.includes(factKind)) { const error = new Error(`observation factKind is not recognized: ${factKind}`); error.code = 'kc2-platform-observation-failed'; throw error; }
+  const subject = input.subject ? normalizeKc2HostObjectRef({ ...input.subject, platformId: input.subject.platformId || provenance.platformId }) : { hostObjectId: null, hostObjectKind: null, kc2ArticleKey: null, platformId: provenance.platformId };
+  const facts = input.facts && typeof input.facts === 'object' ? { ...input.facts } : {};
+  if (factKind === 'materialization') {
+    facts.exists = facts.exists === true;
+    facts.publicationIdentity = normalizeKc2OpaquePublicationIdentity(facts.publicationIdentity || facts.currentVersionId);
+    facts.materializationFingerprint = facts.materializationFingerprint == null ? null : String(facts.materializationFingerprint);
+    facts.destinationIdentity = facts.destinationIdentity == null ? null : String(facts.destinationIdentity);
+  }
+  return { ...provenance, factKind, facts, subject };
+}
+module.exports = { KC2_OBSERVE_FACT_KINDS, KC2_OBSERVE_FORBIDDEN_KEYS, normalizeKc2Observation, normalizeKc2ObservationProvenance };

package/src/platform/kc2PlatformAdapterContract.js

@@ -0,0 +1,84 @@
+'use strict';
+
+const { createKc2PlatformAdapterError, KC2_PLATFORM_ADAPTER_ERROR_CODES } = require('./kc2PlatformAdapterErrors');
+const { normalizeKc2PlatformIdentity } = require('./kc2PlatformIdentity');
+const KC2_PLATFORM_ADAPTER_CONTRACT_VERSION = 'kc2-platform-adapter.v1';
+const KC2_PLATFORM_CAPABILITIES = Object.freeze({
+  MAINTAIN_APPROVED_WORK: 'maintain.approvedWork', MAINTAIN_ORGANIZATION: 'maintain.organization',
+  MAINTAIN_RELATIONSHIPS: 'maintain.relationships', MAINTAIN_REVIEW_MARKER: 'maintain.reviewMarker',
+  MATERIALIZE_ARTICLE: 'materialize.article', MATERIALIZE_COMPENSATE: 'materialize.compensate',
+  OBSERVE_EVIDENCE: 'observe.evidence', OBSERVE_INVENTORY: 'observe.inventory',
+  OBSERVE_MATERIALIZATION: 'observe.materialization', OBSERVE_ORGANIZATION: 'observe.organization',
+  OBSERVE_RELATIONSHIPS: 'observe.relationships', OBSERVE_REVISION: 'observe.revision',
+  SIGNAL_CHANGE: 'signal.change',
+});
+const KC2_PLATFORM_OPTIONAL_CAPABILITIES = Object.freeze(Object.values(KC2_PLATFORM_CAPABILITIES));
+const KC2_PLATFORM_FAMILY_METHODS = Object.freeze({
+  maintain: ['approvedWork', 'organization', 'relationships', 'reviewMarker'],
+  materialize: ['article', 'compensate'],
+  observe: ['evidence', 'inventory', 'materialization', 'organization', 'relationships', 'revision'],
+  signal: ['change'],
+});
+function listDeclaredCapabilities(capabilities = {}) {
+  return Object.values(KC2_PLATFORM_CAPABILITIES).filter((name) => capabilities[name] === true);
+}
+function capabilityMethod(capability) {
+  const [family, method] = String(capability).split('.');
+  return { family, method };
+}
+function normalizeKc2PlatformCapabilities(input = {}) {
+  const capabilities = Object.fromEntries(Object.values(KC2_PLATFORM_CAPABILITIES)
+    .map((name) => [name, input[name] === true]));
+  if (!['observe.inventory', 'observe.revision', 'observe.materialization']
+    .some((name) => capabilities[name])) {
+    throw createKc2PlatformAdapterError(KC2_PLATFORM_ADAPTER_ERROR_CODES.ADAPTER_INCOMPATIBLE,
+      'a platform adapter must declare at least one observe capability');
+  }
+  return Object.freeze(capabilities);
+}
+function assertKc2AdapterCallBounds(input = {}) {
+  if (input.timeoutMs == null) return input;
+  if (!Number.isInteger(Number(input.timeoutMs)) || Number(input.timeoutMs) <= 0) {
+    throw createKc2PlatformAdapterError(KC2_PLATFORM_ADAPTER_ERROR_CODES.TIMEOUT,
+      'adapter timeoutMs must be a positive integer');
+  }
+  return input;
+}
+function hasCapability(adapter, capability) { return adapter?.capabilities?.[capability] === true; }
+function assertCapability(adapter, capability) {
+  if (!hasCapability(adapter, capability)) throw createKc2PlatformAdapterError(
+    KC2_PLATFORM_ADAPTER_ERROR_CODES.UNSUPPORTED_CAPABILITY, `unsupported platform capability: ${capability}`);
+}
+function assertKc2PlatformAdapter(adapter = {}) {
+  if (adapter.contractVersion !== KC2_PLATFORM_ADAPTER_CONTRACT_VERSION) throw createKc2PlatformAdapterError(
+    KC2_PLATFORM_ADAPTER_ERROR_CODES.ADAPTER_INCOMPATIBLE, 'incompatible platform adapter contract');
+  const capabilities = normalizeKc2PlatformCapabilities(adapter.capabilities);
+  for (const capability of listDeclaredCapabilities(capabilities)) {
+    const { family, method } = capabilityMethod(capability);
+    if (typeof adapter[family]?.[method] !== 'function') throw createKc2PlatformAdapterError(
+      KC2_PLATFORM_ADAPTER_ERROR_CODES.ADAPTER_INCOMPATIBLE, `declared capability ${capability} has no implementation`);
+  }
+  for (const [family, methods] of Object.entries(KC2_PLATFORM_FAMILY_METHODS)) for (const method of methods) {
+    if (typeof adapter[family]?.[method] === 'function' && !capabilities[`${family}.${method}`]) throw createKc2PlatformAdapterError(
+      KC2_PLATFORM_ADAPTER_ERROR_CODES.ADAPTER_INCOMPATIBLE, `implemented ${family}.${method} must be declared`);
+  }
+  return { capabilities, contractVersion: adapter.contractVersion, platformId: normalizeKc2PlatformIdentity(adapter).platformId };
+}
+function describeKc2PlatformAdapter(adapter = {}) {
+  const { capabilities, contractVersion, platformId } = assertKc2PlatformAdapter(adapter);
+  const declared = listDeclaredCapabilities(capabilities);
+  return {
+    capabilities: declared, contractVersion, platformId,
+    maintainSupported: declared.some((n) => n.startsWith('maintain.')),
+    materializeSupported: declared.some((n) => n.startsWith('materialize.')),
+    observeSupported: declared.some((n) => n.startsWith('observe.')),
+    signalSupported: declared.includes('signal.change'),
+    pollOnly: declared.some((n) => n.startsWith('observe.')) && !declared.includes('signal.change'),
+    readOnly: !declared.some((n) => n.startsWith('materialize.') || n.startsWith('maintain.')),
+  };
+}
+module.exports = {
+  KC2_PLATFORM_ADAPTER_CONTRACT_VERSION, KC2_PLATFORM_CAPABILITIES, KC2_PLATFORM_OPTIONAL_CAPABILITIES,
+  assertCapability, assertKc2AdapterCallBounds, assertKc2PlatformAdapter, describeKc2PlatformAdapter,
+  hasCapability, listDeclaredCapabilities, normalizeKc2PlatformCapabilities,
+};

package/src/platform/kc2PlatformAdapterErrors.js

@@ -0,0 +1,24 @@
+'use strict';
+
+const KC2_PLATFORM_ADAPTER_ERROR_CODES = Object.freeze({
+  UNAVAILABLE: 'kc2-platform-unavailable',
+  UNSUPPORTED_CAPABILITY: 'kc2-platform-capability-unsupported',
+  OBSERVATION_FAILED: 'kc2-platform-observation-failed',
+  MATERIALIZATION_REJECTED: 'kc2-platform-materialization-rejected',
+  MATERIALIZATION_FAILED: 'kc2-platform-materialization-failed',
+  COMPENSATION_FAILED: 'kc2-platform-compensation-failed',
+  OBSERVATION_STALE: 'kc2-platform-observation-stale',
+  IDENTITY_UNRESOLVED: 'kc2-platform-identity-unresolved',
+  ADAPTER_INCOMPATIBLE: 'kc2-platform-adapter-incompatible',
+  TIMEOUT: 'kc2-platform-timeout',
+});
+function createKc2PlatformAdapterError(code, message, cause) {
+  if (!Object.values(KC2_PLATFORM_ADAPTER_ERROR_CODES).includes(code)) {
+    throw new Error(`unknown platform adapter error code: ${code}`);
+  }
+  const error = new Error(message || code);
+  error.code = code;
+  if (cause !== undefined) error.cause = cause;
+  return error;
+}
+module.exports = { KC2_PLATFORM_ADAPTER_ERROR_CODES, createKc2PlatformAdapterError };

package/src/platform/kc2PlatformIdentity.js

@@ -0,0 +1,72 @@
+'use strict';
+
+const KC2_HOST_OBJECT_KINDS = Object.freeze([
+  'article', 'surface', 'evidence', 'relationship', 'organization',
+  'revision', 'publication',
+]);
+const KC2_ACTOR_KINDS = Object.freeze(['human', 'kc2-system', 'host-service']);
+const KC2_PLATFORM_ID_MIN = 1;
+const KC2_PLATFORM_ID_MAX = 32767;
+
+function identityError(message) {
+  const error = new Error(message);
+  error.code = 'kc2-platform-identity-unresolved';
+  return error;
+}
+function normalizeKc2PlatformId(value) {
+  if (typeof value === 'string' && /^-?\d+$/.test(value.trim())) value = Number(value);
+  if (!Number.isInteger(value) || value < KC2_PLATFORM_ID_MIN || value > KC2_PLATFORM_ID_MAX) {
+    throw identityError('platformId must be a registered SMALLINT');
+  }
+  return value;
+}
+function requireKc2PlatformId(input = {}) { return normalizeKc2PlatformId(input.platformId); }
+function normalizeKc2PlatformIdentity(input = {}) {
+  return { platformId: requireKc2PlatformId(input) };
+}
+function bindKc2AdapterPlatformIdentity(adapter = {}, input = {}) {
+  const platformId = normalizeKc2PlatformId(adapter.platformId);
+  return { ...input, platformId, subject: input.subject ? { ...input.subject, platformId } : input.subject };
+}
+function normalizeKc2HostObjectRef(input = {}) {
+  const platformId = normalizeKc2PlatformId(input.platformId);
+  const hostObjectKind = input.hostObjectKind == null || input.hostObjectKind === ''
+    ? null : String(input.hostObjectKind).trim();
+  if (hostObjectKind && !KC2_HOST_OBJECT_KINDS.includes(hostObjectKind)) {
+    throw identityError(`hostObjectKind is not recognized: ${hostObjectKind}`);
+  }
+  return {
+    hostObjectId: input.hostObjectId == null || input.hostObjectId === '' ? null : String(input.hostObjectId),
+    hostObjectKind,
+    kc2ArticleKey: input.kc2ArticleKey == null || input.kc2ArticleKey === ''
+      ? null : String(input.kc2ArticleKey).trim(),
+    platformId,
+  };
+}
+function normalizeKc2OpaqueActor(input = null) {
+  if (input == null) return null;
+  const kind = String(input.kind || '').trim();
+  if (!KC2_ACTOR_KINDS.includes(kind)) throw identityError('actor kind is not recognized');
+  const id = String(input.id || '').trim();
+  if (!id) throw identityError('actor.id is required');
+  return { id, kind };
+}
+function normalizeKc2OpaquePublicationIdentity(value) {
+  if (value == null || value === '') return null;
+  if (typeof value === 'object') value = value.publicationIdentity == null ? value.id : value.publicationIdentity;
+  return value == null || value === '' ? null : String(value);
+}
+function describeKc2PlatformIdentityModel() {
+  return {
+    deploymentIdRejected: true, environmentPropagationRejected: true, groupIdDistinct: true,
+    mutableGlobalCurrentPlatformRejected: true, platformIdIsPrimaryKey: true,
+    platformIdType: 'smallint', repositoryBoundHostConstant: true,
+    tenantIdentityOwner: 'external-login-authorization-system',
+  };
+}
+module.exports = {
+  KC2_ACTOR_KINDS, KC2_HOST_OBJECT_KINDS, KC2_PLATFORM_ID_MAX, KC2_PLATFORM_ID_MIN,
+  bindKc2AdapterPlatformIdentity, describeKc2PlatformIdentityModel,
+  normalizeKc2HostObjectRef, normalizeKc2OpaqueActor, normalizeKc2OpaquePublicationIdentity,
+  normalizeKc2PlatformId, normalizeKc2PlatformIdentity, requireKc2PlatformId,
+};

package/src/platform/kc2SignalContract.js

@@ -0,0 +1,23 @@
+'use strict';
+const { normalizeKc2PlatformIdentity } = require('./kc2PlatformIdentity');
+const KC2_SIGNAL_CONTRACT_VERSION = 'kc2-signal.v1';
+const KC2_SIGNAL_FORBIDDEN_KEYS = Object.freeze(['generate', 'generationRequired', 'publish', 'regenerate', 'runAudit', 'stale', 'workRequired']);
+function rejectPolicyFields(input) {
+  for (const key of KC2_SIGNAL_FORBIDDEN_KEYS) if (input && Object.hasOwn(input, key)) {
+    const error = new Error(`signal must not include KC2 policy field ${key}`); error.code = 'kc2-platform-observation-failed'; throw error;
+  }
+}
+function normalizeKc2ChangeSignal(input = {}) {
+  rejectPolicyFields(input);
+  if (input.contractVersion != null && input.contractVersion !== KC2_SIGNAL_CONTRACT_VERSION) {
+    const error = new Error(`unsupported signal contract version ${input.contractVersion}`); error.code = 'kc2-platform-observation-failed'; throw error;
+  }
+  const { platformId } = normalizeKc2PlatformIdentity(input);
+  const signalId = String(input.signalId || input.correlationKey || '').trim();
+  if (!signalId) { const error = new Error('signalId or correlationKey is required'); error.code = 'kc2-platform-identity-unresolved'; throw error; }
+  return { changeCategories: Array.isArray(input.changeCategories) ? input.changeCategories.slice() : [], changedScope: Array.isArray(input.changedScope) ? input.changedScope.slice() : [], contractVersion: KC2_SIGNAL_CONTRACT_VERSION, correlationKey: input.correlationKey == null ? signalId : String(input.correlationKey), observedAt: input.observedAt == null ? null : String(input.observedAt), observedRevision: input.observedRevision == null ? null : String(input.observedRevision), observationFingerprint: input.observationFingerprint == null ? null : String(input.observationFingerprint), platformId, priorRevision: input.priorRevision == null ? null : String(input.priorRevision), signalId };
+}
+function describeKc2SignalSemantics() {
+  return { advisoryOnly: true, broadOrPartialScopeValid: true, doesNotCauseGeneration: true, doesNotCausePublication: true, doesNotMutateCanonicalState: true, doesNotReplaceObserve: true, duplicateSignalsSafe: true, missingSignalsValid: true, outOfOrderSignalsSafe: true, pollOnlyHostValid: true };
+}
+module.exports = { KC2_SIGNAL_CONTRACT_VERSION, KC2_SIGNAL_FORBIDDEN_KEYS, describeKc2SignalSemantics, normalizeKc2ChangeSignal };

package/src/reconciliation/kc2ReconciliationContract.js

@@ -0,0 +1,13 @@
+'use strict';
+
+// Wire vocabulary only. Reconciliation planning, validation, and execution
+// remain KC2 server implementation.
+const KC2_RECONCILIATION_CONTRACT_VERSION = 'kc2-reconciliation.v1';
+const EVIDENCE_REF_KIND = Object.freeze(['sep', 'implementation', 'neighbor', 'policy', 'identity-label']);
+const REQUIRED_PROGRESSIVE_DEPTH_LAYERS = Object.freeze(['summary', 'details', 'deepDive']);
+
+module.exports = {
+  EVIDENCE_REF_KIND,
+  KC2_RECONCILIATION_CONTRACT_VERSION,
+  REQUIRED_PROGRESSIVE_DEPTH_LAYERS,
+};

package/src/reconciliation/kc2ReconciliationStageContracts.js

@@ -0,0 +1,11 @@
+'use strict';
+const KC2_RECONCILIATION_DECISION_CONTRACT_VERSION = 'kc2-reconciliation-decision.v1';
+const KC2_RECONCILIATION_ARTICLE_CONTRACT_VERSION = 'kc2-reconciliation-article.v1';
+const KC2_RECONCILIATION_DECISION_CONTRACT_VERSION_V2 = 'kc2-reconciliation-decision.v2';
+const KC2_RECONCILIATION_ARTICLE_CONTRACT_VERSION_V2 = 'kc2-reconciliation-article.v2';
+module.exports = {
+  KC2_RECONCILIATION_ARTICLE_CONTRACT_VERSION,
+  KC2_RECONCILIATION_ARTICLE_CONTRACT_VERSION_V2,
+  KC2_RECONCILIATION_DECISION_CONTRACT_VERSION,
+  KC2_RECONCILIATION_DECISION_CONTRACT_VERSION_V2,
+};

package/src/reconciliation/stageArtifactEnvelope.js

@@ -0,0 +1,17 @@
+'use strict';
+
+// Envelope vocabulary only. Artifact validation and lifecycle remain server-side.
+const ARTIFACT_ROLE = Object.freeze({
+  CANDIDATE: 'candidate',
+  CANONICAL: 'canonical',
+});
+
+const ARTIFACT_CURRENCY = Object.freeze({
+  CURRENT: 'current',
+  SUPERSEDED: 'superseded',
+});
+
+module.exports = {
+  ARTIFACT_CURRENCY,
+  ARTIFACT_ROLE,
+};

package/src/relationships/articleRelationshipContracts.js

@@ -0,0 +1,8 @@
+'use strict';
+const KC2_ARTICLE_RELATIONSHIP_ROLES = Object.freeze(['related', 'next-step', 'prerequisite', 'alternative', 'manage', 'supporting']);
+const KC2_ARTICLE_RELATIONSHIP_DEFAULT_ROLE = 'related';
+const KC2_ARTICLE_RELATIONSHIP_STATUSES = Object.freeze({ ACCEPTED: 'accepted' });
+const KC2_ARTICLE_RELATIONSHIP_SOURCE = 'operator-relationship-curation';
+const KC2_ARTICLE_RELATIONSHIP_ID_PREFIX = 'kar-';
+const KC2_ARTICLE_RELATIONSHIP_DISMISSAL_ID_PREFIX = 'kard-';
+module.exports = { KC2_ARTICLE_RELATIONSHIP_DEFAULT_ROLE, KC2_ARTICLE_RELATIONSHIP_DISMISSAL_ID_PREFIX, KC2_ARTICLE_RELATIONSHIP_ID_PREFIX, KC2_ARTICLE_RELATIONSHIP_ROLES, KC2_ARTICLE_RELATIONSHIP_SOURCE, KC2_ARTICLE_RELATIONSHIP_STATUSES };

package/src/transport/requestJson.js

@@ -0,0 +1,79 @@
+'use strict';
+
+const http = require('node:http');
+const https = require('node:https');
+const { URL } = require('node:url');
+const Kc2ClientError = require('../errors/Kc2ClientError');
+
+const DEFAULT_TIMEOUT_MS = 10000;
+
+function requestJson({
+  body = null,
+  method = 'GET',
+  rejectUnauthorized = false,
+  timeoutMs = DEFAULT_TIMEOUT_MS,
+  url,
+} = {}) {
+  return new Promise((resolve, reject) => {
+    let parsed;
+    try {
+      parsed = new URL(url);
+    } catch (cause) {
+      reject(new Kc2ClientError('KC2 client URL is invalid', {
+        code: 'kc2-client-invalid-url',
+        cause,
+      }));
+      return;
+    }
+    const transport = parsed.protocol === 'https:' ? https : http;
+    const payload = body == null ? '' : JSON.stringify(body);
+    const request = transport.request({
+      hostname: parsed.hostname,
+      method,
+      path: `${parsed.pathname}${parsed.search}`,
+      port: parsed.port,
+      rejectUnauthorized,
+      headers: {
+        Accept: 'application/json',
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(payload),
+      },
+    }, (response) => {
+      const chunks = [];
+      response.on('data', (chunk) => chunks.push(chunk));
+      response.on('end', () => {
+        const text = Buffer.concat(chunks).toString('utf8');
+        try {
+          resolve({
+            body: text ? JSON.parse(text) : null,
+            statusCode: response.statusCode,
+          });
+        } catch (cause) {
+          reject(new Kc2ClientError('KC2 client received non-JSON response', {
+            code: 'kc2-client-invalid-response',
+            statusCode: response.statusCode || 503,
+            cause,
+          }));
+        }
+      });
+    });
+    request.setTimeout(timeoutMs, () => {
+      request.destroy(new Kc2ClientError('KC2 client request timed out', {
+        code: 'kc2-client-timeout',
+      }));
+    });
+    request.on('error', (cause) => {
+      if (cause instanceof Kc2ClientError) {
+        reject(cause);
+        return;
+      }
+      reject(new Kc2ClientError('KC2 client request failed', { cause }));
+    });
+    request.end(payload);
+  });
+}
+
+module.exports = {
+  DEFAULT_TIMEOUT_MS,
+  requestJson,
+};