@aifabrix/builder 2.60.0 → 2.62.0

package/lib/datasource/capability/upsert-test-scaffold.js

@@ -0,0 +1,189 @@
+/**
+ * Build a no-duplicate upsert proof from author-owned scenario facts.
+ *
+ * @fileoverview Safe testPayload scaffolding for datasource capability upsert
+ */
+
+'use strict';
+
+const { deepClone } = require('./copy-operations');
+
+const RUN_TOKEN = /\{\{\s*testRunId\s*\}\}/i;
+
+function scenarioInput(scenario) {
+  const input = scenario?.input;
+  if (!input || typeof input !== 'object' || Array.isArray(input)) return null;
+  const properties = input.properties;
+  return properties && typeof properties === 'object' && !Array.isArray(properties)
+    ? properties
+    : input;
+}
+
+function scalar(value) {
+  return value !== null && ['string', 'number', 'boolean'].includes(typeof value);
+}
+
+function identityFromInput(input, identityFields) {
+  if (!input) return null;
+  const entries = identityFields.map((field) => [field, input[field]]);
+  if (entries.some(([, value]) => !scalar(value) || value === '')) return null;
+  return Object.fromEntries(entries);
+}
+
+function sameIdentity(first, second, identityFields) {
+  return identityFields.every((field) => first[field] === second[field]);
+}
+
+function isCollisionSafe(identity) {
+  return Object.values(identity).some((value) =>
+    typeof value === 'string' && RUN_TOKEN.test(value)
+  );
+}
+
+function profileFields(doc, targetKey) {
+  const profile = doc.exposed?.profiles?.[targetKey];
+  if (Array.isArray(profile)) return profile;
+  return Array.isArray(profile?.attributes) ? profile.attributes : [];
+}
+
+function changedPublishedField(doc, targetKey, first, second, identityFields) {
+  const identity = new Set(identityFields);
+  const published = new Set(profileFields(doc, targetKey));
+  return Object.keys(first).find((field) =>
+    !identity.has(field) && published.has(field) && scalar(first[field]) &&
+    scalar(second[field]) && first[field] !== second[field]
+  ) || null;
+}
+
+function analyzeWritePair(doc, targetKey, identityFields, firstRow, secondRow) {
+  const first = scenarioInput(firstRow);
+  const second = scenarioInput(secondRow);
+  const firstIdentity = identityFromInput(first, identityFields);
+  const secondIdentity = identityFromInput(second, identityFields);
+  if (!firstIdentity || !secondIdentity) return { reason: 'both writes must contain every business identity field' };
+  if (!sameIdentity(firstIdentity, secondIdentity, identityFields)) {
+    return { reason: 'the two writes must use the same business identity values' };
+  }
+  if (!isCollisionSafe(firstIdentity)) {
+    return { reason: 'the business identity must include {{testRunId}} to isolate each live run' };
+  }
+  const changedField = changedPublishedField(
+    doc, targetKey, first, second, identityFields
+  );
+  if (!changedField) {
+    return { reason: 'the second write must change one published non-identity scalar field' };
+  }
+  return { first, second, identity: firstIdentity, changedField };
+}
+
+function exactLookup(operation, input, expectedRows, identityKey) {
+  return {
+    operation,
+    input: deepClone(input),
+    identityKey,
+    matchMode: 'exactIdentities',
+    expectedRows: deepClone(expectedRows)
+  };
+}
+
+function expectedRow(identity, changedField, value) {
+  return { ...deepClone(identity), [changedField]: value };
+}
+
+function hasExactProof(scenarios, index, targetKey, lookupKey, facts) {
+  const rows = scenarios.slice(index, index + 5);
+  if (rows.length !== 5) return false;
+  const operations = rows.map((row) => row?.operation);
+  if (operations.join('|') !== [lookupKey, targetKey, lookupKey, targetKey, lookupKey].join('|')) {
+    return false;
+  }
+  const [before, , afterFirst, , afterSecond] = rows;
+  return [before, afterFirst, afterSecond].every((row) =>
+    row?.matchMode === 'exactIdentities' && row?.identityKey === facts.changedField
+  ) && Array.isArray(before.expectedRows) && before.expectedRows.length === 0 &&
+    afterFirst.expectedRows?.length === 1 && afterSecond.expectedRows?.length === 1 &&
+    afterFirst.expectedRows?.[0]?.[facts.changedField] === facts.first[facts.changedField] &&
+    afterSecond.expectedRows?.[0]?.[facts.changedField] === facts.second[facts.changedField];
+}
+
+function findExistingProof(doc, scenarios, targetKey, lookupKey, identityFields) {
+  for (let index = 0; index <= scenarios.length - 5; index += 1) {
+    const facts = analyzeWritePair(
+      doc, targetKey, identityFields, scenarios[index + 1], scenarios[index + 3]
+    );
+    if (!facts.reason && hasExactProof(scenarios, index, targetKey, lookupKey, facts)) return true;
+  }
+  return false;
+}
+
+function findAdjacentWrites(doc, scenarios, targetKey, identityFields) {
+  let lastReason = 'two adjacent enabled upsert scenarios are required';
+  for (let index = 0; index < scenarios.length - 1; index += 1) {
+    const first = scenarios[index];
+    const second = scenarios[index + 1];
+    if (first?.operation !== targetKey || second?.operation !== targetKey) continue;
+    if (first.enabled === false || second.enabled === false) continue;
+    const facts = analyzeWritePair(doc, targetKey, identityFields, first, second);
+    if (!facts.reason) return { index, facts };
+    lastReason = facts.reason;
+  }
+  return { reason: lastReason };
+}
+
+function insufficientIssue(reason) {
+  return {
+    code: 'UPSERT-TEST-DATA-INSUFFICIENT',
+    severity: 'blocking',
+    ownership: 'test-payload',
+    aiFixable: false,
+    message: `Safe --test scaffolding was not generated: ${reason}; no values were fabricated`,
+    consequence: 'A weaker generated case could provide false no-duplicate confidence.',
+    remediation: ['Author two adjacent upsert inputs with the same isolated identity and one changed published field, then rerun --test.'],
+    prevention: 'Keep collision-safe two-write facts with the datasource test payload.',
+    residualRisk: 'Upsert remains unproven until the exact live chain passes.'
+  };
+}
+
+function buildProofRows(lookupKey, facts) {
+  const firstExpected = expectedRow(
+    facts.identity, facts.changedField, facts.first[facts.changedField]
+  );
+  const secondExpected = expectedRow(
+    facts.identity, facts.changedField, facts.second[facts.changedField]
+  );
+  return [
+    exactLookup(lookupKey, facts.identity, [], facts.changedField),
+    exactLookup(lookupKey, facts.identity, [firstExpected], facts.changedField),
+    exactLookup(lookupKey, facts.identity, [secondExpected], facts.changedField)
+  ];
+}
+
+function scaffoldUpsertTests(originalDoc, analysis, targetKey = 'upsert') {
+  const scenarios = originalDoc.testPayload?.scenarios;
+  const lookupKey = analysis?.selectedLookup?.operationKey;
+  const identities = Array.isArray(analysis?.identityFields) ? analysis.identityFields : [];
+  if (!Array.isArray(scenarios) || !lookupKey || identities.length === 0) {
+    return { changed: false, issue: insufficientIssue('required scenarios or exact lookup facts are missing') };
+  }
+  if (findExistingProof(originalDoc, scenarios, targetKey, lookupKey, identities)) {
+    return { changed: false, doc: originalDoc, patchOperations: [], updatedSections: [] };
+  }
+  const pair = findAdjacentWrites(originalDoc, scenarios, targetKey, identities);
+  if (pair.reason) return { changed: false, issue: insufficientIssue(pair.reason) };
+  const [before, afterFirst, afterSecond] = buildProofRows(lookupKey, pair.facts);
+  const doc = deepClone(originalDoc);
+  doc.testPayload.scenarios.splice(pair.index, 2,
+    before, scenarios[pair.index], afterFirst, scenarios[pair.index + 1], afterSecond);
+  return {
+    changed: true,
+    doc,
+    patchOperations: [{ op: 'replace', path: '/testPayload/scenarios', value: doc.testPayload.scenarios }],
+    updatedSections: ['testPayload.scenarios: upsert no-duplicate proof']
+  };
+}
+
+module.exports = {
+  scaffoldUpsertTests,
+  analyzeWritePair,
+  insufficientIssue
+};

