@serve.zone/interfaces 27.2.0 → 27.3.1

package/readme.md

@@ -887,6 +887,25 @@ When `validateCorestoreObjectStorageCredentialMaterial()` receives a trusted
 retention expectation, matching retention evidence is mandatory; missing or
 different evidence fails validation.
 
+The runtime export also defines exact Corestore database backup receipts,
+allocation references, restore requests, and restore responses. Use
+`normalizeCorestoreDatabaseAllocationReference()`,
+`encodeCorestoreDatabaseAllocationReference()`, and
+`computeCorestoreDatabaseAllocationReferenceSha256()` for the allocation
+boundary; the receipt, restore-request, and restore-response APIs follow the
+same exact normalize, encode, and SHA-256 naming. They enforce bounded canonical
+JSON without performing a backup or restore. A restore request may carry
+`expectedDatabaseAllocation` so the restore implementation can fence the exact
+scratch allocation, and may carry the caller-owned `restoreAttemptId` to select
+a new fenced idempotency attempt. The attempt ID uses the database-backup
+identifier grammar and 256-character maximum. Omitting the snapshot
+`databaseAllocation` field together with request-level
+`expectedDatabaseAllocation` and `restoreAttemptId` preserves legacy request
+bytes and digests exactly.
+`corestoreDatabaseBackupRuntimeLimits` publishes the distinct 96 MiB snapshot
+payload, one-byte-larger framed snapshot-original, 128 MiB verified closure
+plaintext, and 256 MiB closure boundaries used by Corestore.
+
 ### Legacy Deployment Settlement
 
 The Node-only `/runtime` export also provides strict, exact-schema codecs for
@@ -894,7 +913,10 @@ Cloudly legacy deployment settlement plans, production requests, check/apply
 summaries, stable outcomes, and scratch/production receipts. Authenticated
 artifacts use domain-separated HMAC inputs and references derived from the full
 authority-metadata SHA-256; authority-aware normalizers enforce metadata fences
-and validity windows and require a consumer-owned, constant-time HMAC verifier.
+and artifact-time validity windows. General authority-aware APIs require a
+consumer-owned, constant-time HMAC verifier; private stdio authority-aware APIs
+derive verification from their exact plaintext authority handoffs. They never
+read the current wall clock.
 Structural normalizers explicitly do not authenticate MACs. Literal portable
 golden vectors contain only safe
 metadata, summaries, digests, and MACs. The separately named
@@ -902,6 +924,61 @@ metadata, summaries, digests, and MACs. The separately named
 exists only for private maintenance-container interoperability and is never part
 of a safe result, receipt, or golden summary.
 
+Fenced settlement contracts add deterministic execution-attempt identities and
+prepared, committed, or aborted observations. Resolution bundles distinguish
+`committed-schema1`, `committed-schema2`, `aborted-prepared`,
+`observed-aborted`, `absent-tombstone`, and `legacy-no-op`; only the scratch-only
+legacy no-op has no durable attempt observation. Source and execution authority
+status are bound to the resolution's `observedAt`. Scratch attempts use the same
+authority for both roles and require matching statuses. Historical verification
+remains possible after expiry because status is derived only from the
+authenticated observation time. Production recovery always uses receipt v2 and
+a distinct execution authority B whose metadata names source authority A and
+binds the authenticated plan, request bundle, and scratch receipt digests.
+B is issued strictly after scratch completion; B's `requestedAt` and
+`approvedAt` are independent of A's request timestamp and must remain within
+B's own validity interval.
+
+Consumers make trust decisions through
+`normalizeAuthenticatedCloudlyLegacyDeploymentSettlementResolutionForAuthorities()`,
+`normalizeCloudlyLegacyDeploymentSettlementScratchExecutionBundleForAuthority()`,
+`normalizeCloudlyLegacyDeploymentSettlementProductionExecutionBundleV2ForAuthorities()`,
+`normalizeCloudlyLegacyDeploymentSettlementStdioRequestForAuthorities()`, and
+`normalizeCloudlyLegacyDeploymentSettlementStdioResponseForRequestAuthorities()`.
+Every resolution outcome, including an unapplied outcome, is carried in an
+`IAuthenticatedCloudlyLegacyDeploymentSettlementResolutionV1` recovery
+attestation under the dedicated resolution HMAC domain and signed by the
+execution authority. The raw
+`normalizeCloudlyLegacyDeploymentSettlementResolutionBundleForAuthorities()`
+helper verifies referenced artifacts and status only; its result is not an
+authenticated recovery claim. The non-stdio authority-aware APIs use the
+caller-supplied HMAC verifier and never receive plaintext keys. The private
+stdio variants accept no external verifier: they bind each HMAC to the
+authority reference and key in the corresponding request handoff. Interfaces
+never executes a settlement.
+
+The stdio contract exposes nine commands from `settlement-plan` through
+`settlement-production-resolve`. Requests and responses are exact canonical
+JSON followed by one LF, bounded by
+`cloudlyLegacyDeploymentSettlementStdioLimits`, and responses use a
+command-discriminated success payload or a finite secret-safe error. Private
+authority handoffs and MongoDB descriptors belong only on protected request
+transport. Production stdio requests reject equal decoded A and B HMAC keys and
+wipe temporary comparison buffers. The handoff-derived verifier uses HMAC-SHA256
+with constant-time MAC comparison, rejects wrong or swapped handoff keys, and
+wipes temporary decoded key and MAC buffers. Handoffs and derived verifiers are
+private in-process capabilities that must never be persisted or logged and must
+be discarded when the stdio exchange ends. Verifier-only integrations do not
+expose key material to Interfaces, so their callers must enforce the same key
+separation.
+Authority-aware response validation also binds settlement-request
+`requestedAt`, production-authorization `requestedAt` and `approvedAt`, and
+resolution `observedAt` to the corresponding request. Production check and
+apply results must be issued by B no earlier than both A's request and B's
+`approvedAt`. Callers remain responsible for process isolation, key
+destruction, logging discipline, database access, and the actual settlement
+transaction.
+
 Launcher environment delivery uses stable `szsv-<base32-sha256>` Docker
 resource names and `/run/serve.zone/secrets/<resource>` source paths. The
 nonsecret map is written to `/run/serve.zone/workloadinit-map-v1.json` with mode

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@serve.zone/interfaces',
-  version: '27.2.0',
+  version: '27.3.1',
   description: 'Shared TypeScript interfaces and TypedRequest contracts for the serve.zone ecosystem.'
 }