enigma-memory 0.1.9 → 0.1.11

package/docs/developer-ecosystem.md

@@ -2,30 +2,37 @@
 
 Enigma Memory is a local-first SDK, CLI, MCP server, and service-contract package. The developer surfaces are designed to be copied without secrets, cloud credentials, hidden local paths, or account identifiers.
 
-## CLI memory passport loop
+## Public test-drive loop
 
 For most developers, start with the installed CLI before reading the SDK internals or service contracts:
 
 ```sh
 npm install -g enigma-memory
-enigma setup --overwrite
+enigma test-drive --overwrite
 ```
 
-`enigma setup --overwrite` is the safe default. It writes local Enigma artifacts under the workspace `.enigma` path and emits deterministic, public-safe JSON without printing raw memory plaintext. It does not write third-party app configs.
+`enigma test-drive --overwrite` is zero-credential, local-only, and public-safe by default. It writes an isolated demo under `.enigma/test-drive`, keeps the default bundle inside that directory, emits one JSON summary, and does not print raw private memory plaintext. Use `--dry-run` to preview without writing or `--out-dir <path>` to choose another isolated demo directory.
+
+The test drive runs the local proof/demo path only: setup artifacts, search/status output, a cross-model demo report, and benchmark pointers. It does not call external providers, contact hosted Enigma SaaS, require OpenAI/Anthropic/Cloudflare credentials, create accounts, or write third-party client configs. Keep public claims bounded to local Enigma-controlled vault state, receipts, checkpoints, committed roots, exported bundle shape, and declared boundary operations.
 
-To let setup auto-detect installed or already-configured clients and report the connector plan without mutating client configs:
+To explicitly connect real local clients that are already installed or already configured:
 
 ```sh
-enigma setup --client auto --overwrite
+enigma setup --connect-installed --overwrite
 ```
 
-To explicitly write connector entries for installed/config-present clients only:
+`--connect-installed` implies auto selection, writes only for installed/config-present clients, and skips missing configs instead of creating every default client config. Only explicit write flags mutate client configs; `enigma connect <client>` without `--dry-run` remains the single-client write path, and existing `enigma setup --write-connectors` behavior for explicit/default clients is unchanged. Treat provider-native memory as non-canonical cache only; the local Enigma vault is canonical.
+
+## CLI memory passport loop
+
+After the public test drive, create a regular local workspace when you want day-to-day CLI usage:
 
 ```sh
-enigma setup --connect-installed --overwrite
+npm install -g enigma-memory
+enigma setup --overwrite
 ```
 
-`--client auto` selects clients found by connector detection and falls back to the default setup client list when none are present. The setup output lists selected clients, skipped clients, and skip reasons. `--connect-installed` implies auto selection, writes only for installed/config-present clients, and skips missing configs instead of creating every default client config. Only explicit write flags mutate client configs; `enigma connect <client>` without `--dry-run` remains the single-client write path, and existing `enigma setup --write-connectors` behavior for explicit/default clients is unchanged. Treat provider-native memory as non-canonical cache only; the local Enigma vault is canonical.
+`enigma setup --overwrite` is the safe default for a regular local workspace. It writes local Enigma artifacts under the workspace `.enigma` path and emits deterministic, public-safe JSON without printing raw memory plaintext. It does not write third-party app configs.
 
 After setup, use the same local vault from the CLI or connected clients:
 
@@ -60,15 +67,16 @@ The example app prints ids, counts, roots, and verification status only. It does
 
 ## CLI and CI loop
 
-The CI example installs Node 24, installs the published `enigma-memory@0.1.9` package, runs:
+The CI example installs Node 24, installs the published `enigma-memory@0.1.11` package, runs:
 
 ```sh
+npx --yes --package enigma-memory enigma test-drive --overwrite
 npx --yes --package enigma-memory enigma setup --overwrite
 npx --yes --package enigma-memory enigma doctor
 npm run benchmark:memory-suite -- --out benchmark-report.json
 ```
 
-and then runs a small ESM import smoke. It does not require GitHub secrets, cloud provider credentials, npm tokens, private bundles, local path assumptions, or official dataset network downloads in normal CI. The benchmark step writes a public-safe local JSON report using schema `enigma.memory_benchmark_suite.v1`; see the benchmark reproducibility guide for claim boundaries and the requirements for any future live third-party comparison.
+and then runs a small ESM import smoke. It does not require GitHub secrets, cloud provider credentials, npm tokens, private bundles, local path assumptions, hosted Enigma SaaS, external memory-provider calls, or official dataset network downloads in normal CI. The test-drive and benchmark steps write public-safe local JSON reports; see the benchmark reproducibility guide for claim boundaries and the requirements for any future live third-party comparison.
 
 The workflow also includes optional official-dataset benchmark preparation steps gated behind the manual `workflow_dispatch` input `run_standard_benchmark: true`. Normal `push` and `pull_request` runs skip them, so official dataset downloads are not required in normal CI. Enable the manual path only after the repository has reviewed network use and dataset-license handling:
 
@@ -84,7 +92,7 @@ Use the workflow as a template in a consumer repository. It is intentionally lim
 
 ## MCP client loop
 
-The same installed package can be used by Claude Desktop, Cursor, Kimi Code, or any generic MCP client. The smooth setup path is `enigma setup --client auto --overwrite` to plan detected clients, then `enigma setup --connect-installed --overwrite` only when you explicitly want setup to write installed/config-present client configs. Manual snippets remain useful when a client needs a copied entry; replace the bundle path with the local path from your setup output, and restart the client.
+The same installed package can be used by Claude Desktop, Cursor, Kimi Code, or any generic MCP client. Run `enigma test-drive --overwrite` first if you want a zero-credential local proof before touching real client configs. The smooth setup path is `enigma setup --client auto --overwrite` to plan detected clients, then `enigma setup --connect-installed --overwrite` only when you explicitly want setup to write installed/config-present client configs. Manual snippets remain useful when a client needs a copied entry; replace the bundle path with the local path from your setup output, and restart the client.
 
 Claude Desktop:
 