package/lib/datasource/validate.js

@@ -23,6 +23,8 @@ const { validateFieldReferences } = require('./field-reference-validator');
 const { validateAbac } = require('./abac-validator');
 const { buildDatasourceValidateSummary } = require('./datasource-validate-summary');
 
+const { validateBinaryDocumentsContract } = require('./binary-documents-validator');
+
 const DATASOURCE_CONFIG_EXTENSIONS = new Set(['.json', '.yaml', '.yml']);
 const EXCLUDE_CONFIG_NAMES = new Set([
   'application.json',
@@ -242,12 +244,14 @@ async function validateDatasourceFile(filePathOrKey) {
     };
   }
 
+  const binary = validateBinaryDocumentsContract(parsed);
+  const warnings = binary.warnings.map(issue => `${issue.code}: ${issue.message}`);
   const postSchemaErrors = collectPostSchemaErrors(parsed);
   if (postSchemaErrors.length > 0) {
     return {
       valid: false,
       errors: postSchemaErrors,
-      warnings: [],
+      warnings,
       resolvedPath: filePath,
       summary
     };
@@ -256,7 +260,7 @@ async function validateDatasourceFile(filePathOrKey) {
   return {
     valid: true,
     errors: [],
-    warnings: [],
+    warnings,
     resolvedPath: filePath,
     summary
   };
@@ -269,7 +273,8 @@ async function validateDatasourceFile(filePathOrKey) {
 function collectPostSchemaErrors(parsed) {
   return [
     ...validateFieldReferences(parsed),
-    ...validateAbac(parsed)
+    ...validateAbac(parsed),
+    ...validateBinaryDocumentsContract(parsed).errors.map(issue => `${issue.code}: ${issue.message}`)
   ];
 }
 
@@ -303,12 +308,14 @@ function validateDatasourceParsed(parsed) {
     };
   }
 
+  const binary = validateBinaryDocumentsContract(parsed);
+  const warnings = binary.warnings.map(issue => `${issue.code}: ${issue.message}`);
   const postSchemaErrors = collectPostSchemaErrors(parsed);
   if (postSchemaErrors.length > 0) {
     return {
       valid: false,
       errors: postSchemaErrors,
-      warnings: [],
+      warnings,
       summary
     };
   }
@@ -316,7 +323,7 @@ function validateDatasourceParsed(parsed) {
   return {
     valid: true,
     errors: [],
-    warnings: [],
+    warnings,
     summary
   };
 }

package/lib/deployment/installation/index.js

@@ -6,8 +6,14 @@
  * All input validation happens before any filesystem, network or cloud mutation.
  */
 
-const { resolveStageInput, validateResourceGroupKey, ENVIRONMENT_STAGES } = require('./stage-input');
+const {
+  resolveStageInput,
+  validateResourceGroupKey,
+  validateStage,
+  ENVIRONMENT_STAGES
+} = require('./stage-input');
 const { openWorkspace } = require('./workspace');
+const { isLocalInstallationKey } = require('./local-installation');
 
 /**
  * Runs one installation workspace stage.
@@ -18,6 +24,13 @@ const { openWorkspace } = require('./workspace');
  */
 async function deployInstallationStage(resourceGroupKey, options, deps = {}) {
   const resourceGroup = validateResourceGroupKey(resourceGroupKey);
+  // A local installation owns its environments itself: no workspace, no Azure template and
+  // no Controller round trip. `register` still goes the shared route, because a local
+  // install registers with Mori exactly as any other does.
+  if (isLocalInstallationKey(resourceGroup) && ENVIRONMENT_STAGES.includes(validateStage(options.stage))) {
+    const { runLocalEnvironmentStage } = require('./local-environment-stage');
+    return runLocalEnvironmentStage(resourceGroup, validateStage(options.stage), deps);
+  }
   const workspace = openWorkspace(resourceGroup, { root: deps.root });
   const input = resolveStageInput(resourceGroup, options, workspace.infra?.vendor?.value);
   const base = { stage: input.stage, vendor: input.vendor, workspaceDir: workspace.dir };

package/lib/deployment/installation/infra-catalog.js

@@ -88,6 +88,7 @@ const PARAMETER_CATALOG = Object.freeze({
   enablePostgresPublicAccess: { kind: 'allowMyIp', source: 'allowMyIp', description: 'Default off; enabled only while allowMyIp grants the validated caller IPv4 /32 for testing.' },
   allowedIPs: { kind: 'allowMyIp', source: 'allowMyIpOrUser', description: 'Explicit CIDRs for PostgreSQL, Key Vault, and Storage; allowMyIp merges the resolved caller IPv4 /32.' },
   adminPassword: { kind: 'secretEnv', env: 'ADMIN_PASSWORD', required: true, description: 'Installation administrator password.' },
+  adminEmail: { kind: 'file', source: 'user', required: true, description: 'Email of the initial platform administrator, used for the installation welcome. Required: the template sets no default and enforces minLength.' },
   deploymentEnvironment: { kind: 'file', source: 'templateDefault', description: 'Vendor deployment profile.' },
   keycloakVerifyAudience: { kind: 'file', source: 'templateDefault', description: 'Enable Keycloak audience verification.' },
   encryptionKey: { kind: 'secretEnv', env: 'ENCRYPTION_KEY', required: true, description: 'Application/data encryption key.' },
@@ -99,11 +100,13 @@ const PARAMETER_CATALOG = Object.freeze({
   deployRegistryRoleAssignment: { kind: 'parameterDefault', defaultFrom: 'deployRoleAssignments', source: 'templateDefault', description: 'Deploy the AcrPull grant on the container registry. False while credential image pull is in effect, because that grant lives in the registry resource group, which a customer installation cannot reach; restored for managed identity.' },
   moriBaseUrl: { kind: 'file', source: 'registration', required: true, description: 'Mori service base URL.' },
   moriLicensePublicKey: { kind: 'file', source: 'registration', required: false, description: 'Mori licence issuer public key (SPKI PEM); empty leaves the installation unpinned and it then refuses every licence.' },
+  moriPolicyPublicKey: { kind: 'file', source: 'registration', required: false, description: 'Mori policy signing anchor (SPKI PEM), a different pair from the licence key; empty leaves the policy bundle checkable only against the key it carries, which proves nothing.' },
   moriLicenseIssuer: { kind: 'file', source: 'registration', required: false, description: 'Expected iss claim on a Mori licence.' },
   entraIdClientId: { kind: 'deferred', description: 'Not collected or sent by infra; issued/configured during later Entra provider onboarding.' },
   entraIdClientSecret: { kind: 'deferred', description: 'Not collected or sent by infra; issued/configured during later Entra provider onboarding.' },
   entraIdTenantId: { kind: 'deferred', description: 'Customer Entra provider tenant; distinct from the Azure subscription directory tenant and configured later.' },
   licenseEdition: { kind: 'license', source: 'cliOrFile', description: 'License requested from Mori during tenant activation: COMMUNITY, STANDARD or ENTERPRISE, or an Azure Marketplace subscription ID. Standard/Enterprise by name is a 30-day evaluation.' },
+  installationResourceModel: { kind: 'file', source: 'templateDefault', description: 'Initial installation topology: shared for Community and Standard, dedicated for Enterprise DEV. Defaults to shared and is protected by Azure application configuration. It records the topology the installation starts in and grants no later licence entitlement, so it is not a licence input.' },
   onboardingMode: { kind: 'onboarding', source: 'workspacePolicy', description: 'Miso onboarding mode (ONBOARDING_MODE); Builder installations use saasDirect, Marketplace customer installations use customerOwned.' },
   capacityProfile: { kind: 'capacity', source: 'workspacePreset', description: 'Infrastructure sizing profile (s, m, l, xl) selecting compute and PostgreSQL SKUs. Derived from the workspace preset so the two cannot drift; set it with --preset.' },
   misoImageTag: { kind: 'file', source: 'templateDefault', description: 'Miso container image tag.' },

package/lib/deployment/installation/local-environment-stage.js

@@ -0,0 +1,285 @@
+/**
+ * `env deploy local --stage dev|tst|pro` — the local environment stage (plan 210.0).
+ *
+ * The Azure path creates an environment in the Miso Controller for an Azure installation.
+ * This is the same sentence spoken locally: create this environment's resources inside the
+ * local installation. Increment 1 covers the databases and roles; the promoted container and
+ * the front-door routing follow.
+ *
+ * Every environment shares one Postgres server here, so the names carry the environment —
+ * `{env}_{appKey}_{logical}` with a `_user` role, mirroring Miso 227.3 exactly rather than
+ * inventing a local scheme. See `lib/parameters/physical-database-naming.js`.
+ *
+ * @fileoverview Local environment provisioning for env deploy
+ */
+
+'use strict';
+
+const logger = require('../../utils/logger');
+const { resolveDatabaseNamesWithAdoption } = require('../../parameters/database-adoption');
+const { parseDatabaseSecretKey } = require('../../parameters/database-secret-values');
+const { resolveLocalInstallationName } = require('./local-installation');
+
+/**
+ * Applications that exist **once per environment**.
+ *
+ * The dataplane and nothing else. Keycloak, the Miso Controller, builder-api and
+ * integration-server are **platform services**: one per platform, living in `miso`, shared by
+ * every environment. There is one ACR and one Keycloak, not one each per environment.
+ *
+ * This is why the list also bounds the databases. Creating `pro_keycloak_keycloak` would
+ * stand up a second Keycloak's database for a Keycloak that does not exist, and nothing
+ * would ever connect to it.
+ */
+const ENVIRONMENT_WORKLOAD_APP_KEYS = Object.freeze(['dataplane']);
+
+/**
+ * The databases this environment needs, with their physical names resolved together.
+ *
+ * Resolved as one list so a caller cannot take the database name and leave the role
+ * verbatim, which is the shape of the defect 227.3 fixed.
+ *
+ * Platform-service databases are **excluded**: they belong to the single shared platform in
+ * `miso`, which `setup` installs, not to a workload environment.
+ *
+ * An existing unprefixed database is **adopted** rather than renamed: renaming on a live
+ * server means dropping and recreating, which means losing the data. Only `dev` may adopt,
+ * because everything a pre-environment install created belongs to it.
+ *
+ * @param {string} envKey - Environment key
+ * @param {{ dbName: string, secretKey: string }[]} slots - Platform database slots
+ * @param {Iterable<string>} [existingDatabaseNames] - Databases the server already has
+ * @returns {{ logicalName: string, appKey: string, databaseName: string, roleName: string, secretKey: string, origin: string }[]}
+ * @throws {Error} When a slot's secret key cannot be parsed for its owning application
+ */
+function resolveEnvironmentDatabasePlan(envKey, slots, existingDatabaseNames) {
+  const forEnvironment = slots.filter((slot) => {
+    const parsed = parseDatabaseSecretKey(slot.secretKey);
+    return parsed && ENVIRONMENT_WORKLOAD_APP_KEYS.includes(parsed.appKey);
+  });
+  return forEnvironment.map((slot) => {
+    const parsed = parseDatabaseSecretKey(slot.secretKey);
+    if (!parsed) {
+      throw new Error(
+        `Cannot determine the owning application for database "${slot.dbName}" from secret ` +
+          `key "${slot.secretKey}".`
+      );
+    }
+    const names = resolveDatabaseNamesWithAdoption({
+      logicalName: slot.dbName,
+      appKey: parsed.appKey,
+      environment: envKey,
+      existingDatabaseNames
+    });
+    return {
+      logicalName: names.logicalName,
+      appKey: parsed.appKey,
+      databaseName: names.databaseName,
+      roleName: names.roleName,
+      origin: names.origin,
+      // The catalog key, which the strict resolver already scopes per environment. Not
+      // `names.passwordSecretKey`: which grammar names this secret is open with Miso, and
+      // the catalog key is the one every existing consumer reads.
+      secretKey: slot.secretKey
+    };
+  });
+}
+
+/**
+ * Create the databases and roles for one environment.
+ *
+ * @async
+ * @param {string} envKey - Environment key
+ * @param {Object} deps - Injected collaborators
+ * @returns {Promise<string[]>} Database names ensured
+ */
+async function ensureEnvironmentDatabases(envKey, deps) {
+  const bootstrap = deps.bootstrap || require('../../utils/postgres-platform-bootstrap');
+  const { container, adminPassword, secrets } = await bootstrap.resolveBootstrapContext();
+  const existing = await bootstrap.listExistingDatabaseNames(container, adminPassword);
+  const plan = resolveEnvironmentDatabasePlan(envKey, bootstrap.PLATFORM_DATABASE_SLOTS, existing);
+  const ensured = [];
+  for (const item of plan) {
+    const password = bootstrap.extractPasswordFromUrlOrValue(secrets[item.secretKey]);
+    if (!password || !password.trim()) {
+      // Name the physical secret, which for an application-scoped key carries the owning
+      // application before the key. Quoting `<env>-<key>` here would send someone to create
+      // a name nothing reads.
+      const { computePhysicalSecretName } = require('../../parameters/physical-secret-name');
+      const physical = computePhysicalSecretName(item.secretKey, { environment: envKey });
+      throw new Error(
+        `Secret ${item.secretKey} is missing or empty for environment ${envKey}. ` +
+          `Add it with: aifabrix secret set ${physical} <value>`
+      );
+    }
+    await bootstrap.ensureRoleAndDatabase(
+      container,
+      item.databaseName,
+      item.roleName,
+      password.trim(),
+      adminPassword
+    );
+    if (item.origin === 'adopted') {
+      logger.log(`Adopted existing database ${item.databaseName} for ${envKey}`);
+    }
+    ensured.push(item.databaseName);
+  }
+  return ensured;
+}
+
+/**
+ * Ask Miso whether this environment may exist, before anything is created.
+ *
+ * **Editions are Miso's, not Builder's.** Whether a licence permits `tst` or `pro` is not a
+ * question this repository answers or caches: it asks, and Miso accepts or declines. Builder
+ * holding its own copy of the entitlement rules would be a second answer to drift from the
+ * licence, and a local one at that — the easiest possible thing to edit.
+ *
+ * This runs **first**. A decline after the databases exist would leave an environment's
+ * objects behind for an environment that is not licensed, and nothing would later remove
+ * them.
+ *
+ * @async
+ * @param {string} envKey - Environment key
+ * @param {Object} deps - Injected collaborators
+ * @returns {Promise<void>}
+ * @throws {Error} When Miso declines, or cannot be reached to ask
+ */
+async function authorizeEnvironmentWithController(envKey, deps) {
+  if (typeof deps.authorizeEnvironment === 'function') {
+    await deps.authorizeEnvironment(envKey);
+    return;
+  }
+  const { resolveControllerUrl } = require('../../utils/controller-url');
+  const { getOrRefreshDeviceToken } = require('../../utils/token-manager');
+  const { createEnvironment } = require('../../api/environments.api');
+
+  const controllerUrl = await resolveControllerUrl();
+  if (!controllerUrl) {
+    throw new Error(
+      `Cannot create ${envKey}: no controller is configured, so whether your licence ` +
+        'permits this environment cannot be checked. Run "aifabrix login" first.'
+    );
+  }
+  const deviceToken = await getOrRefreshDeviceToken(controllerUrl);
+  if (!deviceToken || !deviceToken.token) {
+    throw new Error(
+      `Cannot create ${envKey}: not signed in, so whether your licence permits this ` +
+        'environment cannot be checked. Run "aifabrix login" first.'
+    );
+  }
+  const authConfig = {
+    type: 'device',
+    token: deviceToken.token,
+    controller: deviceToken.controller || controllerUrl
+  };
+  try {
+    await createEnvironment(controllerUrl, authConfig, { key: envKey, environment: envKey });
+  } catch (error) {
+    // Miso owns the edition rules, so its refusal is reported as given rather than
+    // reinterpreted here. Guessing at the reason would put a second, stale explanation of
+    // the licence in front of the operator.
+    throw new Error(
+      `Miso declined environment ${envKey}: ${error.message}\n` +
+        'Editions are licensed in Miso. Nothing was created locally.'
+    );
+  }
+}
+
+/**
+ * Workloads `env deploy` promotes into a promotion-only environment.
+ *
+ * The same set that owns the environment's databases: an application exists per environment
+ * or it does not, and its containers and its databases cannot disagree about which.
+ */
+const PROMOTED_WORKLOAD_APP_KEYS = ENVIRONMENT_WORKLOAD_APP_KEYS;
+
+/**
+ * Run the promoted image as this environment's container.
+ *
+ * `base: true` is the whole point. Without it the run path prefers a local developer-scoped
+ * tag, which is the image someone happens to have built — the opposite of promotion, where
+ * what runs in `pro` must be the artifact that was promoted out of dev.
+ *
+ * Nothing is built here, and image resolution stays with the run path rather than being
+ * recomputed: a second answer to "which image" is how the promoted artifact and the running
+ * one come apart.
+ *
+ * @async
+ * @param {string} envKey - Environment key
+ * @param {Object} deps - Injected collaborators
+ * @returns {Promise<string[]>} Application keys promoted
+ */
+async function promoteWorkloadsForEnvironment(envKey, deps) {
+  const policy = deps.policy || require('../../core/environment-mode-policy');
+  // dev is a working environment: its containers come from `setup` and the `up-*` commands,
+  // and promoting over them would replace what a developer is working on.
+  if (!policy.isPromotionOnlyEnvironment(envKey)) {
+    return [];
+  }
+  const runApp = deps.runApp || require('../../app').runApp;
+  const promoted = [];
+  for (const appKey of PROMOTED_WORKLOAD_APP_KEYS) {
+    try {
+      await runApp(appKey, { env: envKey, base: true });
+    } catch (error) {
+      throw new Error(
+        `Could not promote ${appKey} into ${envKey}: ${error.message}\n` +
+          `${envKey} runs a promoted image and never builds one. Produce it in dev first ` +
+          `with: aifabrix build ${appKey} --base --from-dev`
+      );
+    }
+    promoted.push(appKey);
+  }
+  return promoted;
+}
+
+/**
+ * Run the local environment stage.
+ *
+ * @async
+ * @param {string} installationKey - Positional installation key (`local` or `local-…`)
+ * @param {string} envKey - Validated stage, one of dev|tst|pro
+ * @param {Object} [deps] - Injected collaborators
+ * @returns {Promise<{ stage: string, vendor: string, installation: string, databases: string[], promoted: string[] }>}
+ */
+async function runLocalEnvironmentStage(installationKey, envKey, deps = {}) {
+  const config = deps.config || require('../../core/config');
+  const policy = deps.policy || require('../../core/environment-mode-policy');
+
+  // Miso first: it owns editions, and it accepts or declines this environment. Everything
+  // below creates something, so the licence answer has to come before any of it.
+  await authorizeEnvironmentWithController(envKey, deps);
+
+  // Then the local precondition. tst and pro are unreachable outside the front-door mode,
+  // so creating their databases would leave resources behind for an environment that cannot
+  // serve a request.
+  await policy.assertEnvironmentAllowedForCurrentMode(envKey);
+
+  const developerId = await config.getDeveloperId();
+  const installation = resolveLocalInstallationName(installationKey, developerId);
+
+  logger.log(`Deploying environment ${envKey} into local installation ${installation}`);
+
+  // Databases before containers: a workload that starts without its database fails on its
+  // first request rather than at startup, which is the harder failure to read.
+  const databases = await ensureEnvironmentDatabases(envKey, deps);
+  logger.log(`Ensured ${databases.length} database(s) for ${envKey}: ${databases.join(', ')}`);
+
+  const promoted = await promoteWorkloadsForEnvironment(envKey, deps);
+  if (promoted.length > 0) {
+    logger.log(`Promoted into ${envKey}: ${promoted.join(', ')}`);
+  }
+
+  return { stage: envKey, vendor: 'DOCKER', installation, databases, promoted };
+}
+
+module.exports = {
+  ENVIRONMENT_WORKLOAD_APP_KEYS,
+  PROMOTED_WORKLOAD_APP_KEYS,
+  authorizeEnvironmentWithController,
+  resolveEnvironmentDatabasePlan,
+  ensureEnvironmentDatabases,
+  promoteWorkloadsForEnvironment,
+  runLocalEnvironmentStage
+};

package/lib/deployment/installation/local-installation.js

@@ -0,0 +1,76 @@
+/**
+ * The `local` installation key for `env deploy` (plan 210.0).
+ *
+ * `env deploy` is dual-mode, and the installation name is what chooses the mode. Miso
+ * already names a local installation `local-dev{NN}`, so Builder mirrors that rather than
+ * inventing a second convention. The operator types the bare word `local`; the CLI knows its
+ * own developer id and supplies the rest.
+ *
+ * Naming the mode in the argument, rather than inferring it from machine state, means the
+ * positional means the same thing on both paths — an installation — and the command reads
+ * the same whichever installation it names.
+ *
+ * @fileoverview Local installation key detection and name derivation
+ */
+
+'use strict';
+
+/** The bare key an operator types. */
+const LOCAL_INSTALLATION_KEY = 'local';
+
+/** Prefix of a fully qualified local installation name. */
+const LOCAL_INSTALLATION_PREFIX = 'local-';
+
+/**
+ * Whether this installation key names a local installation.
+ *
+ * @param {unknown} key - Positional installation key
+ * @returns {boolean}
+ */
+function isLocalInstallationKey(key) {
+  const value = String(key ?? '').trim().toLowerCase();
+  return value === LOCAL_INSTALLATION_KEY || value.startsWith(LOCAL_INSTALLATION_PREFIX);
+}
+
+/**
+ * The installation name for a local key.
+ *
+ * `local` expands to `local-dev{developerId}`; an already-qualified `local-…` is kept as
+ * given, so an operator can name an installation whose id is not this machine's.
+ *
+ * **The developer id must be the stored string, never a parsed number.** It is persisted
+ * zero-padded (`'03'`), and `config.js` preserves that string deliberately. Surrounding code
+ * carries `parseInt(developerId, 10)` for numeric comparisons such as `idNum === 0`; deriving
+ * the name from that would produce `local-dev3`, which disagrees with Miso's `local-dev03`
+ * and surfaces as a missing installation rather than as a naming bug.
+ *
+ * @param {string} key - Positional installation key
+ * @param {string|number} developerId - Stored developer id
+ * @returns {string} Qualified installation name
+ * @throws {Error} When the key is not a local key, or the id is unusable
+ */
+function resolveLocalInstallationName(key, developerId) {
+  const value = String(key ?? '').trim().toLowerCase();
+  if (!isLocalInstallationKey(value)) {
+    throw new Error(`Installation "${key}" is not a local installation key`);
+  }
+  if (value !== LOCAL_INSTALLATION_KEY) {
+    return value;
+  }
+  const id = String(developerId ?? '').trim();
+  if (!id || !/^\d+$/.test(id)) {
+    throw new Error(
+      'Cannot derive the local installation name: no developer id is configured. ' +
+        'Set one with "aifabrix setup", or name the installation explicitly, for example ' +
+        '"aifabrix env deploy local-dev03".'
+    );
+  }
+  return `${LOCAL_INSTALLATION_PREFIX}dev${id}`;
+}
+
+module.exports = {
+  LOCAL_INSTALLATION_KEY,
+  LOCAL_INSTALLATION_PREFIX,
+  isLocalInstallationKey,
+  resolveLocalInstallationName
+};