@oondemand/oon-core-back 0.6.8 → 0.6.9

package/bin/delivery.js

@@ -5,6 +5,7 @@ const fs = require("node:fs");
 const path = require("node:path");
 const { getContextWithPhase, setState, addEvidence } = require("../src/delivery/api");
 const { provisionRuntime, deployRuntime, waitHttp, activateMember } = require("../src/delivery/runtime");
+const { canonicalizeDeliveryContext } = require("../src/delivery/technicalIdentity");
 
 function flag(name, fallback) {
   const args = process.argv.slice(3);
@@ -16,6 +17,7 @@ function flag(name, fallback) {
 }
 function required(value, name) { if (!value) throw new Error(`${name} obrigatório.`); return value; }
 function secret() { return required(process.env.OON_DELIVERY_SHARED_SECRET, "OON_DELIVERY_SHARED_SECRET"); }
+function normalizedContext(value) { return { ...canonicalizeDeliveryContext(value) }; }
 
 async function main() {
   const command = process.argv[2];
@@ -25,7 +27,8 @@ async function main() {
   if (command === "context") {
     const phase = flag("--phase", "build");
     const output = required(flag("--output"), "--output");
-    const context = await getContextWithPhase({ apiUrl: required(apiUrl, "--api"), releaseId: required(releaseId, "--release"), token: secret(), phase });
+    const fetched = await getContextWithPhase({ apiUrl: required(apiUrl, "--api"), releaseId: required(releaseId, "--release"), token: secret(), phase });
+    const context = normalizedContext(fetched);
     fs.writeFileSync(path.resolve(output), JSON.stringify(context, null, 2), { mode: 0o600 });
     return;
   }
@@ -40,7 +43,7 @@ async function main() {
   if (command === "deploy") {
     const contextFile = required(flag("--context"), "--context");
     const imageDigest = required(flag("--image-digest"), "--image-digest");
-    const context = JSON.parse(fs.readFileSync(path.resolve(contextFile), "utf8"));
+    const context = normalizedContext(JSON.parse(fs.readFileSync(path.resolve(contextFile), "utf8")));
     let failureState = "falha_infra";
     try {
       await setState({ apiUrl, releaseId, token: secret(), etapa: "provisionando", imageDigest });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@oondemand/oon-core-back",
-  "version": "0.6.8",
+  "version": "0.6.9",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/oondemand/oon-platform.git",

package/src/core/technicalIdentity.js

@@ -113,6 +113,10 @@ function technicalIdentity({ appCode, instanceUid, environment }) {
   const mongoUsername = `${base}-rw`;
   const serviceAccount = `${base}-runtime`;
   const secret = `${base}-runtime`;
+  const provisionJob = `${base}-provision`;
+  const frontendDnsLabel = base;
+  const backendDnsLabel = `${base}-api`;
+  const tlsSecret = `${base}-tls`;
 
   const lengths = {
     base: base.length,
@@ -120,6 +124,10 @@ function technicalIdentity({ appCode, instanceUid, environment }) {
     mongoUsername: mongoUsername.length,
     serviceAccount: serviceAccount.length,
     secret: secret.length,
+    provisionJob: provisionJob.length,
+    frontendDnsLabel: frontendDnsLabel.length,
+    backendDnsLabel: backendDnsLabel.length,
+    tlsSecret: tlsSecret.length,
   };
   const invalidLength = Object.entries(lengths).find(([, length]) => length > 63);
   if (invalidLength) {
@@ -141,6 +149,10 @@ function technicalIdentity({ appCode, instanceUid, environment }) {
     mongoUsername,
     serviceAccount,
     secret,
+    provisionJob,
+    frontendDnsLabel,
+    backendDnsLabel,
+    tlsSecret,
   });
 }
 
@@ -159,4 +171,4 @@ module.exports = Object.freeze({
   encodeInstanceUid,
   generateInstanceUid,
   technicalIdentity,
-});
+});

package/src/delivery/mongoProvisioning.js

@@ -1,6 +1,7 @@
 "use strict";
 
 const { mongo } = require("mongoose");
+const { technicalIdentity } = require("../core/technicalIdentity");
 
 const DIGITALOCEAN_API = "https://api.digitalocean.com/v2";
 const DIGITALOCEAN_HOST_SUFFIX = ".mongo.ondigitalocean.com";
@@ -24,8 +25,19 @@ function dnsLabel(value, max = 63) {
     .replace(/-+$/, "");
 }
 
-function mongoIdentity(appCode, environment) {
+function mongoIdentity(appCode, environment, { instanceUid } = {}) {
+  if (instanceUid != null) {
+    const identity = technicalIdentity({ appCode, instanceUid, environment });
+    return {
+      mode: "canonical",
+      identityVersion: identity.version,
+      instanceUid: identity.instanceUid,
+      dbName: identity.database,
+      username: identity.mongoUsername,
+    };
+  }
   return {
+    mode: "legacy",
     dbName: dnsLabel(`${appCode}_${environment}`, 48).replace(/-/g, "_"),
     username: dnsLabel(`${appCode}-${environment}`, 48),
   };
@@ -129,8 +141,9 @@ async function waitForMongoUri(
   );
 }
 
-async function provisionNativeMongo({ adminUri, appCode, environment }) {
-  const { dbName, username } = mongoIdentity(appCode, environment);
+async function provisionNativeMongo({ adminUri, appCode, environment, instanceUid }) {
+  const identity = mongoIdentity(appCode, environment, { instanceUid });
+  const { dbName, username } = identity;
   const password = randomSecret(30);
   const client = new mongo.MongoClient(adminUri, {
     serverSelectionTimeoutMS: 15000,
@@ -163,6 +176,9 @@ async function provisionNativeMongo({ adminUri, appCode, environment }) {
   return {
     dbName,
     username,
+    ...(identity.mode === "canonical"
+      ? { instanceUid: identity.instanceUid, technicalIdentityVersion: identity.identityVersion }
+      : {}),
     mongoUri: buildRuntimeMongoUri({
       adminUri,
       username,
@@ -383,6 +399,7 @@ async function provisionDigitalOceanMongo(
     adminUri,
     appCode,
     environment,
+    instanceUid,
     digitalOceanToken,
     digitalOceanClusterId,
   },
@@ -399,7 +416,8 @@ async function provisionDigitalOceanMongo(
     );
   }
 
-  const { dbName, username } = mongoIdentity(appCode, environment);
+  const identity = mongoIdentity(appCode, environment, { instanceUid });
+  const { dbName, username } = identity;
   const apiOptions = {
     token: digitalOceanToken,
     clusterId: digitalOceanClusterId,
@@ -425,6 +443,9 @@ async function provisionDigitalOceanMongo(
   return {
     dbName,
     username: user.name || username,
+    ...(identity.mode === "canonical"
+      ? { instanceUid: identity.instanceUid, technicalIdentityVersion: identity.identityVersion }
+      : {}),
     mongoUri,
     provider: "digitalocean",
   };
@@ -462,4 +483,4 @@ module.exports = {
   provisionDigitalOceanUser,
   provisionDigitalOceanMongo,
   provisionMongo,
-};
+};

package/src/delivery/runtime.js

@@ -5,6 +5,7 @@ const { spawnSync } = require("node:child_process");
 const { kubectl } = require("./command");
 const { validateInfraFromCluster } = require("../deploy/contracts/infra-contract");
 const { provisionMongo, validateMongoUri } = require("./mongoProvisioning");
+const { canonicalizeDeliveryContext } = require("./technicalIdentity");
 
 const RESOURCE_PROFILES = {
   nano: { cpuRequest: "50m", cpuLimit: "250m", memoryRequest: "96Mi", memoryLimit: "256Mi" },
@@ -36,24 +37,40 @@ function readSecret(namespace, name, key) {
   } catch { return null; }
 }
 
+function canonicalRuntimeContext(context) {
+  return canonicalizeDeliveryContext(context);
+}
+
+function identityLabels(identity) {
+  if (identity.mode !== "canonical") return "";
+  return `\n    oon.runtime/instance-uid: ${identity.instanceUid}\n    oon.runtime/identity-version: \"${identity.version}\"`;
+}
+
+function podIdentityLabels(identity) {
+  if (identity.mode !== "canonical") return "";
+  return `\n        oon.runtime/instance-uid: ${identity.instanceUid}\n        oon.runtime/identity-version: \"${identity.version}\"`;
+}
+
 function baselineManifest({ context }) {
+  const normalized = canonicalRuntimeContext(context);
+  const identity = normalized.deliveryTechnicalIdentity;
   return `apiVersion: v1
 kind: Namespace
 metadata:
-  name: ${context.namespace}
+  name: ${normalized.namespace}
   labels:
-    oon.dev/app-code: ${context.appCode}
-    oon.dev/environment: ${context.environment}
-    app.kubernetes.io/managed-by: oon-platform
+    oon.dev/app-code: ${normalized.appCode}
+    oon.dev/environment: ${normalized.environment}
+    app.kubernetes.io/managed-by: oon-platform${identityLabels(identity)}
 ---
 apiVersion: v1
 kind: ServiceAccount
-metadata: { name: oon-runtime, namespace: ${context.namespace} }
+metadata: { name: ${identity.serviceAccount}, namespace: ${normalized.namespace} }
 automountServiceAccountToken: false
 ---
 apiVersion: v1
 kind: LimitRange
-metadata: { name: oon-runtime-defaults, namespace: ${context.namespace} }
+metadata: { name: oon-runtime-defaults, namespace: ${normalized.namespace} }
 spec:
   limits:
     - type: Container
@@ -62,13 +79,13 @@ spec:
 ---
 apiVersion: v1
 kind: ResourceQuota
-metadata: { name: oon-runtime-quota, namespace: ${context.namespace} }
+metadata: { name: oon-runtime-quota, namespace: ${normalized.namespace} }
 spec:
   hard: { requests.cpu: "2", requests.memory: 2Gi, limits.cpu: "4", limits.memory: 4Gi, pods: "20", services: "10" }
 ---
 apiVersion: networking.k8s.io/v1
 kind: NetworkPolicy
-metadata: { name: oon-runtime-baseline, namespace: ${context.namespace} }
+metadata: { name: oon-runtime-baseline, namespace: ${normalized.namespace} }
 spec:
   podSelector: {}
   policyTypes: [Ingress, Egress]
@@ -82,35 +99,37 @@ spec:
 }
 
 function runtimeManifest({ context, infra, imageRef, profile = "small" }) {
+  const normalized = canonicalRuntimeContext(context);
+  const identity = normalized.deliveryTechnicalIdentity;
   const resources = RESOURCE_PROFILES[profile] || RESOURCE_PROFILES.small;
-  const releaseLabel = kubernetesLabelValue(context.releaseId);
-  const releaseAnnotation = JSON.stringify(String(context.releaseId));
+  const releaseLabel = kubernetesLabelValue(normalized.releaseId);
+  const releaseAnnotation = JSON.stringify(String(normalized.releaseId));
   return `apiVersion: apps/v1
 kind: Deployment
 metadata:
-  name: ${context.appCode}
-  namespace: ${context.namespace}
+  name: ${normalized.appCode}
+  namespace: ${normalized.namespace}
 spec:
   replicas: 1
   selector:
-    matchLabels: { app.kubernetes.io/name: ${context.appCode} }
+    matchLabels: { app.kubernetes.io/name: ${normalized.appCode} }
   template:
     metadata:
       labels:
-        app.kubernetes.io/name: ${context.appCode}
+        app.kubernetes.io/name: ${normalized.appCode}
         app.kubernetes.io/part-of: oon-central
-        oon.dev/release-id: ${releaseLabel}
+        oon.dev/release-id: ${releaseLabel}${podIdentityLabels(identity)}
       annotations:
         oon.dev/release-id: ${releaseAnnotation}
     spec:
-      serviceAccountName: oon-runtime
+      serviceAccountName: ${identity.serviceAccount}
       imagePullSecrets: [{ name: ${infra.REGISTRY_PULL_SECRET_NAME || "ghcr-oon"} }]
       containers:
         - name: central
           image: ${imageRef}
           imagePullPolicy: IfNotPresent
           ports: [{ name: http, containerPort: 8080 }]
-          envFrom: [{ secretRef: { name: oon-runtime } }]
+          envFrom: [{ secretRef: { name: ${identity.secret} } }]
           resources:
             requests: { cpu: ${resources.cpuRequest}, memory: ${resources.memoryRequest} }
             limits: { cpu: ${resources.cpuLimit}, memory: ${resources.memoryLimit} }
@@ -123,28 +142,28 @@ spec:
 ---
 apiVersion: v1
 kind: Service
-metadata: { name: ${context.appCode}, namespace: ${context.namespace} }
+metadata: { name: ${normalized.appCode}, namespace: ${normalized.namespace} }
 spec:
-  selector: { app.kubernetes.io/name: ${context.appCode} }
+  selector: { app.kubernetes.io/name: ${normalized.appCode} }
   ports: [{ name: http, port: 80, targetPort: http }]
 ---
 apiVersion: networking.k8s.io/v1
 kind: Ingress
 metadata:
-  name: ${context.appCode}
-  namespace: ${context.namespace}
+  name: ${normalized.appCode}
+  namespace: ${normalized.namespace}
   annotations: { cert-manager.io/cluster-issuer: ${infra.CLUSTER_ISSUER} }
 spec:
   ingressClassName: ${infra.INGRESS_CLASS}
-  tls: [{ hosts: [${context.hostname}], secretName: ${context.appCode}-tls }]
+  tls: [{ hosts: [${normalized.hostname}], secretName: ${identity.tlsSecret} }]
   rules:
-    - host: ${context.hostname}
+    - host: ${normalized.hostname}
       http:
         paths:
           - path: /
             pathType: Prefix
             backend:
-              service: { name: ${context.appCode}, port: { name: http } }
+              service: { name: ${normalized.appCode}, port: { name: http } }
 `;
 }
 
@@ -159,26 +178,36 @@ function copyPullSecret(namespace, infra) {
 }
 
 function applyRuntimeSecret({ context, mongoUri, encryptionKey, extraSecrets = {} }) {
+  const normalized = canonicalRuntimeContext(context);
+  const identity = normalized.deliveryTechnicalIdentity;
   const literals = {
     MONGO_URI: mongoUri,
     NODE_ENV: "production",
-    APP_ENVIRONMENT: context.environment,
-    APP_CODE: context.appCode,
-    PUBLIC_APP_URL: context.publicUrl,
-    CENTRAL_ATIVACAO_URL: context.activationApiUrl,
-    CENTRAL_ATIVACAO_API_URL: context.activationApiUrl,
+    APP_ENVIRONMENT: normalized.environment,
+    APP_CODE: normalized.appCode,
+    PUBLIC_APP_URL: normalized.publicUrl,
+    CENTRAL_ATIVACAO_URL: normalized.activationApiUrl,
+    CENTRAL_ATIVACAO_API_URL: normalized.activationApiUrl,
     INSTANCE_CREDENTIAL_ENCRYPTION_KEY: encryptionKey,
+    ...(identity.mode === "canonical"
+      ? {
+        OON_INSTANCE_UID: identity.instanceUid,
+        OON_TECHNICAL_IDENTITY_VERSION: String(identity.version),
+      }
+      : {}),
     ...extraSecrets,
   };
-  const args = ["-n", context.namespace, "create", "secret", "generic", "oon-runtime"];
+  const args = ["-n", normalized.namespace, "create", "secret", "generic", identity.secret];
   for (const [key, value] of Object.entries(literals)) args.push(`--from-literal=${key}=${value}`);
   args.push("--dry-run=client", "-o", "yaml");
   applyYaml(kubectl(args, { capture: true }));
 }
 
 async function provisionRuntime({ context, extraSecrets = {} }) {
+  const normalized = canonicalRuntimeContext(context);
+  const identity = normalized.deliveryTechnicalIdentity;
   const infra = validateInfraFromCluster().config;
-  applyYaml(baselineManifest({ context, infra }));
+  applyYaml(baselineManifest({ context: normalized, infra }));
 
   const platformNamespace = infra.PLATFORM_NAMESPACE || "oon-system";
   const adminSecretName = infra.MONGO_ADMIN_SECRET_NAME || "oon-mongo-admin";
@@ -205,7 +234,7 @@ async function provisionRuntime({ context, extraSecrets = {} }) {
     "DIGITALOCEAN_DATABASE_CLUSTER_ID",
   );
 
-  let mongoUri = readSecret(context.namespace, "oon-runtime", "MONGO_URI");
+  let mongoUri = readSecret(normalized.namespace, identity.secret, "MONGO_URI");
   let databaseName = "";
   let credentialRotated = false;
 
@@ -225,8 +254,9 @@ async function provisionRuntime({ context, extraSecrets = {} }) {
   if (!mongoUri) {
     const provisioned = await provisionMongo({
       adminUri,
-      appCode: context.appCode,
-      environment: context.environment,
+      appCode: normalized.appCode,
+      environment: normalized.environment,
+      ...(identity.mode === "canonical" ? { instanceUid: identity.instanceUid } : {}),
       provisioner: mongoProvisioner,
       digitalOceanToken,
       digitalOceanClusterId,
@@ -238,20 +268,32 @@ async function provisionRuntime({ context, extraSecrets = {} }) {
 
   const encryptionKey =
     readSecret(
-      context.namespace,
-      "oon-runtime",
+      normalized.namespace,
+      identity.secret,
       "INSTANCE_CREDENTIAL_ENCRYPTION_KEY",
     ) || randomSecret(48);
-  applyRuntimeSecret({ context, mongoUri, encryptionKey, extraSecrets });
-  return { infra, databaseName, credentialRotated };
+  applyRuntimeSecret({ context: normalized, mongoUri, encryptionKey, extraSecrets });
+  return {
+    infra,
+    databaseName,
+    credentialRotated,
+    ...(identity.mode === "canonical" ? { technicalIdentity: identity } : {}),
+  };
 }
 
 function deployRuntime({ context, infra, imageDigest, resourceProfile = "small" }) {
-  copyPullSecret(context.namespace, infra);
-  const imageRef = `${context.imageRepository}@${imageDigest}`;
-  applyYaml(runtimeManifest({ context, infra, imageRef, profile: resourceProfile }));
-  kubectl(["-n", context.namespace, "rollout", "status", `deployment/${context.appCode}`, "--timeout=10m"]);
-  return { infraVersion: infra.INFRA_SCHEMA_VERSION, imageRef };
+  const normalized = canonicalRuntimeContext(context);
+  copyPullSecret(normalized.namespace, infra);
+  const imageRef = `${normalized.imageRepository}@${imageDigest}`;
+  applyYaml(runtimeManifest({ context: normalized, infra, imageRef, profile: resourceProfile }));
+  kubectl(["-n", normalized.namespace, "rollout", "status", `deployment/${normalized.appCode}`, "--timeout=10m"]);
+  return {
+    infraVersion: infra.INFRA_SCHEMA_VERSION,
+    imageRef,
+    ...(normalized.deliveryTechnicalIdentity.mode === "canonical"
+      ? { technicalIdentity: normalized.deliveryTechnicalIdentity }
+      : {}),
+  };
 }
 
 async function waitHttp(url, { timeoutMs = 300000, expectedStatus = 200 } = {}) {
@@ -269,19 +311,20 @@ async function waitHttp(url, { timeoutMs = 300000, expectedStatus = 200 } = {})
 }
 
 async function activateMember(context) {
-  const statusResponse = await waitHttp(`${context.publicUrl}/api/ativacao/status`);
+  const normalized = canonicalRuntimeContext(context);
+  const statusResponse = await waitHttp(`${normalized.publicUrl}/api/ativacao/status`);
   const status = await statusResponse.json();
   if (status.status === "ativa") return { alreadyActive: true, instanceId: status.instanceId };
-  if (!context.activationCode) throw new Error("Instância não está ativa e não há código de ativação autorizado.");
-  const response = await fetch(`${context.publicUrl}/api/ativacao/concluir`, {
+  if (!normalized.activationCode) throw new Error("Instância não está ativa e não há código de ativação autorizado.");
+  const response = await fetch(`${normalized.publicUrl}/api/ativacao/concluir`, {
     method: "POST",
-    headers: { "Content-Type": "application/json", "Idempotency-Key": context.releaseId },
+    headers: { "Content-Type": "application/json", "Idempotency-Key": normalized.releaseId },
     body: JSON.stringify({
-      codigoAtivacao: context.activationCode,
-      nomeInstancia: `${context.appCode} dev`,
+      codigoAtivacao: normalized.activationCode,
+      nomeInstancia: `${normalized.appCode} dev`,
       parametrosGlobais: {
-        nomeInstancia: `${context.appCode} dev`, ambiente: context.environment,
-        urlPublica: context.publicUrl, emailAdministrativo: context.administrativeEmail,
+        nomeInstancia: `${normalized.appCode} dev`, ambiente: normalized.environment,
+        urlPublica: normalized.publicUrl, emailAdministrativo: normalized.administrativeEmail,
         idioma: "pt-BR", timezone: "America/Sao_Paulo", moeda: "BRL", pais: "BR", formatoData: "DD/MM/YYYY",
       },
       parametrosAplicacao: {},
@@ -292,4 +335,18 @@ async function activateMember(context) {
   return data;
 }
 
-module.exports = { RESOURCE_PROFILES, randomSecret, dnsLabel, kubernetesLabelValue, provisionMongo, validateMongoUri, baselineManifest, runtimeManifest, provisionRuntime, deployRuntime, waitHttp, activateMember };
+module.exports = {
+  RESOURCE_PROFILES,
+  randomSecret,
+  dnsLabel,
+  kubernetesLabelValue,
+  canonicalRuntimeContext,
+  provisionMongo,
+  validateMongoUri,
+  baselineManifest,
+  runtimeManifest,
+  provisionRuntime,
+  deployRuntime,
+  waitHttp,
+  activateMember,
+};

package/src/delivery/technicalIdentity.js

@@ -0,0 +1,140 @@
+"use strict";
+
+const technical = require("../core/technicalIdentity");
+
+const SUPPORTED_DELIVERY_IDENTITY_VERSION = 1;
+const CANONICAL_FIELDS = Object.freeze([
+  "version",
+  "appCode",
+  "instanceUid",
+  "environment",
+  "resourceBase",
+  "namespace",
+  "database",
+  "mongoUsername",
+  "serviceAccount",
+  "secret",
+  "provisionJob",
+  "frontendDnsLabel",
+  "backendDnsLabel",
+  "tlsSecret",
+]);
+const CANONICAL_SIGNAL_FIELDS = Object.freeze([
+  "instanceUid",
+  "technicalIdentityVersion",
+  "technicalInstanceId",
+  "technicalIdentity",
+]);
+
+function deliveryIdentityError(code, message, details = {}) {
+  const error = new Error(message);
+  error.name = "DeliveryTechnicalIdentityError";
+  error.code = code;
+  error.details = details;
+  return error;
+}
+
+function hasOwn(object, field) {
+  return Object.prototype.hasOwnProperty.call(object || {}, field);
+}
+
+function hasCanonicalIdentitySignal(context = {}) {
+  return CANONICAL_SIGNAL_FIELDS.some((field) => hasOwn(context, field));
+}
+
+function legacyDeliveryIdentity(context = {}) {
+  return Object.freeze({
+    mode: "legacy",
+    version: 0,
+    appCode: String(context.appCode || ""),
+    environment: String(context.environment || ""),
+    namespace: String(context.namespace || ""),
+    serviceAccount: "oon-runtime",
+    secret: "oon-runtime",
+    tlsSecret: `${String(context.appCode || "")}-tls`,
+  });
+}
+
+function assertProjection(canonical, context = {}) {
+  const mismatches = [];
+  if (context.namespace != null && String(context.namespace) !== canonical.namespace) {
+    mismatches.push("namespace");
+  }
+
+  if (hasOwn(context, "technicalIdentity")) {
+    const projected = context.technicalIdentity;
+    if (!projected || typeof projected !== "object" || Array.isArray(projected)) {
+      throw deliveryIdentityError(
+        "DELIVERY_TECHNICAL_IDENTITY_PROJECTION_INVALID",
+        "A projeção da identidade técnica do delivery é inválida.",
+      );
+    }
+    for (const field of CANONICAL_FIELDS) {
+      if (projected[field] == null) continue;
+      if (String(projected[field]) !== String(canonical[field])) mismatches.push(field);
+    }
+  }
+
+  if (mismatches.length) {
+    throw deliveryIdentityError(
+      "DELIVERY_TECHNICAL_IDENTITY_MISMATCH",
+      "O contexto de delivery diverge da identidade técnica canônica.",
+      { mismatches: [...new Set(mismatches)] },
+    );
+  }
+}
+
+function resolveDeliveryTechnicalIdentity(context = {}, { requireCanonical = false } = {}) {
+  if (!hasCanonicalIdentitySignal(context)) {
+    if (requireCanonical) {
+      throw deliveryIdentityError(
+        "DELIVERY_TECHNICAL_IDENTITY_REQUIRED",
+        "O contexto de delivery exige identidade técnica canônica.",
+      );
+    }
+    return legacyDeliveryIdentity(context);
+  }
+
+  if (context.instanceUid == null || context.technicalIdentityVersion == null) {
+    throw deliveryIdentityError(
+      "DELIVERY_TECHNICAL_IDENTITY_INCOMPLETE",
+      "O contexto de delivery possui identidade técnica parcial.",
+    );
+  }
+  if (Number(context.technicalIdentityVersion) !== SUPPORTED_DELIVERY_IDENTITY_VERSION) {
+    throw deliveryIdentityError(
+      "DELIVERY_TECHNICAL_IDENTITY_VERSION_UNSUPPORTED",
+      "A versão da identidade técnica do delivery não é suportada.",
+      { received: context.technicalIdentityVersion, supported: SUPPORTED_DELIVERY_IDENTITY_VERSION },
+    );
+  }
+
+  const canonical = technical.technicalIdentity({
+    appCode: context.appCode,
+    instanceUid: context.instanceUid,
+    environment: context.environment,
+  });
+  assertProjection(canonical, context);
+  return Object.freeze({ mode: "canonical", ...canonical });
+}
+
+function canonicalizeDeliveryContext(context = {}, options = {}) {
+  const identity = resolveDeliveryTechnicalIdentity(context, options);
+  if (identity.mode !== "canonical") {
+    return Object.freeze({ ...context, deliveryTechnicalIdentity: identity });
+  }
+  return Object.freeze({
+    ...context,
+    namespace: identity.namespace,
+    deliveryTechnicalIdentity: identity,
+  });
+}
+
+module.exports = Object.freeze({
+  CANONICAL_FIELDS,
+  CANONICAL_SIGNAL_FIELDS,
+  SUPPORTED_DELIVERY_IDENTITY_VERSION,
+  canonicalizeDeliveryContext,
+  hasCanonicalIdentitySignal,
+  resolveDeliveryTechnicalIdentity,
+});