genesis-compiler 1.2.1 → 1.2.3

package/src/index/code-index.js

@@ -3,6 +3,8 @@ import path from 'node:path';
 
 import { astGrepCodeIndexers } from './code-indexers/ast-grep.js';
 import { asDiagnostic } from './errors.js';
+import { buildCityPresentation } from './city-presentation.js';
+import { cityPathExcluded } from './stack-city-presentation.js';
 import { gitContext } from './git.js';
 import { isProjectContentPath } from './paths.js';
 import { inspectProgram } from './program.js';
@@ -128,8 +130,14 @@ function mergeIndexedFiles(contributions) {
   };
 }
 
-function machineCity({ components, contributions, diagnostics, indexers }) {
+function machineCity({ cityRegions, components, contributions, diagnostics, indexers }) {
   const merged = mergeIndexedFiles(contributions);
+  const structuralDistricts = directoryRecords(merged.files.map(({ path: filePath }) => filePath));
+  const presentation = buildCityPresentation({
+    districts: structuralDistricts,
+    files: merged.files,
+    regions: cityRegions,
+  });
   const visibility = new Map(merged.functions.map((entry) => [entry.id, entry.visibility]));
   const codeHash = sha256(stableJson(merged.files.map(({ path: filePath, hash, mode }) => ({
     path: filePath,
@@ -141,13 +149,19 @@ function machineCity({ components, contributions, diagnostics, indexers }) {
     schemaVersion: 1,
     status: indexers.length === 0 ? 'unconfigured' : diagnostics.length > 0 ? 'completed-with-warning' : 'current',
     codeHash,
+    presentationRegions: presentation.regions,
+    presentationCampuses: presentation.campuses,
     stackComponents: components,
     indexers,
     diagnostics,
     functions: merged.functions,
-    districts: directoryRecords(merged.files.map(({ path: filePath }) => filePath)),
+    districts: structuralDistricts.map((district) => ({
+      ...district,
+      ...presentation.placementForPath(district.path),
+    })),
     buildings: merged.files.map((file) => ({
       ...file,
+      ...presentation.placementForPath(file.path),
       districtId: directoryId(parentDirectory(file.path)),
       title: path.posix.basename(file.path),
       publicFunctionCount: file.functionIds.filter((id) => visibility.get(id) === 'public').length,
@@ -229,7 +243,13 @@ export async function buildProjectIndex({ projectRoot, queries = [], write = tru
   const stack = await readStack(root);
   const states = await gitVisibleFileStates(root, { includePath: isProjectContentPath });
   const files = [...states]
-    .filter(([, state]) => state.exists && !state.symlink && !state.special && state.hash)
+    .filter(([filePath, state]) => (
+      state.exists
+      && !state.symlink
+      && !state.special
+      && state.hash
+      && !cityPathExcluded(filePath, stack.cityExclusions)
+    ))
     .map(([filePath, state]) => ({ path: filePath, hash: state.hash, mode: state.mode }));
   const indexers = [...new Set(stack.components.flatMap((component) => component.indexers || []))].sort();
   const contributions = [];
@@ -249,6 +269,7 @@ export async function buildProjectIndex({ projectRoot, queries = [], write = tru
     }
   }
   const machine = machineCity({
+    cityRegions: stack.cityRegions,
     components: stack.components.map(({ id }) => id),
     contributions,
     diagnostics,

package/src/index/deployment.js

@@ -0,0 +1,31 @@
+import { gitContext } from './git.js';
+import { readStack } from './stack.js';
+import { sha256, stableJson, uniqueSorted } from './utils.js';
+
+/** Read the Stack's production recipe without provisioning or publishing anything. */
+export async function inspectProjectDeployment({ projectRoot } = {}) {
+  const root = (await gitContext(projectRoot)).repositoryRoot;
+  const stack = await readStack(root);
+  const diagnostics = [...stack.deployment.diagnostics];
+  let status = 'unconfigured';
+  if (diagnostics.length > 0) status = 'blocked';
+  else if (stack.deployment.steps.length > 0) status = 'ready';
+  const recipe = {
+    version: stack.deployment.version,
+    workdir: stack.deployment.workdir,
+    runtimeRequirements: stack.deployment.runtimeRequirements,
+    readiness: stack.deployment.readiness,
+    steps: stack.deployment.steps,
+  };
+  return {
+    status,
+    stackHash: stack.identityHash,
+    recipeHash: status === 'ready' ? sha256(stableJson(recipe)) : '',
+    components: stack.components.map(({ id }) => id),
+    source: stack.deployment.source,
+    runtimeRequirements: uniqueSorted(stack.deployment.runtimeRequirements),
+    resources: stack.resources,
+    ...recipe,
+    diagnostics,
+  };
+}

package/src/index/environment-files.js

@@ -1,17 +1,24 @@
 import { gitContext } from './git.js';
 import { readStack } from './stack.js';
+import { withStackEnvironmentDefaults } from './stack-environment-defaults.js';
 import { missingStackResources } from './stack-preflight.js';
 
-/** Inspect Stack environment requirements without returning or writing values. */
+/** Inspect Stack environment requirements without returning supplied host values. */
 export async function inspectProjectEnvironment({ environment = process.env, projectRoot } = {}) {
   const root = (await gitContext(projectRoot)).repositoryRoot;
   const stack = await readStack(root);
-  const diagnostics = missingStackResources({ environment, resources: stack.resources });
-  const configured = stack.environmentFiles.length > 0 || stack.resources.length > 0;
+  const diagnostics = missingStackResources({
+    environment: withStackEnvironmentDefaults(environment, stack.environmentDefaults),
+    resources: stack.resources,
+  });
+  const configured = stack.environmentDefaults.length > 0
+    || stack.environmentFiles.length > 0
+    || stack.resources.length > 0;
   return {
     status: !configured ? 'unconfigured' : diagnostics.length > 0 ? 'missing-inputs' : 'ready',
     stackHash: stack.identityHash,
     components: stack.components.map(({ id }) => id),
+    environmentDefaults: stack.environmentDefaults,
     files: stack.environmentFiles,
     resources: stack.resources,
     diagnostics,

package/src/index/init.js

@@ -12,7 +12,7 @@ async function createIfMissing(projectRoot, relativePath, source) {
   const location = path.join(projectRoot, relativePath);
   await mkdir(path.dirname(location), { recursive: true });
   try {
-    await writeFile(location, source, { flag: 'wx', mode: 0o644 });
+    await writeFile(location, source, { flag: 'wx', mode: 0o666 });
     return relativePath;
   } catch (error) {
     if (error?.code === 'EEXIST') return null;

package/src/index/launch.js

@@ -1,5 +1,6 @@
 import { gitContext } from './git.js';
 import { missingStackResources } from './stack-preflight.js';
+import { withStackEnvironmentDefaults } from './stack-environment-defaults.js';
 import { readStack } from './stack.js';
 import { uniqueSorted } from './utils.js';
 
@@ -10,7 +11,10 @@ export async function inspectProjectLaunch({
 } = {}) {
   const root = (await gitContext(projectRoot)).repositoryRoot;
   const stack = await readStack(root);
-  const diagnostics = missingStackResources({ environment, resources: stack.resources });
+  const diagnostics = missingStackResources({
+    environment: withStackEnvironmentDefaults(environment, stack.environmentDefaults),
+    resources: stack.resources,
+  });
   const disabledReason = diagnostics.length === 0
     ? null
     : diagnostics.map(({ message }) => message).join(' ');
@@ -26,6 +30,7 @@ export async function inspectProjectLaunch({
     status,
     stackHash: stack.identityHash,
     components: stack.components.map(({ id }) => id),
+    environmentDefaults: stack.environmentDefaults,
     runtimeRequirements: uniqueSorted(targets.flatMap((target) => target.runtimeRequirements)),
     resources: stack.resources,
     targets,

package/src/index/prompt.js

@@ -9,6 +9,7 @@ import { gitContext } from './git.js';
 import { inspectProgram } from './program.js';
 import { inspectVerification } from './project-state.js';
 import { missingStackResources } from './stack-preflight.js';
+import { withStackEnvironmentDefaults } from './stack-environment-defaults.js';
 import { stableJson } from './utils.js';
 import { gitVisibleFileStates } from './project-files.js';
 import { isProjectContentPath } from './paths.js';
@@ -305,7 +306,10 @@ export async function generateProjectPrompt({
     buildProjectIndex({ projectRoot: root, write: false }),
     inspectProjectSkills({ projectRoot: root, stack }),
   ]);
-  const missing = missingStackResources({ environment, resources: stack.resources });
+  const missing = missingStackResources({
+    environment: withStackEnvironmentDefaults(environment, stack.environmentDefaults),
+    resources: stack.resources,
+  });
   const warnings = [
     ...(program.diagnostic ? [program.diagnostic] : []),
     ...missing,

package/src/index/stack-catalog.js

@@ -63,7 +63,10 @@ export async function listBuiltinStackPieces() {
       guidance: piece.guidance,
       requires: piece.requires,
       conflicts: piece.conflicts,
+      cityExclusions: piece.cityExclusions,
+      cityRegions: piece.cityRegions,
       indexers: piece.indexers,
+      environmentDefaults: piece.environmentDefaults,
       launchTargets: piece.launchTargets.map(({ id }) => id),
       workspaceSetup: piece.workspaceSetupSteps,
       skill: piece.skill === null ? null : piece.skill.path,

package/src/index/stack-city-presentation.js

@@ -0,0 +1,178 @@
+import { GenesisError } from './errors.js';
+
+const ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+const IGNORE_LINE = /^- Ignore `([^`]+)`[ \t]*$/u;
+const MATCH_LINE = /^- Match `([^`]+)` as `([^`]+)`: `([^`]+)\/\*\*`[ \t]*$/u;
+const FALLBACK_LINE = /^- Fallback `([^`]+)` as `([^`]+)`[ \t]*$/u;
+const REGEXP_SPECIAL = /[.+^${}()|[\]\\]/u;
+const compiledGlobPatterns = new Map();
+
+function invalid(piecePath, message) {
+  throw new GenesisError('STACK_PIECE_INVALID', message, { path: piecePath });
+}
+
+function normalizedPrefix(value, piecePath) {
+  const prefix = String(value || '').trim();
+  if (
+    !prefix
+    || prefix.startsWith('/')
+    || prefix.includes('\\')
+    || /[*?\[\]{}!]/u.test(prefix)
+    || prefix.split('/').some((segment) => !segment || ['.', '..'].includes(segment))
+  ) {
+    invalid(piecePath, '## City regions match paths must be canonical project-relative prefixes.');
+  }
+  return prefix;
+}
+
+function normalizedGlob(value, piecePath) {
+  const pattern = String(value || '').trim();
+  if (
+    !pattern
+    || pattern.startsWith('/')
+    || pattern.includes('\\')
+    || pattern.includes('***')
+    || /[?\[\]{}!]/u.test(pattern)
+    || pattern.split('/').some((segment) => !segment || ['.', '..'].includes(segment))
+  ) {
+    invalid(
+      piecePath,
+      '## City regions ignore patterns must be canonical project-relative globs using only * and ** wildcards.',
+    );
+  }
+  return pattern;
+}
+
+function regionIdentity(id, title, piecePath) {
+  if (!ID_PATTERN.test(id)) {
+    invalid(piecePath, '## City regions ids must use lowercase letters, digits, and single hyphens.');
+  }
+  if (!title.trim()) invalid(piecePath, '## City regions titles must not be empty.');
+  return { id, title: title.trim() };
+}
+
+function globExpression(pattern) {
+  if (compiledGlobPatterns.has(pattern)) return compiledGlobPatterns.get(pattern);
+  let expression = '^';
+  for (let index = 0; index < pattern.length; index += 1) {
+    const character = pattern[index];
+    if (character === '*' && pattern[index + 1] === '*') {
+      if (pattern[index + 2] === '/') {
+        expression += '(?:[^/]+/)*';
+        index += 2;
+      } else {
+        expression += '.*';
+        index += 1;
+      }
+    } else if (character === '*') {
+      expression += '[^/]*';
+    } else {
+      expression += REGEXP_SPECIAL.test(character) ? `\\${character}` : character;
+    }
+  }
+  const compiled = new RegExp(`${expression}$`, 'u');
+  compiledGlobPatterns.set(pattern, compiled);
+  return compiled;
+}
+
+export function cityPathExcluded(filePath, exclusions = []) {
+  return exclusions.some((pattern) => globExpression(pattern).test(filePath));
+}
+
+/**
+ * A City presentation declaration is one complete, ordered contract. Ignore
+ * globs remove non-product files before Machine City is emitted. Matching
+ * prefixes are explicit Stack facts; one final fallback owns every remaining
+ * path. Genesis resolves both region and campus placement, so renderers never
+ * classify or filter repository paths.
+ */
+export function parseStackCityPresentationLines(lines, { path = 'stack piece' } = {}) {
+  if (lines === undefined) return { exclusions: [], regions: [] };
+  const content = lines.filter((line) => line.trim());
+  if (content.length === 0 || (content.length === 1 && content[0].trim() === '- Nothing.')) {
+    return { exclusions: [], regions: [] };
+  }
+  const exclusions = [];
+  const regions = [];
+  let regionDeclarationStarted = false;
+  content.forEach((line, index) => {
+    const ignore = line.match(IGNORE_LINE);
+    if (ignore) {
+      if (regionDeclarationStarted) {
+        invalid(path, '## City regions Ignore entries must precede Match and Fallback entries.');
+      }
+      exclusions.push(normalizedGlob(ignore[1], path));
+      return;
+    }
+    regionDeclarationStarted = true;
+    const match = line.match(MATCH_LINE);
+    if (match) {
+      const identity = regionIdentity(match[1], match[2], path);
+      regions.push({
+        ...identity,
+        fallback: false,
+        pathPrefix: normalizedPrefix(match[3], path),
+      });
+      return;
+    }
+    const fallback = line.match(FALLBACK_LINE);
+    if (fallback) {
+      if (index !== content.length - 1) {
+        invalid(path, '## City regions fallback must be the final declaration.');
+      }
+      regions.push({
+        ...regionIdentity(fallback[1], fallback[2], path),
+        fallback: true,
+        pathPrefix: null,
+      });
+      return;
+    }
+    invalid(
+      path,
+      '## City regions entries must use Ignore with a glob, Match with an id, title, and path/**, or one final Fallback.',
+    );
+  });
+  if (new Set(exclusions).size !== exclusions.length) {
+    invalid(path, '## City regions contains a duplicate ignore pattern.');
+  }
+  if (new Set(regions.map(({ id }) => id)).size !== regions.length) {
+    invalid(path, '## City regions contains a duplicate region id.');
+  }
+  const matches = regions.filter(({ fallback }) => !fallback);
+  if (new Set(matches.map(({ pathPrefix }) => pathPrefix)).size !== matches.length) {
+    invalid(path, '## City regions contains a duplicate path prefix.');
+  }
+  if (regions.filter(({ fallback }) => fallback).length !== 1) {
+    invalid(path, '## City regions requires exactly one final fallback.');
+  }
+  for (const [index, left] of matches.entries()) {
+    if (matches.slice(index + 1).some((right) => (
+      left.pathPrefix.startsWith(`${right.pathPrefix}/`)
+      || right.pathPrefix.startsWith(`${left.pathPrefix}/`)
+    ))) {
+      invalid(path, '## City regions match prefixes must not overlap.');
+    }
+  }
+  return { exclusions, regions };
+}
+
+export function composeStackCityPresentation(components = []) {
+  const owners = components.filter((component) => (
+    component.cityRegions.length > 0 || component.cityExclusions.length > 0
+  ));
+  if (owners.length === 0) return { exclusions: [], regions: [] };
+  if (owners.length > 1) {
+    throw new GenesisError(
+      'STACK_CITY_PRESENTATION_AMBIGUOUS',
+      `Stack components ${owners.map(({ id }) => id).join(', ')} declare competing City presentation contracts.`,
+      { components: owners.map(({ id }) => id) },
+    );
+  }
+  return {
+    exclusions: [...owners[0].cityExclusions],
+    regions: owners[0].cityRegions.map((region) => ({
+      ...region,
+      component: owners[0].id,
+    })),
+  };
+}

package/src/index/stack-deployment.js

@@ -0,0 +1,204 @@
+import { GenesisError } from './errors.js';
+import {
+  isCanonicalProjectWorkdir,
+  isSafeProcessExecutable,
+  parseBacktickedArguments,
+} from './stack-process.js';
+
+const RUNTIME_ID = /^[a-z0-9]+(?:-[a-z0-9]+)*$/u;
+const STEP_LINE = /^- (Prepare|Build|Migrate|Serve) `([^`\r\n]+)`:[ \t]+(.+)$/u;
+const STEP_ROLE_ORDER = Object.freeze({
+  prepare: 0,
+  build: 1,
+  migrate: 2,
+  serve: 3,
+});
+
+function invalid(deploymentPath, message, line, details = {}) {
+  throw new GenesisError('STACK_DEPLOYMENT_INVALID', message, {
+    path: deploymentPath,
+    ...(line === undefined ? {} : { line }),
+    ...details,
+  });
+}
+
+function oneToken(source, prefix, deploymentPath, label, line) {
+  const values = parseBacktickedArguments(source.slice(prefix.length));
+  if (!values || values.length !== 1) {
+    invalid(deploymentPath, `${label} accepts exactly one backticked value.`, line);
+  }
+  return values[0];
+}
+
+function parseRuntimes(source, deploymentPath, line) {
+  const values = parseBacktickedArguments(source.slice('- Runtimes: '.length));
+  if (!values || values.some((value) => !RUNTIME_ID.test(value))) {
+    invalid(
+      deploymentPath,
+      'Deployment runtimes must be separate backticked technology ids.',
+      line,
+    );
+  }
+  if (new Set(values).size !== values.length) {
+    invalid(deploymentPath, 'Deployment contains a duplicate runtime.', line);
+  }
+  return values;
+}
+
+function parseUrlPath(value, deploymentPath, line) {
+  const normalized = String(value || '').trim();
+  if (!normalized.startsWith('/') || normalized.startsWith('//') || /[\\?#]/u.test(normalized)) {
+    invalid(
+      deploymentPath,
+      'Deployment readiness path must begin with one slash and contain no query or fragment.',
+      line,
+    );
+  }
+  return normalized;
+}
+
+function parseReadiness(source, deploymentPath, line) {
+  const match = source.match(/^- Ready when: `GET` `([^`\r\n]+)` returns `([0-9]{3})`$/u);
+  if (!match) {
+    invalid(
+      deploymentPath,
+      'Deployment readiness must use `- Ready when: `GET` `/path` returns `200``.',
+      line,
+    );
+  }
+  const status = Number(match[2]);
+  if (!Number.isInteger(status) || status < 200 || status > 399) {
+    invalid(deploymentPath, 'Deployment readiness status must be from 200 through 399.', line);
+  }
+  return {
+    kind: 'http',
+    method: 'GET',
+    path: parseUrlPath(match[1], deploymentPath, line),
+    status,
+  };
+}
+
+function parseStep(match, deploymentPath, line) {
+  const label = match[2].trim();
+  const argv = parseBacktickedArguments(match[3]);
+  if (!label || /[\0\r\n]/u.test(label)) {
+    invalid(deploymentPath, 'Deployment step labels must be non-empty single lines.', line);
+  }
+  if (!argv || argv.some((value) => value.includes('\0')) || !isSafeProcessExecutable(argv[0])) {
+    invalid(
+      deploymentPath,
+      'Deployment command and arguments must be separate non-empty backticked values with a safe executable.',
+      line,
+    );
+  }
+  return {
+    label,
+    argv,
+    role: match[1].toLowerCase(),
+  };
+}
+
+export function parseStackDeploymentLines(lines, {
+  path: deploymentPath = 'stack deployment',
+} = {}) {
+  if (lines === undefined) return null;
+  const entries = lines.map((line) => line.trim()).filter(Boolean);
+  if (entries.length === 1 && entries[0] === '- Nothing.') return { version: 1, steps: [] };
+
+  const result = {
+    version: 1,
+    workdir: '.',
+    runtimeRequirements: [],
+    readiness: null,
+    steps: [],
+  };
+  const seen = new Set();
+  for (let index = 0; index < lines.length; index += 1) {
+    const source = lines[index].trim();
+    if (!source) continue;
+    const line = index + 1;
+    if (source.startsWith('- Workdir: ')) {
+      if (seen.has('workdir')) invalid(deploymentPath, 'Duplicate Deployment Workdir.', line);
+      seen.add('workdir');
+      const workdir = oneToken(source, '- Workdir: ', deploymentPath, 'Deployment Workdir', line);
+      if (!isCanonicalProjectWorkdir(workdir)) {
+        invalid(deploymentPath, 'Deployment workdir must be a canonical project-relative directory.', line);
+      }
+      result.workdir = workdir;
+      continue;
+    }
+    if (source.startsWith('- Runtimes: ')) {
+      if (seen.has('runtimes')) invalid(deploymentPath, 'Duplicate Deployment Runtimes.', line);
+      seen.add('runtimes');
+      result.runtimeRequirements = parseRuntimes(source, deploymentPath, line);
+      continue;
+    }
+    if (source.startsWith('- Ready when: ')) {
+      if (seen.has('readiness')) invalid(deploymentPath, 'Duplicate Deployment Ready when.', line);
+      seen.add('readiness');
+      result.readiness = parseReadiness(source, deploymentPath, line);
+      continue;
+    }
+    const step = source.match(STEP_LINE);
+    if (step) {
+      result.steps.push(parseStep(step, deploymentPath, line));
+      continue;
+    }
+    invalid(deploymentPath, `Unknown Deployment entry: ${source}.`, line);
+  }
+  if (result.steps.length === 0) {
+    invalid(deploymentPath, '## Deployment needs at least one command or exactly `- Nothing.`.');
+  }
+  const serveSteps = result.steps.filter(({ role }) => role === 'serve');
+  if (serveSteps.length !== 1 || result.steps.at(-1).role !== 'serve') {
+    invalid(deploymentPath, 'Deployment needs exactly one final Serve step.');
+  }
+  for (let index = 1; index < result.steps.length; index += 1) {
+    if (STEP_ROLE_ORDER[result.steps[index].role] < STEP_ROLE_ORDER[result.steps[index - 1].role]) {
+      invalid(
+        deploymentPath,
+        'Deployment steps must be ordered Prepare, Build, Migrate, then Serve.',
+      );
+    }
+  }
+  if (!result.readiness) {
+    invalid(deploymentPath, 'Deployment needs one Ready when entry.');
+  }
+  return result;
+}
+
+export function composeStackDeployment(components, projectDeployment) {
+  if (projectDeployment) return { ...projectDeployment, source: 'project', diagnostics: [] };
+  const declarations = components
+    .filter((component) => component.deployment?.steps?.length > 0)
+    .map((component) => ({
+      ...component.deployment,
+      source: `component:${component.id}`,
+    }));
+  if (declarations.length === 0) {
+    return {
+      version: 1,
+      workdir: '.',
+      runtimeRequirements: [],
+      readiness: null,
+      steps: [],
+      source: null,
+      diagnostics: [],
+    };
+  }
+  if (declarations.length === 1) return { ...declarations[0], diagnostics: [] };
+  const sources = declarations.map(({ source }) => source).sort();
+  return {
+    version: 1,
+    workdir: '.',
+    runtimeRequirements: [],
+    readiness: null,
+    steps: [],
+    source: null,
+    diagnostics: [{
+      code: 'STACK_DEPLOYMENT_AMBIGUOUS',
+      message: `Selected Stack components provide competing Deployment recipes: ${sources.join(', ')}. Add one project ## Deployment section to choose the exact recipe.`,
+      details: { sources },
+    }],
+  };
+}

package/src/index/stack-environment-defaults.js

@@ -0,0 +1,79 @@
+import { GenesisError } from './errors.js';
+
+const DEFAULT_LINE = /^- Default `([A-Za-z_][A-Za-z0-9_]*)`: `([^`\r\n]+)`[ \t]*$/u;
+
+function invalid(defaultsPath, message, line, details = {}) {
+  throw new GenesisError('STACK_ENVIRONMENT_DEFAULTS_INVALID', message, {
+    path: defaultsPath,
+    ...(line === undefined ? {} : { line }),
+    ...details,
+  });
+}
+
+export function parseStackEnvironmentDefaultLines(lines, {
+  path: defaultsPath = 'stack environment defaults',
+} = {}) {
+  if (lines === undefined) return [];
+  const defaults = [];
+  for (let index = 0; index < lines.length; index += 1) {
+    const source = lines[index].trim();
+    if (!source) continue;
+    const entry = source.match(DEFAULT_LINE);
+    if (!entry) {
+      invalid(
+        defaultsPath,
+        'Every Environment defaults entry must be a Default bullet with a backticked name and value.',
+        index + 1,
+        { observed: source },
+      );
+    }
+    defaults.push({ name: entry[1], value: entry[2] });
+  }
+  if (defaults.length === 0) {
+    invalid(defaultsPath, '## Environment defaults needs at least one Default entry.');
+  }
+  if (new Set(defaults.map(({ name }) => name)).size !== defaults.length) {
+    invalid(defaultsPath, '## Environment defaults contains a duplicate name.');
+  }
+  return defaults;
+}
+
+export function composeStackEnvironmentDefaults(components) {
+  const defaults = new Map();
+  for (const component of components) {
+    for (const declaration of component.environmentDefaults) {
+      const existing = defaults.get(declaration.name);
+      if (existing && existing.value !== declaration.value) {
+        invalid(
+          `component:${component.id}`,
+          `Stack components declare incompatible defaults for ${declaration.name}.`,
+          undefined,
+          {
+            name: declaration.name,
+            sources: [...existing.sources, `component:${component.id}`],
+          },
+        );
+      }
+      if (existing) {
+        existing.sources.push(`component:${component.id}`);
+      } else {
+        defaults.set(declaration.name, {
+          ...declaration,
+          sources: [`component:${component.id}`],
+        });
+      }
+    }
+  }
+  return [...defaults.values()].sort((left, right) => left.name.localeCompare(right.name));
+}
+
+/** Apply public Stack constants beneath explicit host or user environment. */
+export function withStackEnvironmentDefaults(environment, defaults = []) {
+  if (!environment || typeof environment !== 'object' || Array.isArray(environment)) {
+    throw new TypeError('Stack environment resolution requires an environment object.');
+  }
+  return {
+    ...Object.fromEntries(defaults.map(({ name, value }) => [name, value])),
+    ...environment,
+  };
+}