@aifabrix/builder 2.60.0 → 2.61.2

package/lib/utils/compose-generate-docker-compose.js

@@ -11,6 +11,7 @@
 const fsSync = require('fs');
 const path = require('path');
 const buildCopy = require('./build-copy');
+const { prepareLocalDataMount } = require('./prepare-local-data-mount');
 const paths = require('./paths');
 const { isSystemBuilderAppName } = require('./paths-system-builder-keys');
 const {
@@ -187,14 +188,14 @@ function resolveStorageMountSourceRoot(appName, buildContext) {
 }
 
 /**
- * Host `mount/` directory bind-mounted to `/mnt/data` when storage is required.
+ * Host `mount/data/<appName>/` directory bind-mounted to `/mnt/data` when storage is required.
  *
  * @param {object} ctx - Compose template context (`devMountPath`, `appName`, `appConfig`, `serviceConfig`)
  * @returns {string|null}
  */
 function resolveLocalDataMountPathForCompose(ctx) {
   if (ctx.devMountPath && typeof ctx.devMountPath === 'string') {
-    return path.join(ctx.devMountPath, 'mount').replace(/\\/g, '/');
+    return path.join(ctx.devMountPath, 'mount', 'data', ctx.appName).replace(/\\/g, '/');
   }
   const requiresStorage =
     ctx.serviceConfig?.requiresStorage ||
@@ -212,7 +213,7 @@ function resolveLocalDataMountPathForCompose(ctx) {
     if (!sourceRoot) {
       return null;
     }
-    return path.join(sourceRoot, 'mount').replace(/\\/g, '/');
+    return path.join(sourceRoot, 'mount', 'data', ctx.appName).replace(/\\/g, '/');
   } catch {
     return null;
   }
@@ -229,12 +230,8 @@ function buildComposeTemplateContext(ctx) {
     ctx.appConfig?.requires?.storage ||
     ctx.appConfig?.services?.storage ||
     false;
-  if (localDataMountPath && requiresStorage && !fsSync.existsSync(localDataMountPath)) {
-    try {
-      fsSync.mkdirSync(localDataMountPath, { recursive: true });
-    } catch {
-      // Non-fatal: tests may use non-writable devMountPath; host must create mount/ before run.
-    }
+  if (localDataMountPath && requiresStorage) {
+    prepareLocalDataMount(localDataMountPath, ctx.envFileAbsolutePath);
   }
   return {
     ...ctx.serviceConfig,
@@ -253,9 +250,7 @@ function buildComposeTemplateContext(ctx) {
     // An app that administers its own operating system — creating accounts, managing
     // sshd — cannot work that way and declares `runAsRoot: true` to opt out.
     runAsRoot: ctx.appConfig?.runAsRoot === true,
-    // Extra ports for an application serving a second protocol from the same container,
-    // such as SSH beside HTTP. Each host port uses the main port's formula so developers
-    // on one host do not collide.
+    // Extra protocol ports use the main port offset formula to avoid developer collisions.
     additionalPorts: (ctx.appConfig?.additionalPorts ?? []).map((entry) => ({
       name: entry.name,
       containerPort: entry.containerPort,

package/lib/utils/datasource-binary-evidence.js

@@ -0,0 +1,92 @@
+/** @fileoverview Safe binary metadata and keyed document persistence evidence. */
+'use strict';
+
+const { keyedGetEvidence, hasExecutedKeyedGet } = require('./datasource-test-run-capability-scope');
+const BINARY_FIELDS = new Set(['contentType', 'size', 'filename', 'sha256']);
+
+/** @param {*} value @returns {Object} */
+function binarySummary(value) {
+  if (!value || typeof value !== 'object') return {};
+  return Object.fromEntries(Object.entries(value).filter(([key, item]) =>
+    BINARY_FIELDS.has(key) && ['string', 'number'].includes(typeof item)));
+}
+
+/**
+ * Limit binary containers to metadata before printing or saving a report.
+ * Ordinary JSON record fields remain intact.
+ * @param {*} value
+ * @param {WeakSet} seen
+ * @returns {*}
+ */
+function sanitizeBinaryEvidence(value, seen = new WeakSet()) {
+  if (!value || typeof value !== 'object') return value;
+  if (Buffer.isBuffer(value) || ArrayBuffer.isView(value)) return '[binary omitted]';
+  if (seen.has(value)) return '[Circular]';
+  seen.add(value);
+  if (Array.isArray(value)) {
+    const items = value.map(item => sanitizeBinaryEvidence(item, seen));
+    seen.delete(value);
+    return items;
+  }
+  const out = {};
+  for (const [key, item] of Object.entries(value)) {
+    if (['getBinary', 'listBinary', '_binary'].includes(key)) out[key] = binarySummary(item);
+    else if (value.keyedGet === true && key === 'document') {
+      out[key] = { ...binarySummary(item) };
+      if (typeof item?.key === 'string') out[key].key = item.key;
+      if (typeof item?.persisted === 'boolean') out[key].persisted = item.persisted;
+    } else if (value.keyedGet === true && ['data', 'bytes', 'body', 'content', 'base64'].includes(key)) continue;
+    else out[key] = sanitizeBinaryEvidence(item, seen);
+  }
+  seen.delete(value);
+  return out;
+}
+
+/** @param {Object} value @param {string[]} lines */
+function appendBinaryAndPersistence(value, lines) {
+  if (!value || typeof value !== 'object') return;
+  if (value.getBinary) lines.push(`  getBinary: ${JSON.stringify(binarySummary(value.getBinary))}`);
+  if (value.scope?.expectedSource === 'get') {
+    const observed = value.observed || {};
+    lines.push(`  Document persistence (expectedSource: get): documents=${Number(observed.documents) || 0}, chunks=${Number(observed.chunks) || 0}`);
+  }
+  for (const [key, child] of Object.entries(value)) {
+    if (key !== 'getBinary') appendBinaryAndPersistence(child, lines);
+  }
+}
+
+/** @param {Object} envelope @returns {string[]} */
+function binaryEvidenceLines(envelope) {
+  const lines = [];
+  for (const job of keyedGetEvidence(envelope)) {
+    const status = job.skipped === true ? 'skipped' : job.ok === true ? 'executed' : 'failed';
+    lines.push(`  Keyed get: ${status} (${job.datasourceKey || envelope.datasourceKey || 'unknown'})`);
+    if (job.document) lines.push(`  Document: ${JSON.stringify(binarySummary(job.document))}`);
+  }
+  appendBinaryAndPersistence(envelope?.integration?.stepResults, lines);
+  return lines;
+}
+
+/** @param {Object} envelope @param {string} key @returns {boolean} */
+function hasKeyedDocumentPersistence(envelope, key) {
+  if (!hasExecutedKeyedGet(envelope, key)) return false;
+  const steps = envelope?.integration?.stepResults || [];
+  return steps.some(step => {
+    if (step.name !== 'document_persistence' || step.success === false || step.status === 'failed') return false;
+    const row = step.evidence?.datasources?.[key];
+    const model = row?.model;
+    return model?.scope?.expectedSource === 'get' && model.observed?.documents > 0 &&
+      model.observed?.chunks > 0 && (!Array.isArray(row.failures) || row.failures.length === 0);
+  });
+}
+
+/** @param {Object} result @param {string[]} keys @returns {boolean} */
+function hasAllKeyedDocumentPersistence(result, keys) {
+  return keys.length > 0 && keys.every(key => {
+    const row = result?.results?.find(item => item.key === key);
+    return row?.success === true && hasKeyedDocumentPersistence(row.datasourceTestRun, key);
+  });
+}
+
+module.exports = { binarySummary, sanitizeBinaryEvidence, binaryEvidenceLines, hasKeyedDocumentPersistence,
+  hasAllKeyedDocumentPersistence };

package/lib/utils/datasource-test-run-capability-scope.js

@@ -4,6 +4,43 @@
  * @version 2.0.0
  */
 
+/**
+ * Keyed document retrieval has no list operation, so the `get` runs once against a business
+ * key instead of over a sync page. The dataplane records that run as step evidence
+ * (`sync_step_keyed_get.py`), which is why execution is read from evidence rather than from
+ * a row count. `IntegrationStepResult.evidence` is an open object by contract.
+ * @param {Object|null|undefined} envelope - DatasourceTestRun-like
+ * @returns {Array<Object>} Keyed-get evidence entries, newest first as reported
+ */
+function keyedGetEvidence(envelope) {
+  const integration = envelope && typeof envelope === 'object' ? envelope.integration : null;
+  const steps = integration && Array.isArray(integration.stepResults) ? integration.stepResults : [];
+  return steps
+    .map(step => (step && typeof step.evidence === 'object' ? step.evidence : null))
+    .flatMap(evidence => evidence && Array.isArray(evidence.jobs) ? evidence.jobs : [evidence])
+    .filter(evidence => evidence && evidence.keyedGet === true);
+}
+
+/**
+ * A keyed `get` counts as executed only when it actually returned a document. A skipped run
+ * (no primary key value) or a failed one is not execution, and reporting it as such would
+ * turn `--strict-capability-scope` into a rubber stamp.
+ * @param {Object|null|undefined} envelope - DatasourceTestRun-like
+ * @param {string|undefined|null} datasourceKey - Restrict to one datasource when given
+ * @returns {boolean} True when a keyed get ran successfully
+ */
+function hasExecutedKeyedGet(envelope, datasourceKey) {
+  const wanted = datasourceKey === undefined || datasourceKey === null || String(datasourceKey).trim() === ''
+    ? ''
+    : String(datasourceKey).trim();
+  return keyedGetEvidence(envelope).some(evidence => {
+    if (evidence.ok !== true || evidence.skipped === true) {
+      return false;
+    }
+    return wanted === '' || String(evidence.datasourceKey || '') === wanted;
+  });
+}
+
 /**
  * @param {Object|null|undefined} envelope - DatasourceTestRun-like
  * @param {string|undefined|null} requestedCapabilityKey - From positional [capabilityKey]
@@ -23,6 +60,10 @@ function analyzeCapabilityScope(envelope, requestedCapabilityKey) {
     envelope && typeof envelope === 'object' && Array.isArray(envelope.capabilities)
       ? envelope.capabilities
       : [];
+  if (key === 'get' && keyedGetEvidence(envelope).length > 0 &&
+      !hasExecutedKeyedGet(envelope, envelope.datasourceKey)) {
+    return { violated: true, message: 'Capabilities scope: keyed get was not executed successfully.' };
+  }
   if (caps.length <= 1) {
     return { violated: false };
   }
@@ -39,5 +80,7 @@ function analyzeCapabilityScope(envelope, requestedCapabilityKey) {
 }
 
 module.exports = {
-  analyzeCapabilityScope
+  analyzeCapabilityScope,
+  keyedGetEvidence,
+  hasExecutedKeyedGet
 };

package/lib/utils/datasource-test-run-debug-display.js

@@ -4,6 +4,7 @@
  * @version 2.0.0
  */
 
+const { sanitizeBinaryEvidence } = require('./datasource-binary-evidence');
 const { SEP, appendReferenceLayoutLines } = require('./datasource-test-run-display');
 const { buildDebugEnvelopeSlice } = require('./datasource-test-run-debug-slice');
 const {
@@ -250,6 +251,7 @@ function applyRawLineCap(text) {
  * @returns {string}
  */
 function formatDatasourceTestRunDebugBlock(envelope, mode, isTTY) {
+  envelope = sanitizeBinaryEvidence(envelope);
   if (!envelope || typeof envelope !== 'object') return '';
 
   const lines = ['', SEP, `Debug (${mode})`];

package/lib/utils/datasource-test-run-display.js

@@ -5,9 +5,11 @@
  */
 
 const chalk = require('chalk');
+const { binaryEvidenceLines } = require('./datasource-binary-evidence');
 const { sectionTitle, headerKeyValue, colorAggregateGlyph, successGlyph, failureGlyph } = require('./cli-test-layout-chalk');
 const { appendCertificateTTY, appendCertificateIssuanceTTY } = require('./datasource-test-run-certificate-tty');
 const { buildTtyMetaLines: buildTtyMetaLinesCore } = require('./datasource-test-run-tty-meta-lines');
+const { appendStructuredIssueGuidance } = require('./datasource-test-run-issue-guidance');
 
 const SEP = '────────────────────────────────';
 
@@ -297,9 +299,12 @@ function appendValidationIssueLines(lines, envelope, maxIssues = 5) {
   const cap = Math.min(maxIssues, issues.length);
   for (let i = 0; i < cap; i += 1) {
     const iss = issues[i];
-    const code = iss && iss.code ? chalk.red(`[${iss.code}] `) : '';
+    const issueCode = iss && (iss.stableCode || iss.code);
+    const code = issueCode ? chalk.red(`[${issueCode}] `) : '';
+    const severity = iss?.severity ? chalk.gray(`[${String(iss.severity)}] `) : '';
     const msg = iss && iss.message ? String(iss.message) : JSON.stringify(iss);
-    lines.push(`  ${code}${chalk.yellow(msg)}`);
+    lines.push(`  ${code}${severity}${chalk.yellow(msg)}`);
+    appendStructuredIssueGuidance(lines, iss);
     appendDpSec013Details(lines, iss);
   }
   if (issues.length > cap) {
@@ -448,6 +453,7 @@ function formatDatasourceTestRunTTY(envelope, options = {}) {
   appendRefsSectionIfEnabled(lines, envelope, options);
   appendValidationIssueLines(lines, envelope);
   appendIntegrationStepLines(lines, envelope);
+  lines.push(...binaryEvidenceLines(envelope));
   const focus = normalizedFocusCapabilityKey(options.focusCapabilityKey);
   if (focus) {
     lines.push(formatCapabilityFocusSection(envelope, focus));

package/lib/utils/datasource-test-run-issue-guidance.js

@@ -0,0 +1,176 @@
+/**
+ * Structured human guidance for DatasourceTestRun validation issues.
+ *
+ * @fileoverview Preserve actionable issue fields in TTY output
+ */
+
+'use strict';
+
+const chalk = require('chalk');
+
+const STEP_VERBS = {
+  locate_file: 'open',
+  update_path: 'update',
+  add_mapping: 'add mapping',
+  set_value: 'set',
+  remove_value: 'remove',
+  add_item: 'add to',
+  remove_item: 'remove from'
+};
+
+const UPSERT_GUIDANCE = {
+  'DP-CIP-030': {
+    observed: 'The declared upsert does not contain the required create, update, and records-output composition.',
+    consequence: 'The runtime cannot execute one deterministic create-or-update operation.',
+    aiFixable: true,
+    remediation: [
+      'Run aifabrix datasource capability upsert <file-or-key> --overwrite --dry-run, review the patch, then apply and validate it.'
+    ],
+    prevention: 'Author upsert through the capability command and keep both source halves valid.',
+    residualRisk: 'Publication remains blocked while the composition is malformed.',
+    rerun: 'Rerun the same focused datasource validation or E2E case.'
+  },
+  'DP-CIP-031': {
+    observed: 'The upsert declares no usable business identity.',
+    consequence: 'Existence cannot be resolved, so a retry may create a duplicate or update the wrong record.',
+    aiFixable: true,
+    remediation: [
+      'Run aifabrix datasource capability upsert <file-or-key> --identity <fields> --dry-run with author-approved mapped non-primary fields.'
+    ],
+    prevention: 'Model business identity before exposing a composed write.',
+    residualRisk: 'Upsert must remain unavailable until identity is explicit and validated.',
+    rerun: 'Rerun the same focused datasource validation or E2E case.'
+  },
+  'DP-CIP-040': {
+    observed: 'No declared read operation can constrain the complete business identity.',
+    consequence: 'The source record may be missed, creating a duplicate or selecting the wrong update target.',
+    aiFixable: false,
+    remediation: [
+      'Declare a real exact lookup only if the source API supports it.',
+      'Otherwise keep separate create and update capabilities and withhold upsert readiness.'
+    ],
+    prevention: 'Require complete equality lookup coverage before authoring upsert.',
+    residualRisk: 'AI cannot repair a source API that lacks exact lookup or uniqueness.',
+    rerun: 'After a supported lookup is declared, rerun the same focused validation and E2E proof.'
+  },
+  'DP-CIP-041': {
+    observed: 'A covering identity read is declared, but live filtering has not been proven.',
+    consequence: 'Static coverage alone cannot show that the source applies the constraint or exposes writes in time.',
+    aiFixable: false,
+    remediation: ['Run the focused live validation and two-write no-duplicate E2E proof; do not add a duplicate read declaration.'],
+    prevention: 'Keep exact lookup and no-duplicate proof scenarios with every upsert datasource.',
+    residualRisk: 'Read-after-write delay can leave a bounded duplicate window until runtime protection is proven.',
+    rerun: 'Rerun the same focused datasource validation and upsert E2E case.'
+  }
+};
+
+function normalizeOptionalString(value) {
+  return typeof value === 'string' ? value.trim() : '';
+}
+
+function hasGuidanceValue(value) {
+  if (Array.isArray(value)) return value.some(hasGuidanceValue);
+  if (typeof value === 'boolean') return true;
+  if (value && typeof value === 'object') return Object.keys(value).length > 0;
+  return normalizeOptionalString(value) !== '';
+}
+
+function firstGuidanceValue(...values) {
+  return values.find(hasGuidanceValue);
+}
+
+function guidancePayload(item) {
+  return normalizeOptionalString(item.value) || normalizeOptionalString(item.template);
+}
+
+function guidanceVerb(step) {
+  return STEP_VERBS[step] || step.replace(/_/g, ' ') || 'update';
+}
+
+/**
+ * Render one guidance entry, which may be a string or a structured fix instruction.
+ *
+ * `fix.instructions[]` entries are objects ({step, path, value, template, note}),
+ * so stringifying them printed `[object Object]` and the remediation — the part a
+ * developer acts on — was lost.
+ *
+ * @param {unknown} item guidance entry
+ * @returns {string|null} display text, or null when there is nothing to show
+ */
+function formatGuidanceItem(item) {
+  if (typeof item === 'string') return item.trim() || null;
+  if (!item || typeof item !== 'object') return null;
+
+  const step = normalizeOptionalString(item.step);
+  const note = normalizeOptionalString(item.note);
+  const target = normalizeOptionalString(item.path);
+  const payload = guidancePayload(item);
+
+  // `explain` carries no path or value; its note *is* the instruction.
+  if (step === 'explain' || (!target && !payload)) {
+    return note || (step ? step.replace(/_/g, ' ') : null);
+  }
+
+  const verb = guidanceVerb(step);
+  // With no path the payload *is* the target (e.g. locate_file carries a path in
+  // `value`), so it reads as "open <file>" rather than "open: <file>".
+  let text = target ? `${verb} ${target}` : `${verb} ${payload}`;
+  if (target && payload) text += step === 'set_value' ? ` = ${payload}` : `: ${payload}`;
+  return note ? `${text} — ${note}` : text;
+}
+
+function appendGuidanceValue(lines, label, value) {
+  const values = Array.isArray(value) ? value : [value];
+  values
+    .map(formatGuidanceItem)
+    .filter(Boolean)
+    .forEach((text) => {
+      lines.push(`    ${chalk.gray(`${label}:`)} ${chalk.white(text)}`);
+    });
+}
+
+function enrichUpsertIssueGuidance(issue) {
+  if (!issue || typeof issue !== 'object') return issue;
+  const code = issue.stableCode || issue.code;
+  const fallback = UPSERT_GUIDANCE[code];
+  if (!fallback) return issue;
+  const enriched = { ...issue };
+  Object.entries(fallback).forEach(([key, value]) => {
+    if (!hasGuidanceValue(enriched[key])) enriched[key] = value;
+  });
+  return enriched;
+}
+
+function appendStructuredIssueGuidance(lines, issue) {
+  if (!issue || typeof issue !== 'object') return;
+  const display = enrichUpsertIssueGuidance(issue);
+  appendGuidanceValue(lines, 'Observed', firstGuidanceValue(
+    issue.observed, issue.details?.diagnosis, display.observed
+  ));
+  appendGuidanceValue(lines, 'Consequence', firstGuidanceValue(
+    issue.impact, issue.consequence, issue.reason, display.consequence
+  ));
+  if (typeof display.aiFixable === 'boolean') {
+    appendGuidanceValue(lines, 'Can AI fix?', display.aiFixable
+      ? 'Yes — only as an authorized deterministic local manifest change.'
+      : 'No automatic fix is safe for this source or live-proof limitation.');
+  }
+  appendGuidanceValue(lines, 'Safe action', firstGuidanceValue(
+    issue.fix?.instructions, issue.remediation, issue.hint, display.remediation
+  ));
+  appendGuidanceValue(lines, 'Prevention', firstGuidanceValue(
+    issue.prevention, issue.fix?.prevention, display.prevention
+  ));
+  appendGuidanceValue(lines, 'Residual risk', firstGuidanceValue(
+    issue.residualRisk, issue.risk, display.residualRisk
+  ));
+  appendGuidanceValue(lines, 'Rerun', firstGuidanceValue(
+    issue.rerun, issue.fix?.rerun, display.rerun
+  ));
+}
+
+module.exports = {
+  appendStructuredIssueGuidance,
+  enrichUpsertIssueGuidance,
+  formatGuidanceItem
+};

package/lib/utils/datasource-test-run-tty-log.js

@@ -5,6 +5,7 @@
 'use strict';
 
 const chalk = require('chalk');
+const { sanitizeBinaryEvidence } = require('./datasource-binary-evidence');
 const logger = require('./logger');
 const { getReportVersionStderrMessage } = require('./datasource-test-run-report-version');
 const {
@@ -42,6 +43,7 @@ function emitCapabilityScopeDiagnostics(envelope, opts = {}) {
  * @param {string} [options.requestedCapabilityKey]
  */
 function printDatasourceTestRunForTTY(envelope, options = {}) {
+  envelope = sanitizeBinaryEvidence(envelope);
   const mode = resolveDebugDisplayMode(options.debug);
   const displayOpts = {
     focusCapabilityKey: options.requestedCapabilityKey,

package/lib/utils/env-copy.js

@@ -56,16 +56,17 @@ function readDeveloperIdFromConfig(config) {
  * Creates the mount folder on the local filesystem (next to the .env file) when it does not exist.
  * @param {string} content - Env file content
  * @param {string} outputPath - Resolved path of the .env file being written
+ * @param {string} [appName] - System key (defaults to output directory name)
  * @returns {string} Content with /mnt/data replaced by path to mount directory
  */
-function substituteMntDataForLocal(content, outputPath) {
+function substituteMntDataForLocal(content, outputPath, appName) {
   const outputDir = path.dirname(outputPath);
   // Avoid introducing a drive letter for root-relative paths (e.g. "\tmp\out"),
   // which are common in unit tests and some Windows path constructions.
   const isWinRootRelative = process.platform === 'win32' && /^\\(?!\\)/.test(outputDir);
   const localMountPath = isWinRootRelative
-    ? path.win32.normalize(path.win32.join(outputDir, 'mount'))
-    : path.resolve(outputDir, 'mount');
+    ? path.win32.normalize(path.win32.join(outputDir, 'mount', 'data', appName || path.basename(outputDir)))
+    : path.resolve(outputDir, 'mount', 'data', appName || path.basename(outputDir));
   if (!fs.existsSync(localMountPath)) {
     fs.mkdirSync(localMountPath, { recursive: true });
   }
@@ -140,12 +141,12 @@ async function writeEnvOutputForReload(outputPath, runEnvPath, appName) {
     baseContent = await fsp.readFile(outputPath, 'utf8');
   } else if (appName) {
     baseContent = await generateEnvContent(appName, null, 'local', false);
-    baseContent = substituteMntDataForLocal(baseContent, outputPath);
+    baseContent = substituteMntDataForLocal(baseContent, outputPath, appName);
   } else {
     baseContent = runContent;
   }
   let toWrite = mergeEnvMapIntoContent(baseContent, runMap, { appendMissingFromNewMap: false });
-  toWrite = substituteMntDataForLocal(toWrite, outputPath);
+  toWrite = substituteMntDataForLocal(toWrite, outputPath, appName);
   await fsp.writeFile(outputPath, toWrite, { mode: 0o600 });
   logger.log(
     formatSuccessLine(
@@ -163,7 +164,7 @@ async function writeEnvOutputForReload(outputPath, runEnvPath, appName) {
 async function writeEnvOutputForLocal(appName, outputPath) {
   const { generateEnvContent, parseEnvContentToMap, mergeEnvMapIntoContent } = require('../core/secrets');
   let localContent = await generateEnvContent(appName, null, 'local', false);
-  localContent = substituteMntDataForLocal(localContent, outputPath);
+  localContent = substituteMntDataForLocal(localContent, outputPath, appName);
   let toWrite = localContent;
   if (fs.existsSync(outputPath)) {
     const existingContent = await fsp.readFile(outputPath, 'utf8');
@@ -319,7 +320,7 @@ async function patchEnvContentForLocal(envContent, variables) {
 async function syncWrittenBuilderEnvToOutputPath(envPath, outputPath, envOutputPathLabel, copyOptions = {}) {
   const { parseEnvContentToMap, mergeEnvMapIntoContent } = require('../core/secrets');
   const raw = fs.readFileSync(envPath, 'utf8');
-  const synced = substituteMntDataForLocal(raw, outputPath);
+  const synced = substituteMntDataForLocal(raw, outputPath, copyOptions.appName || path.basename(path.dirname(envPath)));
   let toWrite = synced;
   if (!copyOptions.freshEnv && fs.existsSync(outputPath)) {
     const existingContent = fs.readFileSync(outputPath, 'utf8');
@@ -344,7 +345,7 @@ async function writeLocalEnvToOutputPath(outputPath, appName, secretsPath, envOu
   const { generateEnvContent, parseEnvContentToMap, mergeEnvMapIntoContent } = require('../core/secrets');
   const genOpts = extraOpts.appPath ? { appPath: extraOpts.appPath } : {};
   let localEnvContent = await generateEnvContent(appName, secretsPath, 'local', false, genOpts);
-  localEnvContent = substituteMntDataForLocal(localEnvContent, outputPath);
+  localEnvContent = substituteMntDataForLocal(localEnvContent, outputPath, appName);
   let toWrite = localEnvContent;
   if (!extraOpts.freshEnv && fs.existsSync(outputPath)) {
     const existingContent = fs.readFileSync(outputPath, 'utf8');
@@ -366,7 +367,7 @@ async function writeLocalEnvToOutputPath(outputPath, appName, secretsPath, envOu
 async function writePatchedEnvToOutputPath(envPath, outputPath, variables, envOutputPathLabel) {
   const envContent = fs.readFileSync(envPath, 'utf8');
   let patchedContent = await patchEnvContentForLocal(envContent, variables);
-  patchedContent = substituteMntDataForLocal(patchedContent, outputPath);
+  patchedContent = substituteMntDataForLocal(patchedContent, outputPath, variables.app?.key || path.basename(path.dirname(envPath)));
   fs.writeFileSync(outputPath, patchedContent, { mode: 0o600 });
   logger.log(formatSuccessLine(`Copied .env to: ${envOutputPathLabel}`));
 }
@@ -405,7 +406,7 @@ async function copyOrRegenerateEnvForNamedApp(opts) {
     return;
   }
   if (fs.existsSync(envPath)) {
-    await syncWrittenBuilderEnvToOutputPath(envPath, outputPath, label, { freshEnv: freshEnv === true });
+    await syncWrittenBuilderEnvToOutputPath(envPath, outputPath, label, { freshEnv: freshEnv === true, appName });
     return;
   }
   await writeLocalEnvToOutputPath(outputPath, appName, secretsPath, label, localOpts);

package/lib/utils/external-system-system-test-tty.js

@@ -182,7 +182,9 @@ function pickBlockingDatasourceKey(rows) {
 }
 
 function issueKey(issue) {
-  const code = issue && issue.code ? String(issue.code) : '';
+  const code = issue && (issue.stableCode || issue.code)
+    ? String(issue.stableCode || issue.code)
+    : '';
   const msg = issue && issue.message ? String(issue.message) : '';
   return `${code}::${msg}`.toLowerCase();
 }
@@ -402,4 +404,3 @@ module.exports = {
   systemCertStatus,
   drillDownCommand
 };
-

package/lib/utils/image-tags.js

@@ -48,7 +48,7 @@ function expandTag(entry, version) {
  * @throws {Error} On blank entries, unsupported placeholders, missing version or invalid tags
  */
 function resolveImageTags(tagInput, appVersion) {
-  if (tagInput === undefined || tagInput === null || String(tagInput).trim() === '') {
+  if (tagInput === undefined || tagInput === null) {
     return [DEFAULT_TAG];
   }
   const entries = String(tagInput).split(',').map((entry) => entry.trim());
@@ -72,7 +72,7 @@ function resolveImageTags(tagInput, appVersion) {
  */
 function resolveBuildTagPlan(tagInput, appVersion) {
   const tags = resolveImageTags(tagInput, appVersion);
-  const explicitSingle = tags.length === 1 && tagInput !== undefined && tagInput !== null && String(tagInput).trim() !== '';
+  const explicitSingle = tagInput !== undefined && tagInput !== null && !String(tagInput).includes(',');
   if (explicitSingle && !FLOATING_TAGS.includes(tags[0])) {
     tags.push(DEFAULT_TAG);
   }

package/lib/utils/platform-kv-ref.js

@@ -42,7 +42,7 @@ function isPlatformCatalogKvRef(val) {
 
 /**
  * True when repair should normalize a kv value to path-style kv://systemKey/variable.
- * Platform catalog refs (e.g. kv://secrets-openaiApiKeyVault) are never legacy.
+ * Platform catalog refs (e.g. kv://redis-passwordKeyVault) are never legacy.
  *
  * @param {string} val - Value from authentication.security or configuration
  * @returns {boolean}

package/lib/utils/prepare-local-data-mount.js

@@ -0,0 +1,58 @@
+/**
+ * Prepare persistent storage before starting a local application container.
+ * @fileoverview Local storage mount and configured DATA_DIR initialization
+ */
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const dotenv = require('dotenv');
+
+/**
+ * Read only a DATA_DIR beneath the container's storage mount.
+ * @param {string|undefined} envFile - Resolved application env file
+ * @returns {string[]} Relative directory components
+ */
+function dataDirectoryParts(envFile) {
+  if (!envFile || !fs.existsSync(envFile)) return [];
+  const { DATA_DIR: dataDir } = dotenv.parse(fs.readFileSync(envFile, 'utf8'));
+  if (!dataDir || !dataDir.startsWith('/mnt/data/')) return [];
+  const parts = dataDir.slice('/mnt/data/'.length).split('/').filter(part => part && part !== '.');
+  if (parts.some(part => part === '..' || part.includes('\\') || part.includes('\0'))) {
+    throw new Error('DATA_DIR must remain inside the /mnt/data storage mount');
+  }
+  return parts;
+}
+
+/**
+ * Create the mount root and any configured DATA_DIR inside it, preserving state.
+ * Refuse child symlinks so initialization cannot write outside the storage root.
+ * @param {string} localPath - Host directory mounted at /mnt/data
+ * @param {string|undefined} envFile - Resolved application env file
+ * @returns {void}
+ */
+function prepareLocalDataMount(localPath, envFile) {
+  try {
+    const parts = dataDirectoryParts(envFile);
+    fs.mkdirSync(localPath, { recursive: true });
+    let directory = localPath;
+    for (const part of parts) {
+      directory = path.join(directory, part);
+      try {
+        const stat = fs.lstatSync(directory);
+        if (stat.isSymbolicLink() || !stat.isDirectory()) {
+          throw new Error('DATA_DIR components must be directories, not symlinks or files');
+        }
+      } catch (error) {
+        if (error.code !== 'ENOENT') throw error;
+        fs.mkdirSync(directory);
+      }
+    }
+  } catch (error) {
+    // Filesystem errors can include env content or paths; report only their code.
+    const reason = error.code || error.message;
+    throw new Error(`Unable to prepare local storage before container startup: ${reason}`);
+  }
+}
+
+module.exports = { prepareLocalDataMount };

package/lib/utils/secrets-helpers.js

@@ -55,7 +55,6 @@ const { resolveBashKvFromProcessEnv } = require('./secrets-bash-kv');
 const EMPTY_ALLOWED_KV_FALLBACK = new Set([
   'redis-passwordKeyVault',
   'azure-openaiapi-urlKeyVault',
-  'secrets-azureOpenaiApiKeyVault',
   'miso-controller-secrets-apiKeyVault'
 ]);