package/docs/hosted-cloud-product.md

@@ -10,6 +10,7 @@ The source package now has pure contract builders and validators in `packages/ho
 - tenant records;
 - hosted vault records;
 - API key metadata records;
+- API key lifecycle packets for issue/rotate/revoke/audit readiness;
 - usage billing records;
 - dashboard summaries;
 - backup drill records;
@@ -18,7 +19,7 @@ The source package now has pure contract builders and validators in `packages/ho
 
 These functions are contract and validation code only. They do not call an auth provider, billing provider, cloud deployment, KMS, backup target, support desk, status page, SIEM, or model provider. They are safe to import as package code because they do not start servers, read user files, mutate deployment state, publish packages, or contact external accounts.
 
-The lifecycle packet public API is `buildCustomerLifecyclePacket(input)` and `validateCustomerLifecyclePacket(packet)` under `enigma-memory/hosted-cloud`; the script command below emits the same schema for release evidence.
+The lifecycle packet public APIs are `buildCustomerLifecyclePacket(input)` / `validateCustomerLifecyclePacket(packet)` and `buildApiKeyLifecyclePacket(input)` / `validateApiKeyLifecyclePacket(packet)` under `enigma-memory/hosted-cloud`; the script commands below emit the same schemas for release evidence.
 
 The validators enforce hosted-cloud boundaries:
 
@@ -27,10 +28,11 @@ The validators enforce hosted-cloud boundaries:
 - raw memory, plaintext prompts, provider responses, transcripts, credential-looking values, token values, private keys, and API key secret material are rejected;
 - financial outcome claims, token ROI/profit claims, provider-side deletion claims, and model-forgetting claims are rejected;
 - API key contracts store identifiers, fingerprints, scopes, rotation refs, and timestamps only, not key material;
+- API key lifecycle packets store issue/rotate/revoke/audit evidence refs, event refs, fingerprints, opaque subjects, readiness status, and operator approval refs only; they reject raw key material, provider payloads, customer memory, plaintext prompts, credentials, ROI claims, provider-deletion claims, and model-forgetting claims;
 - hosted vault contracts are opaque-record and plaintext-minimized contracts only;
 - billing records remain contract records until an external billing provider invoice flow is wired.
 
-Individual surface builders emit `readiness.contract_ready: true`, `readiness.integration_kind: "contract_validator_only"`, and `readiness.hosted_cloud_sellable: false` because contract readiness is not provider wiring, legal approval, security review, or operator go-live approval. A customer lifecycle packet may only mark `hosted_cloud_sellable: true` when every lifecycle surface has a provided evidence ref and an explicit operator go-live approval ref is supplied; the packet remains evidence validation, not live hosted SaaS or provider wiring.
+Individual surface builders emit `readiness.contract_ready: true`, `readiness.integration_kind: "contract_validator_only"`, and `readiness.hosted_cloud_sellable: false` because contract readiness is not provider wiring, legal approval, security review, or operator go-live approval. A customer lifecycle packet may only mark `hosted_cloud_sellable: true` when every lifecycle surface has a provided evidence ref and an explicit operator go-live approval ref is supplied; the packet remains evidence validation, not live hosted SaaS or provider wiring. An API key lifecycle packet keeps `customer_api_keys_live:false` by default and can become live-ready only when every required issue/rotate/revoke/audit evidence ref is provided and an operator approval ref is supplied. That live-ready state is still evidence validation only: it does not issue a customer API key, create a secret, call an auth provider, rotate/revoke a provider credential, or prove provider-side deletion.
 
 ## Externally blocked before hosted cloud can be sold
 
@@ -53,6 +55,14 @@ A `provided` operator evidence ref means the contract can point to external evid
 
 The lifecycle packet records lifecycle phases, required surfaces, external blockers, missing evidence refs, no-secret/no-plaintext guarantees, and the sellability gate. Missing surfaces, blocked evidence refs, or absent operator go-live approval keep `hosted_cloud_sellable:false`.
 
+## API key lifecycle packet
+
+`npm run production:hosted-api-key -- --tenant <id> --subject <opaque-subject-ref> --operation <issue|rotate|revoke|audit> --out <file>` builds `enigma.hosted_cloud.api_key_lifecycle_packet.v1` readiness evidence for one customer API key lifecycle operation. Operators may pass repeatable `--evidence-ref <phase=status:ref>` values for the phases required by that operation, plus `--operator-approval-ref <ref>` when a reviewed operator approval exists.
+
+The command writes public-safe validation evidence only. It must not receive or print raw API keys, bearer tokens, credentials, provider response bodies, plaintext prompts, raw memory, customer content, financial ROI claims, provider deletion claims, or model forgetting claims. It creates no hosted account, customer API key, provider secret, KMS key, rotation job, revocation job, audit export, invoice, support ticket, Cloudflare resource, provider resource, or deployment.
+
+The packet records lifecycle events, required evidence refs, missing evidence refs, malformed operation blockers, the operator approval ref, readiness status, `customer_api_keys_live`, and no-secret/no-plaintext guarantees. Missing evidence refs, blocked evidence refs, malformed operation surfaces, or absent operator approval keep `customer_api_keys_live:false`.
+
 ## Non-claims
 
 Hosted cloud collateral must not say or imply:

package/docs/sdk-api.md

@@ -1,6 +1,6 @@
 # SDK and API guide
 
-This guide covers the public package imports for `enigma-memory@0.1.9`. The SDK runs locally by default: vaults, passports, context packs, receipts, relay/gateway demo state, storage contracts, metering artifacts, and settlement artifacts are package-level developer surfaces. They are not evidence of hosted Enigma cloud, provider-side deletion, provider model forgetting, token ROI, invoice savings, compliance certification, or benchmark leadership.
+This guide covers the public package imports for `enigma-memory@0.1.11`. The SDK runs locally by default: vaults, passports, context packs, receipts, relay/gateway demo state, storage contracts, metering artifacts, settlement artifacts, and hosted-cloud contract packets are package-level developer surfaces. They are not evidence of hosted Enigma cloud, live customer API key issuance, provider-side deletion, provider model forgetting, token ROI, invoice savings, compliance certification, or benchmark leadership.
 
 ## Install and import style
 
