@opengeni/core 1.3.0 → 1.4.2

package/dist/transcription.d.ts

@@ -1,4 +1,6 @@
+import type { VoiceInputPricing, VoiceInputUsage } from "@opengeni/config";
 import type { TranscribeAudioResponse, VoiceInputErrorCode } from "@opengeni/contracts";
+import type { CreditDebitAttribution } from "@opengeni/db";
 /**
  * Server-owned upstream budget for one provider attempt. Resumable recording
  * claims remain fenced for longer than this budget before another worker may
@@ -31,21 +33,112 @@ export type TranscriptionRequest = {
     preferredProvider?: string | null | undefined;
     fallbackEnabled?: boolean | undefined;
     excludedProviders?: readonly string[] | undefined;
+    /**
+     * Credit settlement facts for a deployment-funded provider. Required when
+     * the selected provider is deployment-funded and credit billing is active;
+     * the service fails closed without it.
+     */
+    billing?: TranscriptionBillingContext | undefined;
+    /**
+     * Internal: return `settleBilling` instead of settling before returning, so
+     * a resumable segment's transcript commits before any billing write.
+     */
+    deferBillingSettlement?: boolean;
+};
+/**
+ * Trusted, server-built settlement identity for one transcription unit. The
+ * usage receipt and debit idempotency keys derive from `workspaceId` +
+ * `sourceId` (see `voiceInputSettlementKeys`), so a retry or a later
+ * reconciliation settles the same unit exactly once.
+ */
+export type TranscriptionBillingContext = {
+    /**
+     * Server-derived unit identity. Never a client-chosen value: a reused id
+     * settles once, so a client-controlled id would make later calls free.
+     */
+    sourceId: string;
+    /** Trusted payer facts from the authenticated request boundary. */
+    attribution: CreditDebitAttribution;
+    /**
+     * Audio duration measured by the server from WAV bytes it produced (the
+     * resumable segment, or the normalized one-shot upload). Bills whenever the
+     * provider reports no usage this deployment has a price for.
+     */
+    trustedDurationSeconds?: number | undefined;
 };
 export type TranscriptionResult = TranscribeAudioResponse & {
     /** Server-private provider id for operational metrics only. Never returned to clients. */
     providerId: string;
     audioSeconds: number;
     latencyMs: number;
+    /** Opengeni credits charged for this call (0 for subscription/free providers). */
+    creditCostMicros?: number | undefined;
+    /**
+     * Server-only settlement callback; never serialized into a public response.
+     * Never rejects: a settlement failure after provider success is logged and
+     * retried, and the transcript is still delivered.
+     */
+    settleBilling?: () => Promise<void>;
+};
+export type TranscriptionBillingRefusalCode = "insufficient_credits" | "allowance_exhausted" | "monthly_model_cost_limit";
+/**
+ * Pre-use refusal for deployment-funded transcription: 402 for credits and
+ * allowances (same codes as session admission), 429 for a static monthly cap.
+ */
+export declare class TranscriptionBillingRefusedError extends Error {
+    readonly status: 402 | 429;
+    readonly code: TranscriptionBillingRefusalCode;
+    readonly details: {
+        scope?: string;
+        resetsAt?: string | null;
+        subjectId?: string;
+    };
+    constructor(input: {
+        code: TranscriptionBillingRefusalCode;
+        message: string;
+        details?: {
+            scope?: string;
+            resetsAt?: string | null;
+            subjectId?: string;
+        };
+    });
+}
+/**
+ * Credit admission and settlement for deployment-funded transcription.
+ * Subscription providers (Codex, SuperGrok) never reach this port.
+ */
+export type TranscriptionBilling = {
+    /** Refuse before any audio is sent when the payer cannot fund the call. */
+    admit(input: {
+        accountId: string;
+        workspaceId: string;
+        attribution: CreditDebitAttribution;
+    }): Promise<void>;
+    /**
+     * Record usage and debit credits once per unit, after use. The usage receipt
+     * commits before the debit, so a failed debit leaves a durable receipt that
+     * `admit` reconciles on the workspace's next voice request.
+     */
+    settle(input: {
+        accountId: string;
+        workspaceId: string;
+        providerId: string;
+        model: string;
+        pricing: VoiceInputPricing;
+        usage: VoiceInputUsage | null;
+        billing: TranscriptionBillingContext;
+    }): Promise<{
+        creditCostMicros: number;
+    }>;
 };
 export declare class TranscriptionServiceError extends Error {
-    readonly code: VoiceInputErrorCode;
+    readonly code: Exclude<VoiceInputErrorCode, TranscriptionBillingRefusalCode>;
     readonly status: number;
     readonly retryable: boolean;
     /** Explicit rejection before any transcription result; safe to try another provider. */
     readonly fallbackSafe: boolean;
     constructor(input: {
-        code: VoiceInputErrorCode;
+        code: Exclude<VoiceInputErrorCode, TranscriptionBillingRefusalCode>;
         message: string;
         status?: number;
         retryable?: boolean;
@@ -73,6 +166,15 @@ export type TranscriptionProvider = {
     /** The adapter guarantees that its upstream transport honors AbortSignal. */
     readonly supportsServerDeadline: true;
     readonly experimental?: boolean | undefined;
+    /**
+     * Present when the deployment pays the upstream provider (OpenAI/Azure):
+     * the call is admitted against and settled in Opengeni credits. Absent for
+     * the workspace's own subscriptions, which are never charged.
+     */
+    readonly deploymentFunded?: {
+        readonly model: string;
+        readonly pricing: VoiceInputPricing | null;
+    } | undefined;
     /**
      * Deployment readiness when called without a workspace. When `workspaceId` is
      * provided, providers may require a workspace-attached credential (e.g. Codex).
@@ -90,14 +192,27 @@ export type TranscriptionProvider = {
     }): Promise<{
         text: string;
         languages: string[];
+        usage?: VoiceInputUsage | null | undefined;
     }>;
 };
 export type TranscriptionService = {
     limits(): TranscriptionLimits;
     /** True when at least one ready provider can serve requests. */
     available(context?: TranscriptionAvailabilityContext): boolean | Promise<boolean>;
+    availableProviderIds?(context: TranscriptionAvailabilityContext): Promise<string[]>;
     /** Select one provider before a durable segment attempt; retries pin this id. */
     selectProvider?(context: TranscriptionAvailabilityContext): string | null | Promise<string | null>;
+    /**
+     * Credit admission for an exact provider before durable work is claimed.
+     * Resolves for subscription providers; throws TranscriptionBillingRefusedError
+     * when a deployment-funded provider cannot be paid for.
+     */
+    admit?(input: {
+        providerId: string;
+        accountId: string;
+        workspaceId: string;
+        attribution: CreditDebitAttribution;
+    }): Promise<void>;
     transcribe(request: TranscriptionRequest): Promise<TranscriptionResult>;
 };
 export type PreparedTranscriptionSegment = {
@@ -113,6 +228,8 @@ export type TranscriptionSegmenter = {
         sourceMimeType: string;
         totalDurationMilliseconds: number;
         providerSegmentSeconds: number;
+        /** Hard decode ceiling (`ffmpeg -t`); audio past it is never decoded. */
+        maxDecodeSeconds?: number | undefined;
         chunks: AsyncIterable<Uint8Array>;
         signal?: AbortSignal | undefined;
     }): AsyncIterable<PreparedTranscriptionSegment>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opengeni/core",
-  "version": "1.3.0",
+  "version": "1.4.2",
   "description": "OpenGeni framework-agnostic core: the domain, access, and billing layers (neutral access, off-HTTP V2 surface). Behavior-preserving extraction from apps/api — keeps Hono's HTTPException for error throwing (typed-errors cleanup deferred).",
   "license": "Apache-2.0",
   "repository": {
@@ -50,17 +50,17 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
-    "@opengeni/capabilities": "1.3.0",
-    "@opengeni/codex": "1.3.0",
-    "@opengeni/config": "1.3.0",
-    "@opengeni/contracts": "1.3.0",
-    "@opengeni/db": "1.3.0",
-    "@opengeni/documents": "1.3.0",
-    "@opengeni/events": "1.3.0",
-    "@opengeni/network": "1.3.0",
-    "@opengeni/observability": "1.3.0",
-    "@opengeni/runtime": "1.3.0",
-    "@opengeni/storage": "1.3.0",
+    "@opengeni/capabilities": "1.4.2",
+    "@opengeni/codex": "1.4.2",
+    "@opengeni/config": "1.4.2",
+    "@opengeni/contracts": "1.4.2",
+    "@opengeni/db": "1.4.2",
+    "@opengeni/documents": "1.4.2",
+    "@opengeni/events": "1.4.2",
+    "@opengeni/network": "1.4.2",
+    "@opengeni/observability": "1.4.2",
+    "@opengeni/runtime": "1.4.2",
+    "@opengeni/storage": "1.4.2",
     "hono": "^4.12.18",
     "zod": "^4.2.1"
   },

package/src/application/modal-native-live-declaration-join.ts

@@ -0,0 +1,196 @@
+import { types } from "node:util";
+import type { Settings } from "@opengeni/config";
+import { ModalNativePreparationDeclarationV2 } from "@opengeni/contracts/modal-native-proof-v2";
+import {
+  lockLiveNativeOriginalOriginTx,
+  type Database,
+  type ModalNativeLiveOriginProjection,
+  type ModalNativeLiveOriginResult,
+} from "@opengeni/db";
+import { z } from "zod";
+import {
+  currentNativeOriginalConfigurationMatches,
+  disposeNativeOriginalConfigurationSample,
+  sampleNativeOriginalConfiguration,
+  type NativeOriginalConfigurationSample,
+} from "./modal-native-original-configuration";
+import {
+  configuredNativeWorkerHostTransport,
+  disposeNativeWorkerHostTransport,
+  nativeWorkerHostTransportDescription,
+  verifyNativeWorkerHostTransport,
+} from "./modal-native-worker-host-transport";
+
+// Unused PRIVATE request/data join. NOT the canonical claimed-worker issuer,
+// custody authorizer, committed grant, native context or one-use effect permit.
+// No consumer may turn this data into authority from its type/shape alone.
+// A future canonical host entry must establish its actual worker provenance and
+// atomically consume this join with protected declaration/config/grant/cold
+// insertion in this SAME transaction, before any provider-prefix I/O.
+const MAX_BODY_BYTES = 4 * 1024 * 1024;
+const typedArrayPrototype = Object.getPrototypeOf(Uint8Array.prototype);
+const nativeLength = Object.getOwnPropertyDescriptor(typedArrayPrototype, "byteLength")!.get!;
+const nativeOffset = Object.getOwnPropertyDescriptor(typedArrayPrototype, "byteOffset")!.get!;
+const nativeBuffer = Object.getOwnPropertyDescriptor(typedArrayPrototype, "buffer")!.get!;
+const request = z
+  .object({
+    protocol: z.literal("opengeni-modal-native-live-declaration-join"),
+    version: z.literal(2),
+    requestId: z.string().uuid(),
+    workflowId: z.string().min(1).max(1024),
+    workflowRunId: z.string().min(1).max(1024),
+    activityId: z.string().min(1).max(1024),
+    initiatingHumanSubjectId: z
+      .string()
+      .regex(/^user:.+/u)
+      .max(1024),
+    declarationJson: z.string().min(1).max(MAX_BODY_BYTES),
+  })
+  .strict();
+
+type JoinSettings = Pick<
+  Settings,
+  | "delegationSecret"
+  | "modalTokenId"
+  | "modalTokenSecret"
+  | "modalEnvironment"
+  | "environmentsEncryptionKey"
+>;
+
+/** Sensitive request-local data only. Do not publish/log/cache across commit.
+ * The sample contains immutable credential strings which disposal cannot erase.
+ * This result has no native-I/O, replay, custody or effect authority. */
+export type NativeLiveDeclarationJoin = Readonly<{
+  requestId: string;
+  declaration: ModalNativePreparationDeclarationV2;
+  projection: ModalNativeLiveOriginProjection;
+  configuration: NativeOriginalConfigurationSample;
+}>;
+export type NativeLiveDeclarationJoinResult =
+  | { kind: "joined_data"; data: NativeLiveDeclarationJoin }
+  | { kind: "off" }
+  | { kind: "refused" }
+  | Exclude<ModalNativeLiveOriginResult, { kind: "live" }>;
+
+function ownedBody(input: Uint8Array): Buffer | null {
+  if (!input || types.isProxy(input) || !types.isUint8Array(input)) return null;
+  try {
+    const length = nativeLength.call(input) as number;
+    const backing = nativeBuffer.call(input) as ArrayBuffer;
+    if (length > MAX_BODY_BYTES || !types.isArrayBuffer(backing)) return null;
+    return Buffer.from(new Uint8Array(backing, nativeOffset.call(input) as number, length));
+  } catch {
+    return null;
+  }
+}
+
+function freezeJson<T>(value: T): T {
+  if (value && typeof value === "object") {
+    for (const child of Object.values(value)) freezeJson(child);
+    Object.freeze(value);
+  }
+  return value;
+}
+
+/** Own bytes BEFORE either verifying or parsing. After the blocking SQL join,
+ * re-read the explicit CURRENT deployment root/profile and reverify current
+ * expiry over those SAME owned bytes. A historical MAC witness is insufficient.
+ * No tenant/subject GUC change, general access-token resolver, provider await,
+ * fallback, registration or error-to-success conversion occurs here.
+ *
+ * Input execution/human fields are signed CORRELATION, not caller authority:
+ * compare them to the exact DB-derived accepted original projection. This does
+ * NOT independently prove that the canonical worker produced the request.
+ * Enter an existing scoped transaction before any tenancy/control/row lock;
+ * consume the result in that transaction and dispose its sample afterward. */
+export async function lockNativeLiveDeclarationJoinTx(
+  scopedTx: Database,
+  settings: JoinSettings,
+  envelope: string,
+  inputBody: Uint8Array,
+): Promise<NativeLiveDeclarationJoinResult> {
+  const initialTransport = configuredNativeWorkerHostTransport(settings);
+  if (!initialTransport) return { kind: "off" };
+  let body: Buffer | null = null;
+  let sample: NativeOriginalConfigurationSample | null = null;
+  let retained = false;
+  try {
+    body = ownedBody(inputBody);
+    if (!body) return { kind: "refused" };
+    const proof = verifyNativeWorkerHostTransport(initialTransport, envelope, body);
+    if (!proof) return { kind: "refused" };
+    const description = nativeWorkerHostTransportDescription(initialTransport, proof);
+    if (description.action !== "declare_preparation") return { kind: "refused" };
+    let parsed: z.infer<typeof request>;
+    try {
+      parsed = request.parse(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(body)));
+    } catch {
+      return { kind: "refused" };
+    }
+    const declarationBytes = Buffer.from(parsed.declarationJson, "utf8");
+    let declaration: ModalNativePreparationDeclarationV2;
+    try {
+      declaration = ModalNativePreparationDeclarationV2.parse(JSON.parse(parsed.declarationJson));
+      if (
+        parsed.requestId !== description.requestId ||
+        Object.keys(declaration.scope).some(
+          (key) =>
+            declaration.scope[key as keyof typeof declaration.scope] !==
+            description.scope[key as keyof typeof description.scope],
+        ) ||
+        declaration.configurationCaptureRef.id !== description.configurationCaptureRef.id ||
+        declaration.configurationCaptureRef.revision !==
+          description.configurationCaptureRef.revision ||
+        declaration.proofGrantRef.id !== description.proofGrantRef.id ||
+        declaration.proofGrantRef.epoch !== description.proofGrantRef.epoch
+      )
+        return { kind: "refused" };
+      sample = sampleNativeOriginalConfiguration(settings, declarationBytes);
+      if (!sample) return { kind: "off" };
+    } catch {
+      return { kind: "refused" };
+    } finally {
+      declarationBytes.fill(0);
+    }
+
+    const origin = await lockLiveNativeOriginalOriginTx(scopedTx, declaration.scope);
+    if (origin.kind !== "live") return origin;
+    const currentTransport = configuredNativeWorkerHostTransport(settings);
+    if (!currentTransport) return { kind: "refused" };
+    try {
+      if (
+        !verifyNativeWorkerHostTransport(currentTransport, envelope, body) ||
+        !currentNativeOriginalConfigurationMatches(sample, settings)
+      )
+        return { kind: "refused" };
+    } finally {
+      disposeNativeWorkerHostTransport(currentTransport);
+    }
+    const projection = origin.projection;
+    if (
+      Object.keys(declaration.scope).some(
+        (key) =>
+          declaration.scope[key as keyof typeof declaration.scope] !==
+          projection.scope[key as keyof typeof projection.scope],
+      ) ||
+      projection.initiator.initiatingHumanSubjectId !== parsed.initiatingHumanSubjectId ||
+      projection.execution.workflowId !== parsed.workflowId ||
+      projection.execution.workflowRunId !== parsed.workflowRunId ||
+      projection.execution.activityId !== parsed.activityId ||
+      projection.providerRecoveryCount !== declaration.providerRecoveryCount
+    )
+      return { kind: "refused" };
+    const data = Object.freeze({
+      requestId: parsed.requestId,
+      declaration: freezeJson(declaration),
+      projection: freezeJson(structuredClone(projection)),
+      configuration: sample,
+    });
+    retained = true;
+    return { kind: "joined_data", data };
+  } finally {
+    body?.fill(0);
+    disposeNativeWorkerHostTransport(initialTransport);
+    if (!retained && sample) disposeNativeOriginalConfigurationSample(sample);
+  }
+}

package/src/application/modal-native-original-configuration.ts

@@ -0,0 +1,261 @@
+import { createHash, createHmac, timingSafeEqual, type Hmac } from "node:crypto";
+import { rootCertificates } from "node:tls";
+import { types } from "node:util";
+import type { Settings } from "@opengeni/config";
+import { ModalNativePreparationDeclarationV2 } from "@opengeni/contracts/modal-native-proof-v2";
+
+// PRIVATE, unused configuration groundwork, not a host authorizer, capture
+// receipt, original grant, native context or effect permit. The canonical host
+// must authenticate and join live original authority before committing this
+// draft into protected storage, and before using its matched snapshot for I/O.
+// Never project its equality bytes into logs, status, errors or workflow history.
+const SUBKEY_DOMAIN = "opengeni:modal-native:configuration-equality:subkey:v2";
+const MESSAGE_DOMAIN = "opengeni:modal-native:configuration-equality:framed:v2\0";
+const MAX_DECLARATION_BYTES = 4 * 1024 * 1024;
+const SERVER_URL = "https://api.modal.com:443";
+const typedArrayPrototype = Object.getPrototypeOf(Uint8Array.prototype);
+const nativeByteLength = Object.getOwnPropertyDescriptor(typedArrayPrototype, "byteLength")!.get!;
+const nativeByteOffset = Object.getOwnPropertyDescriptor(typedArrayPrototype, "byteOffset")!.get!;
+const nativeBuffer = Object.getOwnPropertyDescriptor(typedArrayPrototype, "buffer")!.get!;
+type ConfigurationSettings = Pick<
+  Settings,
+  "modalTokenId" | "modalTokenSecret" | "modalEnvironment" | "environmentsEncryptionKey"
+>;
+
+export type NativeOriginalConfigurationSnapshot = Readonly<{
+  serverUrl: string;
+  tokenId: string;
+  tokenSecret: string;
+  environment: string;
+}>;
+
+function readProfile(environment: string) {
+  return Object.freeze({
+    protocol: "modal-direct-original-read-grpc-v1" as const,
+    version: 1 as const,
+    sourceGitBlob: "7599f5b80cf111a25f78f427cfb2616d7e24b36c" as const,
+    serverUrl: SERVER_URL,
+    serverSelection: "host-pinned-modal-0.9-default" as const,
+    credentialSelection: "explicit-deployment-settings-pair-only" as const,
+    environmentSelection: "explicit-own-settings-no-default" as const,
+    environment,
+    environmentTransmittedByCpReads: false as const,
+    namespaceSelection: "unbound-until-authenticated-once-capture" as const,
+    modalProjectionVersion: "0.9.0" as const,
+    grpcJsVersion: "1.14.4" as const,
+    protobufJsVersion: "7.6.5" as const,
+    rpcPrefix: "/modal.client.ModalClient/" as const,
+    methods: ["AuthTokenGet", "WorkspaceNameLookup", "TaskGetCommandRouterAccess"] as const,
+    authHeaders: {
+      clientType: "8",
+      clientVersion: "1.0.0",
+      libmodalVersion: "modal-js/0.9.0",
+    } as const,
+    tlsPolicy: "explicit-node-tls-rootCertificates-v1" as const,
+    tlsRootsSha256: createHash("sha256").update(rootCertificates.join("\n")).digest("hex"),
+    retries: 0 as const,
+    nativeChainDeadlineMs: 30_000 as const,
+    maxWireBytes: 1_048_576 as const,
+  });
+}
+
+type PrivateDescription = Readonly<{
+  protocol: "opengeni-modal-native-configuration-equality";
+  version: 2;
+  purpose: "original-native-custody-proof";
+  configurationCaptureRef: ModalNativePreparationDeclarationV2["configurationCaptureRef"];
+  proofGrantRef: ModalNativePreparationDeclarationV2["proofGrantRef"];
+  declarationJson: string;
+  declarationSha256: string;
+  profile: ReturnType<typeof readProfile>;
+  keySelection: "existing-environments-encryption-root-current-only";
+  algorithm: "hmac-sha256";
+  subkeyDomain: typeof SUBKEY_DOMAIN;
+  messageDomain: typeof MESSAGE_DOMAIN;
+}>;
+
+/** Sensitive PRIVATE storage draft, not proof that any row or grant committed. */
+export type NativeOriginalConfigurationDraftV2 = Readonly<{
+  description: PrivateDescription;
+  equality: Uint8Array;
+}>;
+
+declare const sampleBrand: unique symbol;
+export type NativeOriginalConfigurationSample = Readonly<{ [sampleBrand]: true }>;
+type SampleState = {
+  snapshot: NativeOriginalConfigurationSnapshot;
+  description: PrivateDescription;
+  declarationBytes: Buffer;
+  equality: Buffer;
+};
+const samples = new WeakMap<NativeOriginalConfigurationSample, SampleState>();
+
+function settingsStrings(input: ConfigurationSettings): Record<string, string> | null {
+  if (!input || typeof input !== "object" || types.isProxy(input)) return null;
+  const prototype = Object.getPrototypeOf(input);
+  if (prototype !== Object.prototype && prototype !== null) return null;
+  const result: Record<string, string> = {};
+  for (const key of [
+    "modalTokenId",
+    "modalTokenSecret",
+    "modalEnvironment",
+    "environmentsEncryptionKey",
+  ]) {
+    const property = Object.getOwnPropertyDescriptor(input, key);
+    if (!property || !("value" in property) || typeof property.value !== "string") return null;
+    result[key] = property.value;
+  }
+  if (
+    !/^[\x20-\x7e]{1,8192}$/.test(result.modalTokenId!) ||
+    !/^[\x20-\x7e]{1,8192}$/.test(result.modalTokenSecret!) ||
+    result.modalEnvironment!.length > 200 ||
+    !/^[A-Za-z0-9+/]{43}=$/.test(result.environmentsEncryptionKey!)
+  )
+    return null;
+  return result;
+}
+
+function copyDeclaration(input: Uint8Array): Buffer | null {
+  if (!input || types.isProxy(input) || !types.isUint8Array(input)) return null;
+  try {
+    const byteLength = nativeByteLength.call(input) as number;
+    const byteOffset = nativeByteOffset.call(input) as number;
+    const buffer = nativeBuffer.call(input) as ArrayBuffer;
+    if (byteLength === 0 || byteLength > MAX_DECLARATION_BYTES || types.isSharedArrayBuffer(buffer))
+      return null;
+    return Buffer.from(new Uint8Array(buffer, byteOffset, byteLength));
+  } catch {
+    return null;
+  }
+}
+
+function frame(hmac: Hmac, label: string, bytes: Buffer) {
+  const length = Buffer.alloc(4);
+  length.writeUInt32BE(bytes.length);
+  hmac.update(label).update("\0").update(length).update(bytes);
+}
+
+/** Samples ONLY explicit own settings, without environment/profile/SDK lookup.
+ * A parsed declaration merely supplies correlation. Genuine known app/image
+ * provenance and same-transaction host/grant/admission checks remain external.
+ */
+export function sampleNativeOriginalConfiguration(
+  settings: ConfigurationSettings,
+  declarationBytes: Uint8Array,
+): NativeOriginalConfigurationSample | null {
+  const selected = settingsStrings(settings);
+  const body = copyDeclaration(declarationBytes);
+  if (!selected || !body) {
+    body?.fill(0);
+    return null;
+  }
+  let root: Buffer | undefined;
+  let subkey: Buffer | undefined;
+  let tokenId: Buffer | undefined;
+  let tokenSecret: Buffer | undefined;
+  let profileBytes: Buffer | undefined;
+  let retained = false;
+  try {
+    const json = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(body);
+    const declaration = ModalNativePreparationDeclarationV2.parse(JSON.parse(json));
+    root = Buffer.from(selected.environmentsEncryptionKey!, "base64");
+    if (root.length !== 32 || root.toString("base64") !== selected.environmentsEncryptionKey)
+      return null;
+    const snapshot = Object.freeze({
+      serverUrl: SERVER_URL,
+      tokenId: selected.modalTokenId!,
+      tokenSecret: selected.modalTokenSecret!,
+      environment: selected.modalEnvironment!,
+    });
+    const description: PrivateDescription = Object.freeze({
+      protocol: "opengeni-modal-native-configuration-equality",
+      version: 2,
+      purpose: "original-native-custody-proof",
+      configurationCaptureRef: declaration.configurationCaptureRef,
+      proofGrantRef: declaration.proofGrantRef,
+      declarationJson: json,
+      declarationSha256: createHash("sha256").update(body).digest("hex"),
+      profile: readProfile(snapshot.environment),
+      keySelection: "existing-environments-encryption-root-current-only",
+      algorithm: "hmac-sha256",
+      subkeyDomain: SUBKEY_DOMAIN,
+      messageDomain: MESSAGE_DOMAIN,
+    });
+    subkey = createHmac("sha256", root).update(SUBKEY_DOMAIN).digest();
+    tokenId = Buffer.from(snapshot.tokenId, "utf8");
+    tokenSecret = Buffer.from(snapshot.tokenSecret, "utf8");
+    profileBytes = Buffer.from(JSON.stringify(description), "utf8");
+    const hmac = createHmac("sha256", subkey).update(MESSAGE_DOMAIN);
+    frame(hmac, "original-declaration", body);
+    frame(hmac, "private-configuration", profileBytes);
+    frame(hmac, "exact-token-id", tokenId);
+    frame(hmac, "exact-token-secret", tokenSecret);
+    const sample = Object.freeze({}) as NativeOriginalConfigurationSample;
+    samples.set(sample, { snapshot, description, declarationBytes: body, equality: hmac.digest() });
+    retained = true;
+    return sample;
+  } catch {
+    // Fixed refusal, never validator details, credentials or keyed material.
+    return null;
+  } finally {
+    root?.fill(0);
+    subkey?.fill(0);
+    tokenId?.fill(0);
+    tokenSecret?.fill(0);
+    profileBytes?.fill(0);
+    if (!retained) body.fill(0);
+  }
+}
+
+/** Private draft extraction for protected storage only; never a status DTO. */
+export function privateNativeOriginalConfigurationDraft(
+  sample: NativeOriginalConfigurationSample,
+): NativeOriginalConfigurationDraftV2 | null {
+  const state = samples.get(sample);
+  return state
+    ? { description: structuredClone(state.description), equality: Uint8Array.from(state.equality) }
+    : null;
+}
+
+/** Same sampled strings for a future authenticated native caller; NOT a grant. */
+export function nativeOriginalConfigurationSnapshot(
+  sample: NativeOriginalConfigurationSample,
+): NativeOriginalConfigurationSnapshot | null {
+  return samples.get(sample)?.snapshot ?? null;
+}
+
+/** PRIVATE equality check only. No public oracle, grant renewal or key fallback.
+ * Restart reconstruction still requires an authenticated protected original row.
+ */
+export function currentNativeOriginalConfigurationMatches(
+  sample: NativeOriginalConfigurationSample,
+  settings: ConfigurationSettings,
+): boolean {
+  const state = samples.get(sample);
+  if (!state) return false;
+  const current = sampleNativeOriginalConfiguration(settings, state.declarationBytes);
+  if (!current) return false;
+  try {
+    const candidate = samples.get(current)!;
+    return (
+      state.equality.length === 32 &&
+      candidate.equality.length === 32 &&
+      timingSafeEqual(state.equality, candidate.equality)
+    );
+  } finally {
+    disposeNativeOriginalConfigurationSample(current);
+  }
+}
+
+/** Wipes owned mutable copies, not JS immutable strings or native I/O/custody.
+ * A future owning native caller must join its real callbacks separately.
+ */
+export function disposeNativeOriginalConfigurationSample(
+  sample: NativeOriginalConfigurationSample,
+) {
+  const state = samples.get(sample);
+  if (!state) return;
+  state.declarationBytes.fill(0);
+  state.equality.fill(0);
+  samples.delete(sample);
+}