@@ -157,6 +157,27 @@ const job = createPermissionlessMemoryJob({
 });
 ```
 
+### `enigma-memory/hosted-cloud`
+
+The hosted-cloud module emits public-safe contract/readiness evidence only. Customer API key lifecycle packets model issue, rotate, revoke, and audit readiness with evidence refs, opaque subject refs, fingerprints, missing-evidence refs, readiness status, and operator approval refs. They never contain raw key material, provider payloads, plaintext prompts, raw memory, credentials, ROI claims, provider deletion claims, or model forgetting claims.
+
+```js
+import {
+  buildApiKeyLifecyclePacket,
+  validateApiKeyLifecyclePacket,
+} from 'enigma-memory/hosted-cloud';
+
+const packet = buildApiKeyLifecyclePacket({
+  tenant_id: 'tenant-alpha',
+  subject_ref: 'subject-ref-alpha',
+  environment: 'production',
+  operation: 'audit',
+});
+const valid = validateApiKeyLifecyclePacket(packet);
+```
+
+`customer_api_keys_live` stays `false` unless the issue/rotate/revoke/audit evidence refs are complete and an operator approval ref is supplied. Even then, the packet is readiness evidence validation only; it does not issue a key, create a secret, call KMS or auth providers, rotate or revoke a provider credential, or prove provider-side deletion.
+
 ## Verifying exported proof
 
 Package consumers should verify exported bundles through the CLI or MCP verifier rather than importing source-only verifier internals. Treat full bundles as private unless you have reviewed and removed local import key material before sharing:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "enigma-memory",
-  "version": "0.1.9",
+  "version": "0.1.11",
   "type": "module",
   "description": "Provider-agnostic AI memory passport and offline-verifiable proof layer.",
   "license": "Apache-2.0",
@@ -85,6 +85,7 @@
     "scripts/collect-hosted-backend-live-evidence.mjs",
     "scripts/build-hosted-probe-worker.mjs",
     "scripts/build-hosted-customer-lifecycle.mjs",
+    "scripts/build-hosted-api-key-lifecycle.mjs",
     "scripts/build-edge-backend-workers.mjs",
     "scripts/validate-cloudflare-worker-inspect.mjs",
     "scripts/validate-production-manifests.mjs",
@@ -177,6 +178,7 @@
     "production:edge-live": "node scripts/collect-edge-backend-bootstrap-evidence.mjs",
     "production:ref-draft": "node scripts/build-hosted-ref-draft.mjs",
     "production:hosted-customer": "node scripts/build-hosted-customer-lifecycle.mjs",
+    "production:hosted-api-key": "node scripts/build-hosted-api-key-lifecycle.mjs",
     "production:storage-bootstrap": "node scripts/cloudflare-storage-bootstrap.mjs",
     "production:worker-inspect": "node scripts/validate-cloudflare-worker-inspect.mjs",
     "production:cloudflare-credentials": "node scripts/validate-cloudflare-credentials.mjs",

package/packages/hosted-cloud/src/index.js

@@ -9,6 +9,7 @@ export const HOSTED_CLOUD_DASHBOARD_SCHEMA = 'enigma.hosted_cloud.dashboard_summ
 export const HOSTED_CLOUD_BACKUP_DRILL_SCHEMA = 'enigma.hosted_cloud.backup_drill.v1';
 export const HOSTED_CLOUD_INCIDENT_SLA_SCHEMA = 'enigma.hosted_cloud.incident_sla_refs.v1';
 export const HOSTED_CLOUD_CUSTOMER_LIFECYCLE_PACKET_SCHEMA = 'enigma.hosted_cloud.customer_lifecycle_packet.v1';
+export const HOSTED_CLOUD_API_KEY_LIFECYCLE_PACKET_SCHEMA = 'enigma.hosted_cloud.api_key_lifecycle_packet.v1';
 
 export const HOSTED_CLOUD_EXTERNAL_BLOCKERS = Object.freeze([
   'auth_provider',
@@ -63,6 +64,23 @@ const CUSTOMER_LIFECYCLE_CONTRACT_PHASES = Object.freeze([
   'incident_sla',
 ]);
 const CUSTOMER_LIFECYCLE_REQUIRED_EVIDENCE_PHASES = Object.freeze(HOSTED_CLOUD_CUSTOMER_LIFECYCLE_PHASES.filter((phase) => phase !== 'operator_go_live'));
+export const HOSTED_CLOUD_API_KEY_LIFECYCLE_OPERATIONS = Object.freeze(['issue', 'rotate', 'revoke', 'audit']);
+export const HOSTED_CLOUD_API_KEY_LIFECYCLE_PHASES = Object.freeze([
+  'current_key_metadata',
+  'next_key_metadata',
+  'revoked_key_metadata',
+  'issue_policy',
+  'rotation_policy',
+  'revocation_policy',
+  'audit_log',
+]);
+const API_KEY_LIFECYCLE_OPERATION_PHASES = Object.freeze({
+  issue: Object.freeze(['next_key_metadata', 'issue_policy', 'audit_log']),
+  rotate: Object.freeze(['current_key_metadata', 'next_key_metadata', 'rotation_policy', 'audit_log']),
+  revoke: Object.freeze(['current_key_metadata', 'revoked_key_metadata', 'revocation_policy', 'audit_log']),
+  audit: Object.freeze(['current_key_metadata', 'audit_log']),
+});
+const API_KEY_LIFECYCLE_KEY_SLOTS = Object.freeze(['current', 'next', 'revoked']);
 const CUSTOMER_LIFECYCLE_BLOCKER_LABELS = Object.freeze({
   account: 'Hosted account contract evidence is not provided.',
   tenant: 'Hosted tenant contract evidence is not provided.',
@@ -78,8 +96,19 @@ const CUSTOMER_LIFECYCLE_BLOCKER_LABELS = Object.freeze({
   security_review: 'Hosted security review evidence is not provided.',
   operator_go_live: 'Explicit operator go-live approval is not provided.',
 });
+const API_KEY_LIFECYCLE_BLOCKER_LABELS = Object.freeze({
+  current_key_metadata: 'Current hosted API key metadata evidence is not provided.',
+  next_key_metadata: 'Next hosted API key metadata evidence is not provided.',
+  revoked_key_metadata: 'Revoked hosted API key metadata evidence is not provided.',
+  issue_policy: 'Hosted API key issue policy evidence is not provided.',
+  rotation_policy: 'Hosted API key rotation policy evidence is not provided.',
+  revocation_policy: 'Hosted API key revocation policy evidence is not provided.',
+  audit_log: 'Hosted API key lifecycle audit evidence is not provided.',
+  operator_approval: 'Explicit public-safe operator API key lifecycle approval is not provided.',
+});
+const API_KEY_SECRET_MATERIAL_KEY_RE = /(?:^|_)(?:raw_?api_?key|raw_?key|plaintext_?api_?key|plain_text_?api_?key|plaintext_?key|plain_text_?key|api_?key_?value|key_?value|key_?material|secret_?key|key_?secret|value)(?:$|_)/iu;
 const FORBIDDEN_KEY_RE = /(?:^|_)(?:raw_?memory|plaintext|plain_text|prompt|prompts|completion|completions|message_body|transcript|conversation|provider_?response|response_?body|credential|credentials|secret|password|private_?key|bearer|access_token|refresh_token|token_value|api_key_value|api_secret|token_?roi|token_?profit|roi_claim|profit_claim|provider_?deletion|provider_?erasure|model_?forgetting|model_?erasure)(?:$|_)/iu;
-const SECRET_VALUE_RE = /(?:Bearer\s+[A-Za-z0-9._~+/=-]{12,}|Basic\s+[A-Za-z0-9+/=-]{12,}|-----BEGIN [A-Z ]*PRIVATE KEY-----|https?:\/\/[^\s/@]+:[^\s/@]+@|sk-[A-Za-z0-9_-]{16,}|AKIA[0-9A-Z]{16}|raw memory|private prompt|provider response|full transcript|decrypted memory)/iu;
+const SECRET_VALUE_RE = /(?:Bearer\s+[A-Za-z0-9._~+/=-]{12,}|Basic\s+[A-Za-z0-9+/=-]{12,}|-----BEGIN [A-Z ]*PRIVATE KEY-----|https?:\/\/[^\s/@]+:[^\s/@]+@|sk-[A-Za-z0-9_-]{16,}|AKIA[0-9A-Z]{16}|\b(?:raw memory|plaintext prompts?|plain text prompts?|private prompts?|provider responses?|full transcript|decrypted memory|credentials?|secrets?|passwords?|private keys?|api key secret|api secrets?|access tokens?|refresh tokens?|token values?|credential material)\b)/iu;
 const FORBIDDEN_CLAIM_RE = /(?:token\s+(?:roi|profit|return|investment|price)|(?:roi|profit|return)\s+(?:from|on)\s+token|guaranteed\s+(?:savings|profit|return)|provider(?:-side|\s+side)?\s+(?:deletion|erasure)|model\s+(?:forgetting|forgot|erasure)|makes?\s+models?\s+forget|deleted\s+from\s+every\s+provider)/iu;
 
 function isPlainObject(value) {
@@ -880,7 +909,7 @@ function validateCustomerLifecycleEvidenceRefs(requiredEvidenceRefs) {
 function validateCustomerLifecycleContracts(contracts) {
   if (!isPlainObject(contracts)) throw new TypeError('contracts must be present');
   for (const phase of CUSTOMER_LIFECYCLE_CONTRACT_PHASES) {
-    if (!Object.prototype.hasOwnProperty.call(contracts, phase)) throw new TypeError(`contracts.${phase} must be present`);
+    if (!Object.prototype.hasOwnProperty.call(contracts, phase)) throw new TypeError(`contracts.${phase} must be present; missing_surface_refs must match contracts`);
     const contract = contracts[phase];
     if (contract === null) continue;
     if (!isPlainObject(contract)) throw new TypeError(`contracts.${phase} must be an object or null`);
@@ -982,3 +1011,392 @@ export function validateCustomerLifecyclePacket(packet) {
   validateCustomerLifecycleSafetyGuarantees(packet.guarantees ?? packet.public_safety_guarantees);
   return true;
 }
+
+function assertNoApiKeySecretMaterial(value, path = 'api_key_lifecycle') {
+  if (Array.isArray(value)) {
+    value.forEach((item, index) => assertNoApiKeySecretMaterial(item, `${path}[${index}]`));
+    return;
+  }
+  if (!isPlainObject(value)) return;
+  for (const [key, child] of Object.entries(value)) {
+    const allowedBoundaryKey = key === 'key_material_boundary' || key === 'key_material_in_contract' || key === 'api_key_material_absent';
+    const keyMetadataContext = /(?:^|\.)(?:current|next|revoked|current_key|currentKey|current_api_key|currentApiKey|next_key|nextKey|next_api_key|nextApiKey|revoked_key|revokedKey|revoked_api_key|revokedApiKey|key_contracts\.(?:current|next|revoked)|keyContracts\.(?:current|next|revoked)|key_metadata_contracts\.(?:current|next|revoked)|keyMetadataContracts\.(?:current|next|revoked)|contracts\.(?:current|next|revoked))$/u.test(path);
+    const bareSecretKey = key === 'api_key' || key === 'apiKey' || (keyMetadataContext && key === 'key');
+    if (!allowedBoundaryKey && (bareSecretKey || API_KEY_SECRET_MATERIAL_KEY_RE.test(key))) {
+      throw new TypeError(`${path}.${key} is not allowed in API key lifecycle packets`);
+    }
+    assertNoApiKeySecretMaterial(child, `${path}.${key}`);
+  }
+}
+
+function apiKeyLifecycleOperation(input) {
+  const operation = requiredString(input.operation, 'operation');
+  if (!HOSTED_CLOUD_API_KEY_LIFECYCLE_OPERATIONS.includes(operation)) {
+    throw new TypeError(`operation must be one of ${HOSTED_CLOUD_API_KEY_LIFECYCLE_OPERATIONS.join(', ')}`);
+  }
+  return operation;
+}
+
+function apiKeyLifecycleRequiredPhases(operation) {
+  return API_KEY_LIFECYCLE_OPERATION_PHASES[operation];
+}
+
+function apiKeyLifecycleSlotAliases(slot) {
+  switch (slot) {
+    case 'current':
+      return ['current', 'current_key', 'currentKey', 'current_api_key', 'currentApiKey', 'current_key_contract', 'currentKeyContract', 'current_api_key_contract', 'currentApiKeyContract'];
+    case 'next':
+      return ['next', 'next_key', 'nextKey', 'next_api_key', 'nextApiKey', 'next_key_contract', 'nextKeyContract', 'next_api_key_contract', 'nextApiKeyContract'];
+    case 'revoked':
+      return ['revoked', 'revoked_key', 'revokedKey', 'revoked_api_key', 'revokedApiKey', 'revoked_key_contract', 'revokedKeyContract', 'revoked_api_key_contract', 'revokedApiKeyContract'];
+    default:
+      throw new TypeError(`unknown API key lifecycle slot: ${slot}`);
+  }
+}
+
+function apiKeyLifecycleContractSource(input, slot) {
+  const aliases = apiKeyLifecycleSlotAliases(slot);
+  const contractCollections = [
+    input.key_contracts,
+    input.keyContracts,
+    input.key_metadata_contracts,
+    input.keyMetadataContracts,
+    input.contracts,
+  ];
+  for (const collection of contractCollections) {
+    if (!isPlainObject(collection)) continue;
+    for (const alias of aliases) {
+      if (collection[alias] !== undefined) return collection[alias];
+    }
+  }
+  for (const alias of aliases) {
+    if (input[alias] !== undefined) return input[alias];
+  }
+  return undefined;
+}
+
+function validateApiKeyLifecycleContractTenantSubject(contract, tenantId, subjectRef, name) {
+  if (contract.tenant_id !== tenantId) throw new TypeError(`${name}.tenant_id must match packet tenant_id`);
+  if (contract.subject_ref !== subjectRef) throw new TypeError(`${name}.subject_ref must match packet subject_ref`);
+}
+
+function buildOrValidateApiKeyLifecycleContract(slot, source, tenantId, subjectRef, generatedAt) {
+  if (source === undefined || source === null) return null;
+  if (!isPlainObject(source)) throw new TypeError(`key_contracts.${slot} must be an object`);
+  const name = `key_contracts.${slot}`;
+  if (source.schema === HOSTED_CLOUD_API_KEY_SCHEMA) {
+    validateApiKeyContract(source);
+    validateApiKeyLifecycleContractTenantSubject(source, tenantId, subjectRef, name);
+    return source;
+  }
+  const contract = buildApiKeyContract({
+    ...source,
+    tenant_id: source.tenant_id ?? source.tenantId ?? tenantId,
+    subject_ref: source.subject_ref ?? source.subjectRef ?? subjectRef,
+    generated_at: source.generated_at ?? source.generatedAt ?? generatedAt,
+  });
+  validateApiKeyLifecycleContractTenantSubject(contract, tenantId, subjectRef, name);
+  return contract;
+}
+
+function apiKeyLifecycleContractsFrom(input, tenantId, subjectRef, generatedAt) {
+  return Object.fromEntries(API_KEY_LIFECYCLE_KEY_SLOTS.map((slot) => [
+    slot,
+    buildOrValidateApiKeyLifecycleContract(slot, apiKeyLifecycleContractSource(input, slot), tenantId, subjectRef, generatedAt),
+  ]));
+}
+
+function explicitApiKeyLifecycleEvidenceRefs(input) {
+  const refs = input.required_evidence_refs ?? input.requiredEvidenceRefs ?? input.api_key_evidence_refs ?? input.apiKeyEvidenceRefs ?? input.lifecycle_evidence_refs ?? input.lifecycleEvidenceRefs ?? input.evidence_refs ?? input.evidenceRefs;
+  if (refs === undefined || refs === null) return {};
+  if (!isPlainObject(refs)) throw new TypeError('required_evidence_refs must be an object');
+  return refs;
+}
+
+function apiKeyLifecycleEvidenceRefFor(phase, value) {
+  const fallback = { ref: `blocked:${phase}`, status: BLOCKED, blocker: API_KEY_LIFECYCLE_BLOCKER_LABELS[phase] };
+  if (value === undefined || value === null) return fallback;
+  if (typeof value === 'string') return { ref: requirePublicSafeLifecycleRef(value, `required_evidence_refs.${phase}`), status: PROVIDED };
+  if (!isPlainObject(value)) throw new TypeError(`required_evidence_refs.${phase} must be a string or object`);
+  const status = stringOrDefault(value.status, PROVIDED);
+  if (!EVIDENCE_STATUSES.has(status)) throw new TypeError(`required_evidence_refs.${phase}.status is invalid`);
+  const ref = status === PROVIDED
+    ? requirePublicSafeLifecycleRef(value.ref, `required_evidence_refs.${phase}.ref`)
+    : requiredString(value.ref, `required_evidence_refs.${phase}.ref`);
+  assertNoForbiddenPayload(ref, `required_evidence_refs.${phase}.ref`);
+  assertNoApiKeySecretMaterial(ref, `required_evidence_refs.${phase}.ref`);
+  const evidence = { ref, status };
+  const owner = optionalString(value.owner, `required_evidence_refs.${phase}.owner`);
+  const blocker = optionalString(value.blocker, `required_evidence_refs.${phase}.blocker`);
+  const contractSchema = optionalString(value.contract_schema, `required_evidence_refs.${phase}.contract_schema`);
+  const contractId = optionalString(value.contract_id, `required_evidence_refs.${phase}.contract_id`);
+  if (owner) evidence.owner = owner;
+  if (contractSchema) evidence.contract_schema = contractSchema;
+  if (contractId) evidence.contract_id = contractId;
+  if (status === BLOCKED) evidence.blocker = blocker ?? API_KEY_LIFECYCLE_BLOCKER_LABELS[phase];
+  return evidence;
+}
+
+function apiKeyLifecycleSlotForPhase(phase) {
+  switch (phase) {
+    case 'current_key_metadata':
+      return 'current';
+    case 'next_key_metadata':
+      return 'next';
+    case 'revoked_key_metadata':
+      return 'revoked';
+    default:
+      return null;
+  }
+}
+
+function apiKeyLifecycleContractEvidenceRef(phase, contract) {
+  if (!contract) return apiKeyLifecycleEvidenceRefFor(phase, undefined);
+  return {
+    ref: requiredString(contract.contract_hash, `key_contracts.${apiKeyLifecycleSlotForPhase(phase)}.contract_hash`),
+    status: PROVIDED,
+    contract_schema: requiredString(contract.schema, `key_contracts.${apiKeyLifecycleSlotForPhase(phase)}.schema`),
+    contract_id: requiredString(contract.api_key_id, `key_contracts.${apiKeyLifecycleSlotForPhase(phase)}.api_key_id`),
+  };
+}
+
+function apiKeyLifecycleEvidenceRefsFrom(input, operation, keyContracts) {
+  const explicitRefs = explicitApiKeyLifecycleEvidenceRefs(input);
+  const requiredPhases = apiKeyLifecycleRequiredPhases(operation);
+  const evidenceRefs = {};
+  for (const phase of requiredPhases) {
+    const slot = apiKeyLifecycleSlotForPhase(phase);
+    evidenceRefs[phase] = explicitRefs[phase] === undefined && slot !== null
+      ? apiKeyLifecycleContractEvidenceRef(phase, keyContracts[slot])
+      : apiKeyLifecycleEvidenceRefFor(phase, explicitRefs[phase]);
+  }
+  return evidenceRefs;
+}
+
+function apiKeyLifecycleOperatorApprovalRefFromInput(input) {
+  const value = input.operator_approval_ref ?? input.operatorApprovalRef ?? input.operator_go_live_ref ?? input.operatorGoLiveRef;
+  if (value === undefined || value === null) return null;
+  return requirePublicSafeLifecycleRef(value, 'operator_approval_ref');
+}
+
+function apiKeyLifecycleOperatorApprovalRefFromPacket(packet) {
+  if (!Object.prototype.hasOwnProperty.call(packet, 'operator_approval_ref')) throw new TypeError('operator_approval_ref must be present');
+  if (packet.operator_approval_ref === null) return null;
+  return requirePublicSafeLifecycleRef(packet.operator_approval_ref, 'operator_approval_ref');
+}
+
+function missingApiKeyLifecycleEvidenceRefs(requiredEvidenceRefs, operation) {
+  return apiKeyLifecycleRequiredPhases(operation)
+    .filter((phase) => requiredEvidenceRefs[phase].status !== PROVIDED)
+    .map((phase) => ({
+      key: phase,
+      ref: requiredEvidenceRefs[phase].ref,
+      blocker: requiredEvidenceRefs[phase].blocker ?? API_KEY_LIFECYCLE_BLOCKER_LABELS[phase],
+    }));
+}
+
+function apiKeyLifecycleExternalBlockers(requiredEvidenceRefs, operation, operatorApprovalRef) {
+  const blockers = missingApiKeyLifecycleEvidenceRefs(requiredEvidenceRefs, operation);
+  if (operatorApprovalRef === null) {
+    blockers.push({
+      key: 'operator_approval',
+      ref: 'blocked:operator_approval',
+      blocker: API_KEY_LIFECYCLE_BLOCKER_LABELS.operator_approval,
+    });
+  }
+  return blockers;
+}
+
+function apiKeyLifecycleReadiness(operation, requiredEvidenceRefs, operatorApprovalRef) {
+  const missingEvidenceRefs = missingApiKeyLifecycleEvidenceRefs(requiredEvidenceRefs, operation);
+  const externalLifecycleBlockers = apiKeyLifecycleExternalBlockers(requiredEvidenceRefs, operation, operatorApprovalRef);
+  const evidenceApproved = missingEvidenceRefs.length === 0 && operatorApprovalRef !== null;
+  return {
+    ...HOSTED_CLOUD_CONTRACT_READY,
+    operation,
+    status: evidenceApproved ? 'operator_approved_api_key_lifecycle_evidence' : 'blocked_api_key_lifecycle_evidence_or_operator_approval',
+    evidence_validation_only: true,
+    no_provider_wiring: true,
+    actual_key_issuance: false,
+    lifecycle_evidence_complete: missingEvidenceRefs.length === 0,
+    operator_approval_provided: operatorApprovalRef !== null,
+    external_wiring_ready: externalLifecycleBlockers.length === 0,
+    customer_api_keys_live: evidenceApproved,
+    live_readiness_gate: evidenceApproved ? 'evidence_complete_operator_approved' : 'blocked_until_lifecycle_evidence_and_operator_approval',
+    external_blockers: externalLifecycleBlockers,
+    missing_evidence_refs: missingEvidenceRefs,
+  };
+}
+
+function apiKeyLifecycleKeyMetadataRefs(operation, requiredEvidenceRefs) {
+  const requiredPhases = apiKeyLifecycleRequiredPhases(operation);
+  return Object.fromEntries(API_KEY_LIFECYCLE_KEY_SLOTS.map((slot) => {
+    const phase = `${slot}_key_metadata`;
+    return [slot, requiredPhases.includes(phase) ? requiredEvidenceRefs[phase] : null];
+  }));
+}
+
+function apiKeyLifecycleEvents(operation, requiredEvidenceRefs, keyContracts) {
+  return apiKeyLifecycleRequiredPhases(operation).map((phase) => {
+    const evidence = requiredEvidenceRefs[phase];
+    const event = {
+      operation,
+      phase,
+      evidence_ref: evidence.ref,
+      evidence_status: evidence.status,
+      ready: evidence.status === PROVIDED,
+    };
+    if (evidence.status === BLOCKED) event.blocker = evidence.blocker ?? API_KEY_LIFECYCLE_BLOCKER_LABELS[phase];
+    const slot = apiKeyLifecycleSlotForPhase(phase);
+    if (slot !== null && keyContracts[slot]) {
+      event.key_slot = slot;
+      event.contract_schema = keyContracts[slot].schema;
+      event.contract_id = keyContracts[slot].api_key_id;
+      event.contract_hash = keyContracts[slot].contract_hash;
+    }
+    return event;
+  });
+}
+
+function apiKeyLifecycleSafetyGuarantees() {
+  return {
+    opaque_reference_only: true,
+    customer_content_absent: true,
+    sensitive_text_absent: true,
+    auth_material_absent: true,
+    api_key_material_absent: true,
+    provider_payloads_absent: true,
+    provider_wiring_absent: true,
+    evidence_validation_only: true,
+    actual_key_issuance_absent: true,
+    financial_outcome_claim_absent: true,
+    remote_erasure_claim_absent: true,
+  };
+}
+
+function validateApiKeyLifecycleSafetyGuarantees(guarantees) {
+  if (!isPlainObject(guarantees)) throw new TypeError('public_safety_guarantees must be present');
+  requiredTrue(guarantees.opaque_reference_only, 'public_safety_guarantees.opaque_reference_only');
+  requiredTrue(guarantees.customer_content_absent, 'public_safety_guarantees.customer_content_absent');
+  requiredTrue(guarantees.sensitive_text_absent, 'public_safety_guarantees.sensitive_text_absent');
+  requiredTrue(guarantees.auth_material_absent, 'public_safety_guarantees.auth_material_absent');
+  requiredTrue(guarantees.api_key_material_absent, 'public_safety_guarantees.api_key_material_absent');
+  requiredTrue(guarantees.provider_payloads_absent, 'public_safety_guarantees.provider_payloads_absent');
+  requiredTrue(guarantees.provider_wiring_absent, 'public_safety_guarantees.provider_wiring_absent');
+  requiredTrue(guarantees.evidence_validation_only, 'public_safety_guarantees.evidence_validation_only');
+  requiredTrue(guarantees.actual_key_issuance_absent, 'public_safety_guarantees.actual_key_issuance_absent');
+  requiredTrue(guarantees.financial_outcome_claim_absent, 'public_safety_guarantees.financial_outcome_claim_absent');
+  requiredTrue(guarantees.remote_erasure_claim_absent, 'public_safety_guarantees.remote_erasure_claim_absent');
+}
+
+function validateApiKeyLifecycleContracts(keyContracts, tenantId, subjectRef) {
+  if (!isPlainObject(keyContracts)) throw new TypeError('key_contracts must be present');
+  for (const slot of API_KEY_LIFECYCLE_KEY_SLOTS) {
+    if (!Object.prototype.hasOwnProperty.call(keyContracts, slot)) throw new TypeError(`key_contracts.${slot} must be present`);
+    const contract = keyContracts[slot];
+    if (contract === null) continue;
+    if (!isPlainObject(contract)) throw new TypeError(`key_contracts.${slot} must be an object or null`);
+    validateApiKeyContract(contract);
+    validateApiKeyLifecycleContractTenantSubject(contract, tenantId, subjectRef, `key_contracts.${slot}`);
+  }
+}
+
+function validateApiKeyLifecycleEvidenceRefs(requiredEvidenceRefs, operation) {
+  if (!isPlainObject(requiredEvidenceRefs)) throw new TypeError('required_evidence_refs must be present');
+  const expectedPhases = apiKeyLifecycleRequiredPhases(operation);
+  for (const phase of Object.keys(requiredEvidenceRefs)) {
+    if (!expectedPhases.includes(phase)) throw new TypeError(`required_evidence_refs.${phase} is not required for ${operation}`);
+  }
+  const normalized = {};
+  for (const phase of expectedPhases) {
+    if (!Object.prototype.hasOwnProperty.call(requiredEvidenceRefs, phase)) throw new TypeError(`required_evidence_refs.${phase} must be present`);
+    normalized[phase] = apiKeyLifecycleEvidenceRefFor(phase, requiredEvidenceRefs[phase]);
+  }
+  return normalized;
+}
+
+function assertSameLifecycleObject(actual, expected, name) {
+  if (!isPlainObject(actual)) throw new TypeError(`${name} must be an object`);
+  if (JSON.stringify(canonicalize(actual)) !== JSON.stringify(canonicalize(expected))) throw new TypeError(`${name} must match API key lifecycle evidence`);
+}
+
+function validateApiKeyLifecycleReadiness(readiness, expected) {
+  if (!isPlainObject(readiness)) throw new TypeError('readiness must be present');
+  requiredTrue(readiness.contract_ready, 'readiness.contract_ready');
+  if (readiness.integration_kind !== HOSTED_CLOUD_CONTRACT_READY.integration_kind) throw new TypeError('readiness.integration_kind must remain contract_validator_only');
+  requiredTrue(readiness.no_external_provider_calls, 'readiness.no_external_provider_calls');
+  if (readiness.operation !== expected.operation) throw new TypeError('readiness.operation must match operation');
+  if (readiness.status !== expected.status) throw new TypeError('readiness.status must match API key lifecycle evidence and operator approval');
+  requiredTrue(readiness.evidence_validation_only, 'readiness.evidence_validation_only');
+  requiredTrue(readiness.no_provider_wiring, 'readiness.no_provider_wiring');
+  requiredFalse(readiness.actual_key_issuance, 'readiness.actual_key_issuance');
+  if (readiness.lifecycle_evidence_complete !== expected.lifecycle_evidence_complete) throw new TypeError('readiness.lifecycle_evidence_complete must match required_evidence_refs');
+  if (readiness.operator_approval_provided !== expected.operator_approval_provided) throw new TypeError('readiness.operator_approval_provided must match operator_approval_ref');
+  if (readiness.external_wiring_ready !== expected.external_wiring_ready) throw new TypeError('readiness.external_wiring_ready must match blockers');
+  if (readiness.customer_api_keys_live !== expected.customer_api_keys_live) throw new TypeError('readiness.customer_api_keys_live must match lifecycle evidence and operator approval');
+  if (readiness.live_readiness_gate !== expected.live_readiness_gate) throw new TypeError('readiness.live_readiness_gate must match lifecycle evidence and operator approval');
+  assertSameLifecycleArray(readiness.external_blockers, expected.external_blockers, 'readiness.external_blockers');
+  assertSameLifecycleArray(readiness.missing_evidence_refs, expected.missing_evidence_refs, 'readiness.missing_evidence_refs');
+}
+
+export function buildApiKeyLifecyclePacket(input = {}) {
+  if (!isPlainObject(input)) throw new TypeError('buildApiKeyLifecyclePacket requires an options object');
+  assertNoForbiddenPayload(input, 'input');
+  assertNoApiKeySecretMaterial(input, 'input');
+  const tenantId = requiredString(input.tenant_id ?? input.tenantId, 'tenant_id');
+  const subjectRef = requiredString(input.subject_ref ?? input.subjectRef, 'subject_ref');
+  const generatedAt = isoTimestamp(input.generated_at ?? input.generatedAt, 'generated_at');
+  const operation = apiKeyLifecycleOperation(input);
+  const keyContracts = apiKeyLifecycleContractsFrom(input, tenantId, subjectRef, generatedAt);
+  const requiredEvidenceRefs = apiKeyLifecycleEvidenceRefsFrom(input, operation, keyContracts);
+  const operatorApprovalRef = apiKeyLifecycleOperatorApprovalRefFromInput(input);
+  const readiness = apiKeyLifecycleReadiness(operation, requiredEvidenceRefs, operatorApprovalRef);
+  const body = {
+    schema: HOSTED_CLOUD_API_KEY_LIFECYCLE_PACKET_SCHEMA,
+    packet_id: stringOrDefault(input.packet_id ?? input.packetId, undefined),
+    generated_at: generatedAt,
+    tenant_id: tenantId,
+    subject_ref: subjectRef,
+    operation,
+    key_contracts: keyContracts,
+    key_metadata_refs: apiKeyLifecycleKeyMetadataRefs(operation, requiredEvidenceRefs),
+    lifecycle_events: apiKeyLifecycleEvents(operation, requiredEvidenceRefs, keyContracts),
+    required_evidence_refs: requiredEvidenceRefs,
+    external_blockers: readiness.external_blockers,
+    missing_evidence_refs: readiness.missing_evidence_refs,
+    operator_approval_ref: operatorApprovalRef,
+    readiness,
+    customer_api_keys_live: readiness.customer_api_keys_live,
+    guarantees: apiKeyLifecycleSafetyGuarantees(),
+    public_safety_guarantees: apiKeyLifecycleSafetyGuarantees(),
+  };
+  const packet = withContractIdentity(body, 'hcaklp', 'packet_id');
+  validateApiKeyLifecyclePacket(packet);
+  return packet;
+}
+
+export function validateApiKeyLifecyclePacket(packet) {
+  if (!isPlainObject(packet)) throw new TypeError('packet must be an object');
+  assertNoForbiddenPayload(packet, 'packet');
+  assertNoApiKeySecretMaterial(packet, 'packet');
+  if (packet.schema !== HOSTED_CLOUD_API_KEY_LIFECYCLE_PACKET_SCHEMA) throw new TypeError(`schema must be ${HOSTED_CLOUD_API_KEY_LIFECYCLE_PACKET_SCHEMA}`);
+  requiredString(packet.packet_id, 'packet_id');
+  isoTimestamp(packet.generated_at, 'generated_at');
+  requiredString(packet.contract_hash, 'contract_hash');
+  const tenantId = requiredString(packet.tenant_id, 'tenant_id');
+  const subjectRef = requiredString(packet.subject_ref, 'subject_ref');
+  const operation = apiKeyLifecycleOperation(packet);
+  validateApiKeyLifecycleContracts(packet.key_contracts, tenantId, subjectRef);
+  const requiredEvidenceRefs = validateApiKeyLifecycleEvidenceRefs(packet.required_evidence_refs, operation);
+  const operatorApprovalRef = apiKeyLifecycleOperatorApprovalRefFromPacket(packet);
+  const expectedReadiness = apiKeyLifecycleReadiness(operation, requiredEvidenceRefs, operatorApprovalRef);
+  assertSameLifecycleObject(packet.key_metadata_refs, apiKeyLifecycleKeyMetadataRefs(operation, requiredEvidenceRefs), 'key_metadata_refs');
+  assertSameLifecycleArray(packet.lifecycle_events, apiKeyLifecycleEvents(operation, requiredEvidenceRefs, packet.key_contracts), 'lifecycle_events');
+  assertSameLifecycleArray(packet.external_blockers, expectedReadiness.external_blockers, 'external_blockers');
+  assertSameLifecycleArray(packet.missing_evidence_refs, expectedReadiness.missing_evidence_refs, 'missing_evidence_refs');
+  validateApiKeyLifecycleReadiness(packet.readiness, expectedReadiness);
+  if (packet.customer_api_keys_live !== expectedReadiness.customer_api_keys_live) throw new TypeError('customer_api_keys_live must match readiness.customer_api_keys_live');
+  validateApiKeyLifecycleSafetyGuarantees(packet.guarantees ?? packet.public_safety_guarantees);
+  validateApiKeyLifecycleSafetyGuarantees(packet.public_safety_guarantees ?? packet.guarantees);
+  return true;
+}