stack.zod.ts

// Copyright (c) 2025 ObjectStack. Licensed under the Apache-2.0 license.

import { z } from 'zod';

import { ManifestSchema, resolveInstallModes } from './kernel/manifest.zod';
import { InstalledPackageSourceSchema } from './kernel/package-registry.zod';
import { DEFAULT_METADATA_TYPE_REGISTRY } from './kernel/metadata-plugin.zod';
import {
  UNMANAGED_INSTALL_KEY_DISPOSITIONS,
  UNMANAGED_INSTALL_REFUSING_DISPOSITIONS,
  unmanagedInstallValueCarries,
} from './kernel/unmanaged-install';
import { PLURAL_TO_SINGULAR, pluralToSingular } from './meta-spelling/manifest-collection-spelling';
import { validateObjectNamespacePrefix } from './kernel/namespace-prefix';
import { PLATFORM_CAPABILITY_TOKENS, RETIRED_PLATFORM_CAPABILITY_GUIDANCE } from './kernel/platform-capabilities';
import { DatasourceSchema } from './data/datasource.zod';
import { TranslationBundleSchema, TranslationConfigSchema } from './system/translation.zod';
import { StackServerConfigSchema } from './system/stack-server.zod';
import { StackEmailConfigSchema } from './system/email-config.zod';
import { StackSmsConfigSchema } from './system/sms-config.zod';
import { DevLoginSchema } from './system/dev-login.zod';
import { DemoStaffSchema } from './system/demo-staff.zod';
import { hasPlatformObjectPrefix, isPlatformProvidedObjectName } from './system/constants/platform-object-names';
import { objectStackErrorMap, formatZodError } from './shared/error-map.zod';
import { strictObject } from './shared/strict-object';
import { deepEqualAuthored } from './shared/deep-equal';
import { markStackProvenance, markRefusalConversions, hasStackProvenance, stackConversionsOf } from './stack-provenance';
import {
  normalizeStackInput,
  MAP_SUPPORTED_FIELDS,
  type MetadataCollectionInput,
  type MapSupportedField,
} from './shared/metadata-collection.zod';
import type { ConversionNotice } from './conversions/types.js';
import { formatUnknownAuthoringKey } from './data/authoring-key-lint';
import { lintUnknownAuthoringKeys, lintUnknownStackKeys } from './kernel/metadata-authoring-lint';

// Data Protocol
import { ObjectSchema, ObjectExtensionSchema } from './data/object.zod';
import { controlledByParentMasterRefusal } from './data/controlled-by-parent-master';
import { fieldGroupBodyTableRefusal, type NamedInboundRelationship } from './data/related-list-body-table';
import { externalBindingDatasourceRefusal } from './data/external-binding-datasource';
import { InlineGridColumnSchema } from './data/field.zod';
import { AUDIT_FIELD_DEFS } from './data/injected-system-column-provenance';
import { pageComponentSlotPositions } from './ui/component.zod';
import { SeedSchema } from './data/seed.zod';

// UI Protocol
import { AppSchema } from './ui/app.zod';
import { ViewSchema, isAggregatedViewContainer, expandViewContainer } from './ui/view.zod';
import { deriveViewContainerObject } from './ui/view-container-object';
import { defaultRecordPageObject } from './ui/default-record-page';
import { PageSchema } from './ui/page.zod';
import { DashboardSchema } from './ui/dashboard.zod';
import { ReportSchema } from './ui/report.zod';
import { DatasetSchema } from './ui/dataset.zod';
import { ActionSchema, InlineActionSchema } from './ui/action.zod';

// Automation Protocol
import { FlowSchema } from './automation/flow.zod';
import { resolveFlowTriggerKind } from './automation/flow-trigger-kind';
import { FlowFunctionEntrySchema, FlowFunctionEffectSchema, FlowFunctionLoweredDeclarationSchema } from './automation/flow-function.zod';
import { JobSchema } from './system/job.zod';

// Security Protocol
import { PositionSchema } from './identity/position.zod';
import { PermissionSetSchema, findHierarchyScopeGrants } from './security/permission.zod';
import { judgePermissionSetOwnerBinding } from './security/permission-set-owner-binding';
import { judgeCollectionItemOwnerStamp, OWNER_STAMP_JUDGED_COLLECTIONS } from './kernel/collection-item-owner-stamp';
import { CapabilityDeclarationSchema } from './security/capabilities';
import { SharingRuleSchema } from './security/sharing.zod';
import { QueueSchema } from './security/queue.zod';
import { AssignmentRuleSchema } from './automation/assignment-rule.zod';

import { ApiEndpointSchema, type ApiEndpoint } from './api/endpoint.zod';
import {
  validateApiEndpointDeclarations,
  validateAnonymousElevatedFlows,
  type ElevatedFlowCandidate,
} from './api/endpoint-publish-gate';
import { retiredKey } from './shared/retired-key';

// AI Protocol
import { AgentSchema } from './ai/agent.zod';
import { SkillSchema } from './ai/skill.zod';
import { ToolSchema } from './ai/tool.zod';

// Data Protocol (additional)
import { HookSchema } from './data/hook.zod';
import { MappingSchema } from './data/mapping.zod';
import { PicklistSchema, PicklistExtensionSchema } from './data/picklist.zod';
import { CubeSchema } from './data/analytics.zod';

// Automation Protocol (additional)
import { WebhookSchema } from './automation/webhook.zod';

// System Protocol (additional)
import { EmailTemplateDefinitionSchema, EMAIL_TEMPLATE_FLOOR_LOCALE } from './system/email-template.zod';
import { DocSchema } from './system/doc.zod';
import { BookSchema } from './system/book.zod';

// Integration Protocol
import { DeclarativeConnectorEntrySchema } from './integration/connector.zod';

/**
 * Datasource Mapping Rule Schema
 *
 * Defines rules for routing objects to specific datasources based on
 * namespace, package, or object name patterns. This provides centralized
 * control over datasource assignment without modifying individual objects.
 *
 * Inspired by Django's Database Router and Kubernetes StorageClass patterns.
 *
 * @example
 * ```ts
 * datasourceMapping: [
 *   { namespace: 'crm', datasource: 'memory' },
 *   { objectPattern: 'sys_*', datasource: 'turso' },
 *   { package: 'com.example.analytics', datasource: 'bigquery' },
 *   { default: true, datasource: 'default' }
 * ]
 * ```
 */
import { lazySchema } from './shared/lazy-schema';
export const DatasourceMappingRuleSchema = lazySchema(() => z.object({
  /**
   * Match by namespace (e.g., 'crm', 'auth', 'todo')
   * Objects with this namespace will use the specified datasource.
   */
  namespace: z.string().optional().describe('Match objects by namespace'),

  /**
   * Match by package ID (e.g., 'com.example.crm')
   * All objects from this package will use the specified datasource.
   */
  package: z.string().optional().describe('Match objects by package ID'),

  /**
   * Match by object name pattern (supports wildcards: *, ?)
   * Examples: 'sys_*', 'temp_*', 'cache_*'
   */
  objectPattern: z.string().optional().describe('Match objects by name pattern (glob-style)'),

  /**
   * Mark as default fallback rule.
   * This rule applies to all objects that don't match any other rules.
   */
  default: z.boolean().optional().describe('Default fallback rule'),

  /**
   * Target datasource name.
   * Must match a registered driver name (e.g., 'memory', 'turso', 'postgres').
   */
  datasource: z.string().describe('Target datasource name'),

  /**
   * Optional priority for rule ordering (lower = higher priority).
   * If not specified, rules are evaluated in array order.
   */
  priority: z.number().optional().describe('Rule priority (lower = higher priority)'),
}).describe('Datasource routing rule'));

export type DatasourceMappingRule = z.input<typeof DatasourceMappingRuleSchema>;

/**
 * Raise every `apis:` publish-gate failure as a Zod issue (#5040 E7).
 *
 * The #4936 blanket refusal that used to live here — a `.max(0)` on `apis`
 * whose error message told the author to delete their endpoints — is GONE, and
 * this is what replaced it. Its premise was that nothing executed a declared
 * endpoint; the #5040 E-series built the executor (mount seam, matcher, policy
 * keys, execution targets, mapping keys), so the refusal would now be the lie
 * in the other direction. What survives is the part that was always right:
 * a declaration this runtime cannot serve is REFUSED, loudly and with a
 * prescription, never parsed into silence.
 *
 * It hangs off the whole stack object rather than the `apis` field because two
 * of the gates are cross-field: the namespace carve-out is derived from
 * `manifest.namespace` (ADR-0121 D2), and uniqueness is a property of the set.
 * Placing it on the SCHEMA — not inside `defineStack` — is what keeps it
 * unavoidable: `defineStack`, `os validate`, the lint scorer, the metadata
 * plugin's artifact ingestion and `EnvironmentArtifactSchema.metadata` all run
 * through this one parse, so no publish path can forget to check.
 *
 * [ADR-0138 D2b] The same parse also runs the one cross-item gate: an
 * `authRequired: false` endpoint of `type: 'flow'` whose `target` names a flow
 * of this stack declaring `runAs: 'system'` is refused, located at the
 * endpoint's `authRequired`, with the record's prescription. Both items are in
 * this one input, so the refusal holds whichever of the two was edited last. A
 * target flow outside the stack is not readable here; the metadata layer's
 * doors read it there (`validateAnonymousElevatedFlows`' module notes).
 */
function applyApiEndpointGates(
  config: {
    manifest?: { namespace?: string | undefined } | undefined;
    apis?: ApiEndpoint[] | undefined;
    flows?: readonly ElevatedFlowCandidate[] | undefined;
  },
  ctx: z.RefinementCtx,
): void {
  for (const issue of validateAnonymousElevatedFlows(config.apis, config.flows)) {
    ctx.addIssue({ code: 'custom', path: issue.path, message: issue.message });
  }

  for (const issue of validateApiEndpointDeclarations(config.apis, {
    namespace: config.manifest?.namespace,
  })) {
    ctx.addIssue({ code: 'custom', path: issue.path, message: issue.message });
  }
}

/**
 * [ADR-0086 D3] Raise every permission set whose body `packageId` disagrees
 * with the package that ships it as a Zod issue at that key: the BUILD door of
 * the owner-binding judge ({@link judgePermissionSetOwnerBinding},
 * `security/permission-set-owner-binding.ts`, whose header holds the rule and
 * every other door). A set's owner is the package it is registered under, so a
 * key naming another package (or any key, on a set no package ships) was
 * registered over in silence; refused here instead, before anything is built.
 *
 * On the SCHEMA rather than inside `defineStack`, for the reason
 * {@link applyApiEndpointGates} gives: `defineStack`, `os validate`, `os build`,
 * the lint scorer and the metadata plugin's artifact ingestion all run this one
 * parse, so no build or load path can skip the judgement. The binding is the id
 * each set is registered under, and nothing else:
 *
 * - **no `packages[]`**: the stack IS its one package, so every top-level set
 *   ships from `manifest.id`, and from no package when there is no `manifest`;
 * - **`packages[]`** (ADR-0130 D4): a body's sets ship from that body's own
 *   `id`. A top-level set that no body declares is the stack's residual,
 *   registered under `manifest.id` (the residual rule is `unclaimedTopLevel` in
 *   `@objectstack/metadata`; a permission set's slot there is its name). A
 *   top-level set that a body declares is a copy of that body's set and is never
 *   registered from the top level, so the top level does not judge it.
 *   The residual rule has one exception: a residual PICKLIST is kept as
 *   metadata only, never registered with the engine. When a residual object's
 *   field names it, the boot lists that object and does not serve it. When a
 *   package body's field names it, the boot's `kernel:ready` picklist audit
 *   refuses that field, and `os validate` / `os build` report it as
 *   `picklist-reference-unknown`. When no object field the engine registers
 *   names it, the boot refuses the stack, and `os validate` / `os build`
 *   refuse it first.
 */
function applyPermissionSetOwnerBindingGate(
  config: { manifest?: { id?: unknown } | undefined; permissions?: unknown; packages?: unknown },
  ctx: z.RefinementCtx,
): void {
  const nameOf = (set: unknown): unknown => (set as { name?: unknown } | null | undefined)?.name;
  const judge = (set: unknown, binding: unknown, path: (string | number)[]): void => {
    const name = nameOf(set);
    const refusal = judgePermissionSetOwnerBinding(
      set,
      typeof name === 'string' ? name : String(name),
      typeof binding === 'string' ? binding : undefined,
      'build',
    );
    if (refusal) ctx.addIssue({ code: 'custom', path: [...path, 'packageId'], message: refusal.message });
  };
  const topLevel = Array.isArray(config.permissions) ? config.permissions : [];
  if (!Array.isArray(config.packages)) {
    topLevel.forEach((set, i) => judge(set, config.manifest?.id, ['permissions', i]));
    return;
  }
  const claimed = new Set<string>();
  config.packages.forEach((entry: unknown, j: number) => {
    const body = (entry as { manifest?: { id?: unknown; permissions?: unknown } } | null | undefined)?.manifest;
    if (!body || !Array.isArray(body.permissions)) return;
    body.permissions.forEach((set: unknown, i: number) => {
      const name = nameOf(set);
      if (typeof name === 'string') claimed.add(name);
      judge(set, body.id, ['packages', j, 'manifest', 'permissions', i]);
    });
  });
  topLevel.forEach((set, i) => {
    const name = nameOf(set);
    if (typeof name === 'string' && claimed.has(name)) return;
    judge(set, config.manifest?.id, ['permissions', i]);
  });
}

/**
 * [ADR-0010] Raise every collection item whose body carries a `_packageId`
 * other than the package that ships it as a Zod issue at that key: the BUILD
 * door of the owner-stamp judge ({@link judgeCollectionItemOwnerStamp},
 * `kernel/collection-item-owner-stamp.ts`, whose header holds the rule, the
 * collections and the other door). The registration door refuses the same
 * stamp at boot or install; judged here too, an author hears it where they
 * wrote it.
 *
 * On the SCHEMA rather than inside `defineStack`, for the reason
 * {@link applyApiEndpointGates} gives: `defineStack`, `os validate`, `os build`,
 * the lint scorer and the metadata plugin's artifact ingestion all run this one
 * parse. It reads the PARSED stack, and every item schema of a judged
 * collection declares `_packageId` (`MetadataProtectionFields`), so the parse
 * keeps the key for the judge. The owner is the id each item is registered
 * under, read the way {@link applyPermissionSetOwnerBindingGate} reads a
 * permission set's:
 *
 * - **no `packages[]`**: every top-level item ships from `manifest.id`, and
 *   from no package when there is no `manifest`;
 * - **`packages[]`** (ADR-0130 D4): a body's items ship from that body's own
 *   `id`. The top level is judged as the boot's residual rule reads it
 *   (`unclaimedTopLevel`, `@objectstack/metadata`), mirrored by
 *   {@link isResidualTopLevelItem} because this package cannot import that one:
 *   a top-level item is the stack's residual, registered under `manifest.id`
 *   and judged against it, only when it occupies a registry slot no body
 *   occupies. A top-level item a body declares is a copy of that body's item,
 *   never registered from the top level, so the top level does not judge it.
 *
 * A stack's `plugins` are runtime plugin instances (`z.unknown()`), not bodies
 * this parse can read; the registration door judges a nested plugin's items
 * when it registers them.
 */
function applyCollectionItemOwnerStampGate(
  config: Record<string, unknown> & { manifest?: { id?: unknown } | undefined; packages?: unknown },
  ctx: z.RefinementCtx,
): void {
  const nameOf = (key: string, item: unknown): string => {
    const it = (item ?? {}) as { name?: unknown; id?: unknown; object?: unknown };
    const name = key === 'data' ? it.object : (it.name ?? it.id ?? (key === 'views' ? it.object : undefined));
    return typeof name === 'string' && name !== '' ? name : '(unnamed)';
  };
  const judgeBody = (
    body: Record<string, unknown>,
    owner: unknown,
    path: (string | number)[],
    judged?: (key: string, item: unknown) => boolean,
  ): void => {
    for (const key of OWNER_STAMP_JUDGED_COLLECTIONS) {
      const items = body[key];
      if (!Array.isArray(items)) continue;
      items.forEach((item: unknown, i: number) => {
        if (judged && !judged(key, item)) return;
        const name = nameOf(key, item);
        const refusal = judgeCollectionItemOwnerStamp(
          item,
          pluralToSingular(key),
          name,
          typeof owner === 'string' ? owner : undefined,
          'build',
        );
        if (refusal) ctx.addIssue({ code: 'custom', path: [...path, key, i, '_packageId'], message: refusal.message });
      });
    }
  };
  if (!Array.isArray(config.packages)) {
    judgeBody(config, config.manifest?.id, []);
    return;
  }
  const bodies: Record<string, unknown>[] = [];
  config.packages.forEach((entry: unknown, j: number) => {
    const body = (entry as { manifest?: Record<string, unknown> } | null | undefined)?.manifest;
    if (!body || typeof body !== 'object') return;
    bodies.push(body);
    judgeBody(body, body.id, ['packages', j, 'manifest']);
  });
  judgeBody(config, config.manifest?.id, [], isResidualTopLevelItem(bodies));
}

/**
 * The judged collections a `packages[]` stack's TOP LEVEL never files as
 * residual items: the boot's residual rule (`unclaimedTopLevel`,
 * `@objectstack/metadata`) walks the collections the metadata door registers
 * as items (its `ARTIFACT_FIELD_TO_TYPE`), and these two are not among them,
 * so the boot judges no stamp on a top-level item of either. Both are read off
 * the stack whole, the top level merged with every body
 * (`resolveArtifactCollections`, `@objectstack/runtime`): `AppPlugin` hands the
 * seed `data` to the seed loader and schedules the `jobs`.
 * `datasets` is not here: the residual rule walks it, so a top-level dataset
 * that no body declares is registered under `manifest.id` and its stamp is
 * judged at both doors, like every other residual item.
 * A package BODY's items of these collections are still judged, at both doors.
 *
 * Mirrored, because `@objectstack/spec` cannot import the rule it mirrors; a
 * `@objectstack/metadata` test holds the two equal, collection by collection.
 */
const TOP_LEVEL_COLLECTIONS_NEVER_RESIDUAL: ReadonlySet<string> = new Set(['data', 'jobs']);

/**
 * The registry slot one item occupies, the way the boot's residual rule
 * derives it (`artifactItemSlot`, `@objectstack/metadata`): an aggregated view
 * container is filed under the object it binds to
 * ({@link deriveViewContainerObject}), however that binding is spelled; any
 * other item under its `name`, a `views` entry without one falling back to the
 * same derivation. `undefined`: no slot, so no door registers the item.
 */
function residualSlotOf(key: string, item: unknown): string | undefined {
  if (key === 'views' && isAggregatedViewContainer(item)) return deriveViewContainerObject(item) || undefined;
  const name = (item as { name?: unknown } | null | undefined)?.name;
  if (name) return String(name);
  return key === 'views' ? deriveViewContainerObject(item) || undefined : undefined;
}

/**
 * Whether a top-level item of a `packages[]` stack is its RESIDUAL: the
 * mirror of `unclaimedTopLevel`'s judgement (`@objectstack/metadata`). True
 * when the item's collection is one the rule walks
 * ({@link TOP_LEVEL_COLLECTIONS_NEVER_RESIDUAL}), the item occupies a slot
 * ({@link residualSlotOf}), and no body occupies that slot in the same
 * collection: a body's container claims its object's slot and the slot of
 * every view it expands into ({@link expandViewContainer}), any other body
 * item its name's.
 */
function isResidualTopLevelItem(bodies: readonly Record<string, unknown>[]): (key: string, item: unknown) => boolean {
  // `<collection>:<slot>`: no collection key carries a `:`, so the pair is unambiguous.
  const claimed = new Set<string>();
  for (const body of bodies) {
    for (const key of OWNER_STAMP_JUDGED_COLLECTIONS) {
      const items = body[key];
      if (!Array.isArray(items)) continue;
      for (const item of items) {
        const slot = residualSlotOf(key, item);
        if (slot === undefined) continue;
        claimed.add(`${key}:${slot}`);
        if (key === 'views' && isAggregatedViewContainer(item)) {
          for (const view of expandViewContainer(slot, item)) claimed.add(`views:${view.name}`);
        }
      }
    }
  }
  return (key, item) => {
    if (TOP_LEVEL_COLLECTIONS_NEVER_RESIDUAL.has(key)) return false;
    const slot = residualSlotOf(key, item);
    return slot !== undefined && !claimed.has(`${key}:${slot}`);
  };
}

/** One `objectExtensions` entry as the registry registers it, with where it sits in the stack. */
interface VisibleObjectExtension {
  /** The position of the package that ships it: registration order across packages. */
  readonly carrier: number;
  /** The entry's path in the stack, e.g. `['objectExtensions', 0]`. */
  readonly path: readonly (string | number)[];
  /** `ext.priority ?? 200`, the registry's own default (`engine.ts`, the `objectExtensions` loop). */
  readonly priority: number;
  readonly fields: Record<string, unknown>;
}

/**
 * [#23210 · ADR-0055 §1] The controlled-by-parent master rule, judged on the
 * MERGED field set of an object that an `objectExtensions` entry of this stack
 * extends — the BUILD door of the rule the per-object refinement
 * (`refuseControlledByParentWithoutOneMaster`, `data/object.zod.ts`) applies
 * to an object as it is declared.
 *
 * ## Why the per-object refinement is not enough
 *
 * The registry folds every extension onto its target at boot
 * (`SchemaRegistry.resolveObject`, `objectql/src/registry.ts`), so an object
 * that passes as declared can run with two required `master_detail` fields —
 * or none — once an extension in the same stack is merged. The runtime then
 * derives no master and fails closed (every read denied, every write refused),
 * while `defineStack` and `os validate` had said nothing. The same merged
 * object declared directly is refused here, with this message; so is the
 * extension that produces it.
 *
 * ## The merge, read exactly as the registry computes it
 *
 * - The base is the target's own declaration; an extension carries no
 *   `sharingModel` (`ObjectExtensionSchema` is closed and the merge copies
 *   `fields`, `validations`, `indexes` and three labels only), so the merged
 *   object's `sharingModel` is the target's.
 * - `fields` merge BY NAME, a later writer replacing the whole field
 *   (`mergeObjectDefinitions`: `{ ...base.fields, ...extension.fields }`). An
 *   extension can therefore demote the one master (`required: false`, another
 *   type) as well as add a second.
 * - Extensions apply in ascending `priority`, equal priorities in
 *   registration order (a stable sort), and a package registers one extension
 *   per target: a later entry of the same package replaces an earlier one.
 *
 * ## Which targets this door can see — and the ones it leaves unjudged
 *
 * The registry keys an extension by its `extend` string verbatim
 * (`computeFQN` is the identity), so an extension merges into the object whose
 * `name` is exactly that string, and only that one. A target is visible when
 * the stack declares it:
 *
 * - **no `packages[]`**: the stack is its one package — its top-level
 *   `objects`, extended by its top-level `objectExtensions`;
 * - **`packages[]`** (ADR-0130 D4): the artifact is the co-ownership
 *   boundary, so an extension in any body judges a target declared in any
 *   body, or a top-level object no body declares (the residual the engine
 *   registers too). The top-level `objectExtensions` are not read there: the
 *   engine registers a multi-package stack's bodies and the residual's
 *   objects, never its top-level extensions.
 *
 * Left unjudged, on purpose, so that nothing here guesses at an object the
 * stack cannot see: an `extend` naming no object of the stack (another
 * package's, the platform's); a target two bodies declare (the registry
 * refuses that ownership conflict on its own); a target whose own declaration
 * already breaks the rule (the per-object refinement reports it there); and a
 * target on which two packages write one field key at the `priority` that
 * decides it, whose winner is the registration order the artifact loader
 * computes (`resolveArtifactPackageOrder`, dependency-topological), not this
 * parse.
 *
 * ## Where the issue sits
 *
 * At the `fields` of each extension that wrote the field that decides the
 * verdict: the last writer of every key that is a `master_detail` in the
 * target's declaration or in the merged set. That is the line that introduced
 * the second master, or that demoted the one. The message is the per-object
 * refinement's own ({@link controlledByParentMasterRefusal}), naming the
 * target and the merged fields — one rule, one wording.
 *
 * On the SCHEMA, for the reason {@link applyApiEndpointGates} gives:
 * `defineStack`, `os validate`, `os build`, the lint scorer and an artifact
 * load all run this parse.
 */
function applyControlledByParentExtensionGate(
  config: { objects?: unknown; objectExtensions?: unknown; packages?: unknown },
  ctx: z.RefinementCtx,
): void {
  const asRecord = (value: unknown): Record<string, unknown> | undefined =>
    typeof value === 'object' && value !== null && !Array.isArray(value)
      ? (value as Record<string, unknown>)
      : undefined;

  const bodies = Array.isArray(config.packages)
    ? config.packages.map((entry: unknown) => asRecord(asRecord(entry)?.manifest) ?? {})
    : undefined;

  // Target name → its declaration, or `null` when two packages claim it.
  const targets = new Map<string, Record<string, unknown> | null>();
  const declare = (objects: unknown, carrier: number, owners: Map<string, number>): void => {
    if (!Array.isArray(objects)) return;
    for (const obj of objects) {
      const record = asRecord(obj);
      const name = record?.name;
      if (!record || typeof name !== 'string' || name.length === 0) continue;
      const owner = owners.get(name);
      if (targets.get(name) === null) continue;
      if (owner !== undefined && owner !== carrier) {
        targets.set(name, null);
        continue;
      }
      owners.set(name, carrier);
      // The same package declaring one name twice re-registers it: the last wins.
      targets.set(name, record);
    }
  };
  const owners = new Map<string, number>();
  if (bodies === undefined) {
    declare(config.objects, 0, owners);
  } else {
    bodies.forEach((body, j) => declare(body.objects, j, owners));
    // The residual: a top-level object no body declares.
    const residual = Array.isArray(config.objects)
      ? config.objects.filter((obj: unknown) => {
        const name = asRecord(obj)?.name;
        return typeof name === 'string' && !owners.has(name);
      })
      : [];
    declare(residual, bodies.length, owners);
  }

  // Target name → its extensions, one per package (the last entry wins).
  const extensions = new Map<string, Map<number, VisibleObjectExtension>>();
  const collect = (entries: unknown, carrier: number, at: readonly (string | number)[]): void => {
    if (!Array.isArray(entries)) return;
    entries.forEach((entry: unknown, i: number) => {
      const record = asRecord(entry);
      const target = record?.extend;
      if (!record || typeof target !== 'string' || !targets.get(target)) return;
      const byCarrier = extensions.get(target) ?? new Map<number, VisibleObjectExtension>();
      byCarrier.set(carrier, {
        carrier,
        path: [...at, 'objectExtensions', i],
        priority: typeof record.priority === 'number' ? record.priority : 200,
        fields: asRecord(record.fields) ?? {},
      });
      extensions.set(target, byCarrier);
    });
  };
  if (bodies === undefined) collect(config.objectExtensions, 0, []);
  else bodies.forEach((body, j) => collect(body.objectExtensions, j, ['packages', j, 'manifest']));

  for (const [target, byCarrier] of extensions) {
    const base = targets.get(target);
    const baseFields = asRecord(base?.fields);
    if (!base || !baseFields || base.sharingModel !== 'controlled_by_parent') continue;
    if (controlledByParentMasterRefusal(target, base.sharingModel, baseFields) !== undefined) continue;

    const ordered = [...byCarrier.values()].sort((a, b) => a.priority - b.priority || a.carrier - b.carrier);
    const writers = new Map<string, VisibleObjectExtension>();
    // Per key, how many packages wrote it at the priority of its last writer.
    // Above one, the winner is registration order, which this parse does not compute.
    const tiedWriters = new Map<string, number>();
    const merged: Record<string, unknown> = { ...baseFields };
    for (const extension of ordered) {
      for (const [key, field] of Object.entries(extension.fields)) {
        const previous = writers.get(key);
        tiedWriters.set(key, previous?.priority === extension.priority ? (tiedWriters.get(key) ?? 1) + 1 : 1);
        writers.set(key, extension);
        merged[key] = field;
      }
    }
    if ([...tiedWriters.values()].some((count) => count > 1)) continue;

    const refusal = controlledByParentMasterRefusal(target, base.sharingModel, merged);
    if (refusal === undefined) continue;
    const isMaster = (field: unknown): boolean => asRecord(field)?.type === 'master_detail';
    const blamed = new Set<VisibleObjectExtension>();
    for (const [key, extension] of writers) {
      if (isMaster(merged[key]) || isMaster(baseFields[key])) blamed.add(extension);
    }
    for (const extension of ordered) {
      if (!blamed.has(extension)) continue;
      ctx.addIssue({ code: 'custom', path: [...extension.path, 'fields'], message: refusal.message });
    }
  }
}

/**
 * One package entry as an AUTHOR writes it — manifest only (ADR-0130 D4).
 *
 * A release artifact MAY carry N package manifests: everything inside one
 * artifact is delivered atomically by one publisher, and that joint delivery IS
 * the co-ownership declaration (ADR-0130 D1).
 *
 * ## This is the AUTHORING stage, not the artifact's element type
 *
 * The element type of `packages` on {@link ObjectStackDefinitionSchema} is
 * {@link ArtifactPackageSchema}, whose body half is the ASSEMBLED package body
 * — manifest fields plus the metadata collections that package owns, which is
 * what `ObjectQL.registerApp` iterates. This schema stays at the stage its body
 * half can actually describe: `ManifestSchema`, whose `objects` are glob
 * PATTERNS. #14242 measured that a full parse of a real artifact entry against
 * it is refused (`manifest.objects.0: expected string, received object`), and
 * the maintainer's decision (2026-09-02, road B) was to declare the assembled
 * stage beside this one rather than widen either into a union that could check
 * neither.
 *
 * So: this schema for what an author hands `composeStacks`,
 * {@link ArtifactPackageSchema} for what the artifact carries and the load path
 * registers. An authoring entry is a valid instance of the assembled one
 * whenever its manifest declares no globs — a package identity with no
 * collections.
 *
 * ## ⛔ The entry is a WRAPPER object, and that is the whole point of its shape
 *
 * The manifest body sits UNDER a key (`manifest`); it is never inlined flat as
 * the array element itself. ADR-0130 D4 reserves the position deliberately, at
 * schema time, and says why: an artifact schema is on disk at every customer,
 * so format is the hardest decision to revisit — 黑猫's 30-object artifact is
 * already 2.6 MB, and modules accreting into one JSON grow both marketplace
 * transfer and startup parse. When a future external-segment form lands, it is
 * `{ ref, integrity }` — an ADDITIVE key on this existing object. Flatten the
 * manifest into the array element instead and that same future is a SHAPE
 * change: `ref`/`integrity` would have to be bolted onto `ManifestSchema`
 * (which every other consumer shares) and every required manifest field would
 * have to go optional, because a segment reference carries no manifest content
 * at all.
 *
 * ⛔ Segmented loading itself is NOT implemented and is an explicit Non-goal of
 * ADR-0130 ("D4 reserves the key position only. The segmented form itself needs
 * its own decision."). This schema reserves structure, nothing else.
 *
 * Forward compatibility rides the mechanism that already exists —
 * `manifest.engines.protocol` (ADR-0025, `kernel/manifest.zod.ts`). A
 * new-format artifact declares a new protocol range and an older runtime
 * refuses it cleanly instead of mis-parsing it into a half-registered install.
 * ⛔ No new version-negotiation mechanism is introduced here.
 *
 * @example
 * ```jsonc
 * {
 *   "packages": [
 *     { "manifest": { "id": "com.example.crm", "name": "crm", "version": "1.0.0",
 *                     "type": "app", "namespace": "crm" } },
 *     { "manifest": { "id": "com.example.crm.cpq", "name": "cpq", "version": "1.0.0",
 *                     "type": "module", "namespace": "crm" } }
 *   ]
 * }
 * ```
 */
export const ArtifactPackageEntrySchema = lazySchema(() => strictObject({
  surface: 'an artifact package entry',
  history:
    'The entry is a wrapper object whose manifest body lives under `manifest:` — the '
    + 'structural position ADR-0130 D4 reserves so a future `{ ref, integrity }` external '
    + 'segment is an additive key rather than a reshape. An inlined manifest body (`id`, '
    + '`name`, `version`, … written directly on the array element) is therefore refused: '
    + 'wrap it as `{ manifest: { … } }`.',
}, {
  manifest: ManifestSchema.describe('The package manifest this artifact entry carries'),
}).describe('One package entry as authored — manifest only (ADR-0130 D4)'));

export type ArtifactPackageEntry = z.input<typeof ArtifactPackageEntrySchema>;
/** Post-parse shape of {@link ArtifactPackageEntry} — defaults applied, transforms run (ADR-0122). */
export type ArtifactPackageEntryParsed = z.infer<typeof ArtifactPackageEntrySchema>;

/**
 * The datasource name the HOST owns (#3826, #23634): the runtime declares and
 * connects `default` itself (`DefaultDatasourcePlugin`, from `OS_DATABASE_URL`
 * or the dev fallback), and `AppPlugin` refuses a stack that declares it in
 * every boot posture — with a URL, with `--dev`, and on the standalone path.
 * The comparison is the runtime's: the entry's `name` equals `default` exactly
 * (the map form arrives here already normalized, key → `name`; every other
 * spelling of the word is already refused by `DatasourceSchema.name`'s
 * snake_case pattern).
 *
 * The refusal lives on the STACK's collection, ⛔ never on
 * {@link DatasourceSchema}: that schema also documents the host's own
 * `default` row (the registry, the admin list, the metadata door), which must
 * keep parsing. Saying it here moves the runtime's refusal to the authoring
 * doors — `defineStack`, `os validate` and publish — with the same sentence
 * and the remedy, instead of after the boot's earlier plugins have started.
 */
const HOST_RESERVED_DATASOURCE_NAME = 'default';

function refuseHostReservedDatasourceName(datasources: readonly { name?: unknown }[], ctx: z.RefinementCtx): void {
  datasources.forEach((datasource, index) => {
    if (datasource?.name !== HOST_RESERVED_DATASOURCE_NAME) return;
    ctx.addIssue({
      code: 'custom',
      path: [index, 'name'],
      message:
        `This stack declares a datasource named '${HOST_RESERVED_DATASOURCE_NAME}' — that name is reserved for ` +
        `the host's primary datasource, and every boot refuses a stack that declares it. To give the project ` +
        `its own primary database, set OS_DATABASE_URL and omit this entry. To add a datasource of the stack's ` +
        `own, declare it under another name (e.g. 'app_primary') and route objects to it explicitly (an ` +
        `object's \`datasource\`, or a \`datasourceMapping\` rule).`,
    });
  });
}

/**
 * Every metadata COLLECTION `ObjectStackDefinitionSchema` declares, as one
 * named shape.
 *
 * ## Why the collections are a const rather than written inline
 *
 * Two surfaces need this exact key set and must not be able to disagree about
 * it: the stack definition (spread in below) and {@link
 * AssembledPackageBodySchema}, the assembled form of ONE package inside a
 * release artifact (ADR-0130 D4). Declaring the collections twice is the drift
 * ADR-0116 exists about, and here it would be silent in the worst direction —
 * a metadata family added to the stack and forgotten on the package body would
 * make the load gate refuse every multi-package artifact that uses it, naming a
 * key its author correctly wrote.
 *
 * ⛔ The artifact ENVELOPE keys stay on the schema below and are deliberately
 * NOT in here: `manifest`, `packages`, `api`, `server`, `i18n`, `runtimeModule`
 * and `onEnable` describe the artifact or the deployment, not one package
 * inside it. `packages` additionally CANNOT live here — its element schema is
 * built from this shape, so putting it in the shape would make the declaration
 * circular.
 *
 * Three members of this shape are envelope keys as well: `plugins`,
 * `devPlugins` and `devLogins` are stack collections (they compose by
 * `concat`, so they live here), but they describe the BOOT rather than a
 * package's metadata — the first two are runtime ASSEMBLY instructions, the
 * third is what the development banner prints — and
 * {@link ASSEMBLED_PACKAGE_BODY_ENVELOPE_KEYS} keeps all three out of the
 * assembled package body (#15219, #17556 — {@link AssembledPackageBodyKey}
 * says why).
 *
 * @internal
 */
const STACK_DEFINITION_COLLECTIONS_SHAPE = {
  datasources: z.array(DatasourceSchema)
    .superRefine(refuseHostReservedDatasourceName)
    .optional()
    .describe('External Data Connections'),

  /**
   * Datasource Mapping Configuration
   *
   * Centralized routing rules that map packages, namespaces, or object patterns
   * to specific datasources. This eliminates the need to configure datasource
   * on every individual object.
   *
   * Rules are evaluated in order (or by priority if specified). First match wins.
   * If no match, falls back to object's explicit `datasource` field, then 'default'.
   *
   * @example
   * ```ts
   * datasourceMapping: [
   *   // System objects use Turso (persistent storage)
   *   { objectPattern: 'sys_*', datasource: 'turso' },
   *   { namespace: 'auth', datasource: 'turso' },
   *
   *   // CRM application uses Memory (dev/test)
   *   { namespace: 'crm', datasource: 'memory' },
   *   { package: 'com.example.crm', datasource: 'memory' },
   *
   *   // Temporary objects use Memory
   *   { objectPattern: 'temp_*', datasource: 'memory' },
   *
   *   // Default fallback
   *   { default: true, datasource: 'turso' },
   * ]
   * ```
   */
  datasourceMapping: z.array(DatasourceMappingRuleSchema).optional()
    .describe('Centralized datasource routing rules for packages/namespaces/objects'),

  translations: z.array(TranslationBundleSchema).optional().describe('I18n Translation Bundles'),
  i18n: TranslationConfigSchema.optional().describe('Internationalization configuration'),

  /** 
   * ObjectQL: Data Layer 
   * All business objects and entities.
   */
  objects: z.array(ObjectSchema).optional().describe('Business Objects definition (owned by this package)'),

  /**
   * Object Extensions: fields/config to merge into objects owned by other packages.
   * Use this instead of redefining an object when you want to add fields to
   * an existing object from another package.
   * 
   * @example
   * ```ts
   * objectExtensions: [{
   *   extend: 'contact',
   *   fields: { sales_stage: Field.select([...]) },
   * }]
   * ```
   */
  objectExtensions: z.array(ObjectExtensionSchema).optional().describe('Extensions to objects owned by other packages'),

  /**
   * Shared option lists (`data/picklist.zod.ts`): one list of select options
   * that fields on any object reference by name — `Field.select({ picklist:
   * 'industry' })` — instead of each field copying an `options` array.
   */
  picklists: z.array(PicklistSchema).optional().describe('Shared option lists that select fields reference by name'),

  /**
   * Picklist Extensions: options to ADD to picklists owned by other packages —
   * the `objectExtensions` idiom, additive only.
   *
   * @example
   * ```ts
   * picklistExtensions: [{
   *   extend: 'industry',
   *   options: [{ label: 'Healthcare', value: 'healthcare' }],
   * }]
   * ```
   */
  picklistExtensions: z.array(PicklistExtensionSchema).optional().describe('Options added to picklists owned by other packages (additive only)'),

  /** 
   * ObjectUI: User Interface Layer 
   * Apps, Menus, Pages, and Visualizations.
   */
  apps: z.array(AppSchema).optional().describe('Applications'),
  // #3464: the top-level `portals` collection was removed — PortalSchema was a
  // never-enforced, no-op projection (no dispatcher route family, auth scope,
  // LayoutDispatcher, NavigationBuilder or ThemeProvider ever consumed it).
  // Author external-user UI with apps/views + positions & permission sets.
  views: z.array(ViewSchema).optional().describe('List Views'),
  /**
   * [#5320] MACHINE-ASSEMBLED ONLY — not an authoring surface.
   *
   * Runtime-assembled manifests (`GET /packages/:id/export`, environment
   * artifact bundles) carry their non-container view artifacts — tenant-
   * authored standalone ViewItems, flattened overlays, expanded items a
   * travelling container cannot re-derive — under this key, judged by
   * `AssembledViewArtifactSchema` (`ui/assembled-views.zod.ts`). Authored
   * stack sources never write it: views are authored as `defineView`
   * containers in `views:`, and a standalone view is authored through the
   * metadata door (Studio / `PUT /api/v1/meta/view`), not in stack source.
   *
   * Declared here as an always-refusing key — the `retiredKey()` mechanism,
   * applied to a key that is machine-only rather than removed — for the same
   * reason the tombstones exist (#3855): this schema is not `.strict()`, so an
   * UNDECLARED `viewItems:` would be silently stripped and the author would
   * learn nothing. Declared-refusing, the mistake fails `tsc` (input type
   * `never`) and the parse refusal carries the prescription itself.
   */
  viewItems: z.never({
    error: () =>
      '`viewItems` is the machine-assembled channel for non-container view artifacts in '
      + 'runtime-assembled manifests (package export, environment artifacts) — it is not an '
      + 'authoring surface. Author views as `defineView` containers in `views:`; author a '
      + 'standalone view through the metadata door (Studio / `PUT /api/v1/meta/view`) instead '
      + 'of stack source.',
  }).optional().describe(
    '[MACHINE-ASSEMBLED] Non-container view artifacts of a runtime-assembled manifest '
    + '(standalone ViewItems, flattened overlays) — written by package export and artifact '
    + 'factories, refused in authored stack sources.',
  ),
  pages: z.array(PageSchema).optional().describe('Custom Pages'),
  dashboards: z.array(DashboardSchema).optional().describe('Dashboards'),
  reports: z.array(ReportSchema).optional().describe('Analytics Reports'),
  datasets: z.array(DatasetSchema).optional().describe('Analytics semantic-layer datasets (ADR-0021)'),
  /**
   * Registered actions — global (no `objectName`) and object-bound (`objectName`
   * set; `defineStack` merges those into the named object's `actions`).
   *
   * Uniqueness is per SCOPE, not per stack. The runtime registers and dispatches
   * every action under one exact-string key — the owning object's name (or
   * `'global'` for an object-less action), a colon, then the action name — with
   * no wildcard semantics, so `defineStack` refuses two declarations that
   * resolve to the same key: both written here, both on one object's `actions`,
   * or one in each position, byte-identical twins included (that case is a
   * delete, not a rename). An embedded action is keyed by the object it is
   * written ON — the declaration-resolution key `collectActionDeclarations` /
   * `resolveRouteActionDeclaration` use — not by its own `objectName` (the
   * registration key `collectBundleActions` / `standaloneActionOwnerKey` read).
   * One
   * global and one object-bound action MAY share a `name`: they occupy two
   * keys, and a by-name reader on the object's route resolves the object's own
   * `actions` (embedded, or merged in from here) before a standalone global
   * declaration.
   */
  actions: z.array(ActionSchema).optional().describe(
    'Global and Object Actions. Unique per scope, not per stack: the runtime keys every action by '
    + "its owning object's name (or 'global' when object-less), a colon, then the action name, and "
    + 'defineStack refuses two declarations that resolve to one key — both here, both on one '
    + "object's actions, or one in each position, identical twins included (an embedded action is keyed "
    + 'by the object it is written on, not by its own objectName). '
    + "One global and one object-bound action may share "
    + "a name; on that object's route the object's own actions take precedence for by-name readers. "
    + 'composeStacks runs the same key rule across its input stacks (counting distinct stacks, not sites) '
    + 'and names both source stacks on a collision.',
  ),
  // `themes` was REMOVED in 17.1 (commit 35ad101bc, ADR-0049 enforce-or-remove — ruled
  // 退役授权面, 2026-08-21). The pipeline was live from authoring gate through
  // artifact ingest and stopped there: no framework package ever read the
  // stored items, `theme` was never a registered metadata type, no first-party
  // app mounted the spec-aware provider, and nothing selected a theme — an
  // authored theme shipped green and changed nothing. `app.branding` is the
  // one colour surface. The unknown-key rejection carries the prescription via
  // the `guidance` entry on this schema's `strictObject` options; the D3
  // semantic entry `stack-themes-carrier-retired` carries it to upgraders.

  /**
   * ObjectFlow: Automation Layer
   * Business logic, approvals, and flows.
   *
   * ADR-0019: approvals are no longer a top-level collection — an approval is
   * authored as a flow with one or more Approval nodes, so it lives in `flows`.
   * ADR-0020: there is no top-level `workflows` collection — record state
   * machines are a `state_machine` validation rule on each object.
   */
  flows: z.array(FlowSchema).optional().describe('Screen Flows'),
  jobs: z.array(JobSchema).optional().describe('Background / Scheduled Jobs (run by IJobService on cron/interval/once schedules)'),
  emailTemplates: z.array(EmailTemplateDefinitionSchema).optional().describe('Email Templates resolved by IEmailService.sendTemplate({ template, locale })'),
  docs: z.array(DocSchema).optional().describe('Package documentation — flat Markdown items compiled from src/docs/*.md (ADR-0046)'),
  books: z.array(BookSchema).optional().describe('Documentation navigation spines — ordered groups with derived membership (ADR-0046 §6)'),

  /**
   * ObjectGuard: Security Layer
   */
  positions: z.array(PositionSchema).optional().describe('Positions — flat capability-distribution groups (ADR-0090 D3)'),
  /**
   * Permission Sets — the ADR-0090 app-category collection.
   *
   * ⚠️ **`permissions` is one key with two incompatible readings**, and this is
   * the collection half. The other half is
   * `ManifestSchema.permissions` (`kernel/manifest.zod.ts`): at the AUTHORING
   * stage the same key is the ADR-0025 §3.2 capability GRANT a plugin requests
   * (`{ services, hooks, network, fs }`; its legacy flat `string[]` form is
   * retired). When a stack is
   * assembled, the flatten order puts this collection on top — the stage table
   * at {@link AssembledPackageBodySchema} states that precedence — so a
   * manifest-stage `permissions` has no expression in an assembled body, and
   * writing permission sets on the manifest instead of here reaches no reader.
   *
   * Both readings land in the SAME registry slot: `SchemaRegistry.installPackage`
   * records `manifest.permissions` whichever stage produced it, so a consumer
   * reading it off an installed-package row must name the stage it wants and
   * report the other rather than dropping it silently.
   */
  permissions: z.array(PermissionSetSchema).optional().describe('Permission Sets — the ADR-0090 collection half of `permissions`; at the manifest/authoring stage the same key is the ADR-0025 capability grant instead (`ManifestSchema.permissions`)'),
  /**
   * [ADR-0066 D1] Authorization capabilities this package DEFINES.
   *
   * The formal, EXPLICIT declaration entry point (`defineCapability`) — the
   * package-side counterpart of the curated platform capabilities. Each entry
   * is seeded into `sys_capability` at boot with `managed_by:'package'` +
   * `package_id` provenance, instead of being implicitly derived (untitled)
   * from whatever a permission set references in `systemPermissions[]`.
   *
   * NOT to be confused with `requires` (platform SERVICE capabilities like
   * `ai`/`automation`) nor the runtime `ObjectStackCapabilities` descriptor —
   * these are authorization capabilities in the ADR-0066 sense (referenced by
   * `requiredPermissions` / granted by `systemPermissions`).
   */
  capabilities: z.array(CapabilityDeclarationSchema).optional()
    .describe('[ADR-0066 D1] Authorization capabilities this package defines (seeded with package provenance)'),
  sharingRules: z.array(SharingRuleSchema).optional().describe('Record Sharing Rules'),
  /**
   * [ADR-0142 D1] Ownership queues this package DECLARES — named sets of
   * people records can sit in until one of them claims the record. A declared
   * queue's members name positions only; an organization staffs its own queues
   * as `sys_queue` rows in Setup. Served from the registry, never copied into
   * rows, and switched off through the activation ledger.
   *
   * A composition that declares queues must register the ownership-queue
   * service (`@objectstack/plugin-sharing`): without it nothing resolves the
   * names, so the boot is refused rather than served with inert queues.
   */
  queues: z.array(QueueSchema).optional()
    .describe('[ADR-0142 D1] Ownership queues — named sets of people records can sit in until a member claims them'),
  /**
   * [ADR-0142 D5] Assignment rules this package DECLARES: per object, ordered
   * entries routing an inserted, still-ownerless row to a queue (parked, or
   * given to one member by `round_robin` / `least_loaded`) or to one user.
   * Evaluated by the engine once per insert, after every `beforeInsert` hook;
   * never on update. Requires the ownership-queue service, as `queues` does.
   */
  assignmentRules: z.array(AssignmentRuleSchema).optional()
    .describe('[ADR-0142 D5] Assignment rules — route new ownerless records to a queue or a person, once, on insert'),

  /**
   * ObjectAPI: API Layer — the platform's OUTWARD integration face.
   *
   * ⚠️ **Declared endpoints are LIVE from protocol 17** (#5040). Between #4936
   * and the executor landing, a non-empty `apis:` was refused wholesale because
   * nothing executed it; that refusal is now narrowed to a per-endpoint gate,
   * and an endpoint that passes it **serves requests as soon as it is
   * published**. Read `authRequired: false` on any entry as what it is: an
   * anonymous, internet-reachable execution entry point (ADR-0121 D6 makes an
   * armed `rateLimit` its paired obligation).
   *
   * Each entry must satisfy every gate below or publish/validate fails naming
   * that endpoint and that key — the runtime executes exactly the set that
   * passes, so `declared = enforced` holds in both directions:
   *
   *  1. **Namespace** (ADR-0121 D1/D2) — `path` must be
   *     `/api/v1/apps/<manifest.namespace>/<subpath>`. No built-in domain lives
   *     under `apps/`, and two packages cannot collide because their namespaces
   *     differ, so route ownership is structural rather than a maintained list.
   *  2. **Supported subset** — only `object_operation` (with both
   *     `objectParams.object` and `.operation`) and `flow` (with a `target`)
   *     execute in 17.x; `script` and `proxy` are refused pending their own
   *     rulings, and mapping `transform` is refused because no transformation
   *     registry exists.
   *  3. **Policy** — `authRequired: false` requires `rateLimit.enabled: true`;
   *     an armed budget must be usable; `cacheTtl` must be non-negative and
   *     GET-only.
   *  4. **Uniqueness** — one claim per METHOD + path inside a stack.
   *
   * Which channel: a caller INSIDE the platform (a session, the UI, AI/MCP, the
   * SDK) invokes an `action`; a caller OUTSIDE it (a partner system, an
   * inbound webhook) reaches an `apis:` endpoint (ADR-0121 D3).
   */
  apis: z.array(ApiEndpointSchema)
    .optional()
    .describe('API Endpoints — declared endpoints are live from protocol 17; each is gated at publish (ADR-0121)'),
  webhooks: z.array(WebhookSchema).optional().describe('Outbound Webhooks'),

  /**
   * Server-facing API configuration read by `objectstack serve` / `dev` when
   * it mounts the REST + dispatcher plugins. Declared here (rather than only
   * consumed ad-hoc) so it SURVIVES `defineStack` strict parsing — an
   * undeclared key is silently stripped, which previously made these knobs a
   * no-op through the primary authoring path. Forwarded to the REST plugin as
   * `api.api.*`.
   */
  api: z.object({
    /**
     * [REMOVED in #3963] See `RestApiConfigSchema.requireAuth` — tombstoned for
     * the same reason: this block is not `.strict()`, so deleting the key would
     * silently strip it and the author's intent would vanish without a word.
     */
    requireAuth: retiredKey(
      '`api.requireAuth` was removed in @objectstack/spec 17. Anonymous access to object data '
      + 'is now always denied. Delete the key; publish public surfaces by declaration instead — a public '
      + "form view, a share link, or `book.audience: 'public'`. A stack that mounts no auth at all now "
      + 'fails at boot rather than silently serving object data to anonymous callers. '
      + 'This edit left `os migrate meta` with the protocol-16.x conversions: apply it by hand, or run the tool on a release that still carries the conversion — https://objectstack.ai/docs/protocol-upgrade.',
    ),
    /** Enable environment-scoped routing for data/meta/AI APIs. */
    enableProjectScoping: z.boolean().optional(),
    /** Environment id resolution strategy when scoping is on. */
    projectResolution: z.enum(['required', 'optional', 'auto']).optional(),
    /** Per-environment membership 403 gate (dispatcher). Undefined → default. */
    enforceProjectMembership: z.boolean().optional(),
  }).optional().describe('Server-facing API config consumed by objectstack serve/dev'),

  /**
   * Server-level runtime configuration read by `objectstack serve` / `dev`.
   *
   * DELIBERATELY NARROW (#4910): it carries only keys an executor consumes —
   * today `security.rateLimit` (the inbound token bucket that answers 429) and
   * `trustProxy` (how that limiter identifies a caller). It is NOT the former
   * nine-key `HttpServerConfigSchema`: seven of those keys had no reader and no
   * authoring surface, and mounting them here would have made dead keys
   * writable — so they were retired with their container instead (#4938,
   * ADR-0049). Port/host stay a deployment concern owned by
   * `objectstack serve -p`; see the schema file for the precedence rule, the
   * per-key prescriptions and the rest of the rationale.
   */
  server: StackServerConfigSchema.optional()
    .describe('Server-level runtime config consumed by objectstack serve/dev (inbound rate limit, proxy trust)'),

  /**
   * The deployment's product name — the bottom configured rung of the chain
   * `resolveDeploymentAppName` (`@objectstack/plugin-email`) reads:
   * `OS_APP_NAME` > `email.appName` > `email.defaultTemplateContext.appName` >
   * this > `'ObjectStack'`. `objectstack serve` hands the result to the email
   * templates (`{{appName}}`) and to AuthPlugin (its emails and the TOTP
   * issuer); `bootStack` reads it through the same function.
   */
  appName: z.string().optional()
    .describe(
      'Deployment product name for email templates and AuthPlugin — OS_APP_NAME env wins, then email.appName, '
      + 'then email.defaultTemplateContext.appName, then this, then "ObjectStack"',
    ),

  /**
   * Outbound mail configuration — {@link StackEmailConfigSchema}: the
   * non-secret members of `EmailServiceConfigSchema`, read by
   * `resolveEmailCapabilityArg` when `objectstack serve` / `bootStack`
   * construct the email provider. `OS_EMAIL_*` overrides it per key, and the
   * credentials (`apiKey`, the SMTP `options.password`) are refused here by
   * name — they are environment-only, because this definition is compiled
   * into the published artifact.
   */
  email: StackEmailConfigSchema.optional()
    .describe(
      'Outbound mail configuration (non-secret members of EmailServiceConfig; OS_EMAIL_* env overrides per key). '
      + 'Credentials are environment-only: OS_EMAIL_API_KEY, OS_EMAIL_SMTP_PASSWORD',
    ),

  /**
   * SMS configuration — {@link StackSmsConfigSchema}: `retries`, the one
   * member `resolveSmsCapabilityArg` reads that a stack can deliver. The
   * provider and its credentials (`provider`, `providerOptions`) are refused
   * here by name: the delivering transport is built by the `sms` settings
   * namespace from its own settings and their `OS_SMS_*` environment overrides.
   */
  sms: StackSmsConfigSchema.optional()
    .describe(
      'SMS configuration — retries only. The provider and its credentials are not authorable here: '
      + 'Setup → Settings → SMS Delivery, or OS_SMS_PROVIDER and the other OS_SMS_* env overrides',
    ),

  /**
   * ObjectAI: Artificial Intelligence Layer
   *
   * Three-tier composition (Agent → Skill → Tool) aligned with Salesforce
   * Agentforce Topics, Microsoft Copilot Studio Topics, and ServiceNow Now
   * Assist Skills. Per ADR-0063, **skills (+ tools / MCP) are the only
   * third-party extension primitive**:
   *
   * - **agents**: PLATFORM-INTERNAL (ADR-0063 §2). The kernel ships exactly
   *   two agents — `ask` (data product) and `build` (authoring product) —
   *   bound by surface, never picked from a roster. Tenant/app-package custom
   *   agents were withdrawn (ADR-0040 §3 reversed): an agent declared here
   *   parses, but the runtime catalog filters non-platform agent records, so
   *   it is not a supported extension surface. Author skills instead.
   * - **skills**: Reusable capability bundles ("topics" in Salesforce
   *   parlance) — THE extension primitive. Each skill groups related tools,
   *   declares its agent surface affinity (`'ask' | 'build' | 'both'`,
   *   ADR-0063 §3 — checked by lint, enforced at load) and `triggerConditions`
   *   (an AND of context field/operator/value) for context-aware activation.
   *   Activation is that intersected with the agent's own skill allowlist —
   *   there is no phrase list: `triggerPhrases` was retired in #3896 because
   *   phrases were never matched against the user's message, and the key is now
   *   a `retiredKey()` tombstone that rejects on parse. Natural-language intent
   *   belongs in `description` / `instructions`, where the LLM reads it.
   * - **tools**: OPTIONAL refinement layer, never required (ADR-0109). The
   *   default third-party path declares no tool records: a skill's `tools[]`
   *   names a platform-registered tool (`PLATFORM_PROVIDED_TOOL_NAMES`) or a
   *   tool the runtime materialises from the app's own declarative actions
   *   (`action_<name>`) — the executable, its authz and its audit stay on the
   *   action/flow the app already ships. A `stack.tools` record exists only
   *   for AI-presentation refinement (Phase 2: LLM description, parameter
   *   narrowing, flow exposure) and has no runtime reader until that lands.
   */
  agents: z.array(AgentSchema).optional().describe('AI Agents — platform-internal (ADR-0063 §2): the kernel ships exactly two (ask/build); third parties extend via skills, not agents'),
  tools: z.array(ToolSchema).optional().describe('AI Tool metadata records — optional refinement layer, never required: the default path is skills referencing platform tools or materialised action_<name> tools (ADR-0109)'),
  skills: z.array(SkillSchema).optional().describe('AI Skills (reusable capability bundles — the third-party AI extension primitive, ADR-0063)'),

  /**
   * ObjectQL: Data Extensions
   * Hooks, mappings, and analytics cubes.
   */
  hooks: z.array(HookSchema).optional().describe('Object Lifecycle Hooks'),
  /**
   * Named handler functions for declarative metadata that references
   * handlers by string name (`Hook.handler: 'my_handler'`,
   * `Action.target: 'my_handler'`, a `script` node's `config.function`).
   * Two accepted shapes:
   *
   *   - Map form (preferred): `{ my_handler: (ctx) => {...} }`
   *   - Array form: `[{ name: 'my_handler', handler: (ctx) => {...} }]`
   *
   * Either shape may state what the function DOES instead of just naming it
   * (#4396) — `{ my_handler: { handler, effect: 'writes' } }`, or `effect` on
   * an array entry. A `script` node's function is contractually pure (it
   * returns a value; the flow graph persists it), and the run summary counts on
   * that: an undeclared function is counted as having written nothing. A
   * function that legitimately writes declares `effect: 'writes'` and its step
   * is reported as an effect the platform cannot count, rather than as none.
   * See `FlowFunctionEffectSchema` in `@objectstack/spec/automation`.
   *
   * The CALLABLE lives in code only — `objectstack build` lowers it to a
   * handler ref and carries the function itself in the sibling runtime module
   * (what it declared rides along in the artifact and is re-attached on load).
   * The `AppPlugin` registers them on the engine before binding hooks so
   * `string` handlers resolve at startup.
   *
   * BOTH shapes therefore reach this schema twice: once as authored, once
   * lowered. All four combinations (map/array × bare/declared) are accepted —
   * the map's two lowered forms since #4343 and #4976, the array's since commit c8d6f6e08.
   * `packages/cli`'s `lower-callables.test.ts` pins every cell against what the
   * lowering actually emits, rather than against a belief about it.
   */
  functions: z.union([
    z.record(z.string(), FlowFunctionEntrySchema),
    // The array member is NOT `FlowFunctionEntrySchema` in a list: an array
    // entry carries its own `name` (and an optional `packageId`) because it has
    // no map key to be named by, so the two shapes are genuinely different
    // records rather than one reused schema.
    //
    // `handler` accepts the lowered string ref for the same reason the map form
    // does (#4343, #4976), and this member was the last place it did not:
    // `lowerCallables` lowers the array branch too (`next.handler = ref`,
    // `next.name = ref`), so `objectstack build` emitted
    // `[{ name: 'syncBilling', handler: 'syncBilling', effect: 'writes' }]` into
    // a schema that still demanded a callable — `invalid_union: Invalid input`,
    // path stopping at `functions`, naming neither the entry nor the key. One
    // widening covers BOTH array spellings at once, unlike the map form's two
    // separate members: `effect` is already optional here, so the bare and the
    // declared entry differ only in whether that key is present.
    z.array(z.object({
      name: z.string(),
      handler: z.union([
        z.function(),
        z.string().min(1).describe('The lowered handler ref (built artifacts) — the callable rides in the sibling ESM module'),
      ]).describe('The function invoked by name — the authored callable, or the ref `objectstack build` lowered it to'),
      packageId: z.string().optional(),
      effect: FlowFunctionEffectSchema.optional(),
    })),
  ]).optional().describe('Named handler functions referenced by hooks/actions/script nodes (optionally declaring their effect)'),

  /**
   * App lifecycle hook the runtime EXECUTES off the authored bundle:
   * `AppPlugin` invokes it at `start()` with the host context (`ctx.ql`) —
   * the documented place to register action handlers and drivers
   * (`examples/app-todo` and `examples/app-showcase` both ship one).
   *
   * DECLARED since #8687 closed this schema against unknown keys. Before
   * that, `onEnable` was deliberately undeclared — the parse stripped it and
   * the runtime read it off the authored object — and the top-level lint
   * stayed quiet about it via `STACK_RUNTIME_MEMBERS` ("not declared" and
   * "dropped at load" are different claims). A strict close of an undeclared
   * `onEnable` would have refused the pattern our own examples ship, so the
   * key is now declared: `declared = honoured`, in both directions.
   *
   * A function still cannot survive `dist/objectstack.json` — on the
   * artifact-boot path the CLI grafts it back from the authored module
   * (#4095, `GRAFTABLE_RUNTIME_MEMBERS`, derived from
   * `STACK_RUNTIME_MEMBERS`).
   */
  onEnable: z.function().optional().describe('App lifecycle hook invoked by AppPlugin at start() with the host context (ctx.ql) — register action handlers and drivers here. Executed off the authored bundle; never serialized into the JSON artifact (grafts it back on artifact boot).'),
  mappings: z.array(MappingSchema).optional().describe('Data Import/Export Mappings'),
  analyticsCubes: z.array(CubeSchema).optional().describe('Analytics Semantic Layer Cubes'),

  /**
   * Integration Protocol — connectors are of two kinds (ADR-0097):
   *
   * 1. **Provider-bound instance** (has `provider`): a live, dispatchable
   *    connector authored as pure metadata. At boot the automation service looks
   *    up the installed generic executor named by `provider` (`openapi` / `mcp` /
   *    `rest`, contributed by the matching plugin in `plugins:`), resolves
   *    `auth.credentialRef` (an environment variable, the environment's
   *    connector credential store, or the host's resolver), and registers the
   *    materialized `{ def, handlers }` on the connector registry — so
   *    `connector_action` dispatches it and `GET /connectors` lists it, exactly
   *    like a hand-written connector. A declared `provider` with no installed
   *    factory is a **hard boot error**. A `credentialRef` nothing resolves, or
   *    one the upstream refuses, degrades that one instance until the
   *    credential is set; the boot goes on.
   *
   * 2. **Catalog descriptor** (no `provider`, the #2612 interim contract): an
   *    inert metadata entry for discovery / documentation / marketplace listing.
   *    It does NOT reach the connector registry; `connector_action` cannot
   *    dispatch it. The automation service audits these at boot — a descriptor
   *    with `actions` and no same-name runtime registration logs a loud warning;
   *    mark a deliberate catalog-only entry with `enabled: false` to silence it.
   *
   * Runtime connectors may also be contributed directly by plugins calling
   * `engine.registerConnector(def, handlers)` (ADR-0018 §Addendum). A
   * provider-bound instance whose `name` collides with such a plugin-registered
   * connector is a hard boot error (no silent precedence, ADR-0097 §4).
   */
  connectors: z.array(DeclarativeConnectorEntrySchema).optional().describe(
    'External System Connectors. A provider-bound entry (has `provider`: openapi/mcp/rest) is materialized into a ' +
    'live, dispatchable connector at boot and referenced by flows via `connector_action`; credentials are `auth.credentialRef` ' +
    'references, never inline secrets. An entry with no `provider` is a catalog descriptor only (NOT dispatchable) — set ' +
    '`enabled: false` on deliberate descriptors. Unknown provider / name conflict ⇒ hard boot error; a credentialRef nothing resolves, or one ' +
    'the upstream refuses, degrades that instance until the credential is set (ADR-0097).',
  ),

  /**
   * Data Seeding Protocol
   * 
   * Declarative seed data for bootstrapping, demos, and testing.
   * Each entry targets a specific object and provides records to load
   * using the specified conflict resolution strategy.
   * 
   * Uses the standard SeedSchema which supports:
   * - `externalId`: Idempotency key for upsert matching (default: 'name')
   * - `mode`: Conflict resolution (upsert, insert, ignore, replace)
   * - `env`: Environment scoping (prod, dev, test)
   * 
   * @example
   * ```ts
   * data: [
   *   {
   *     object: 'account',
   *     mode: 'upsert',
   *     externalId: 'name',
   *     records: [
   *       { name: 'Acme Corp', type: 'customer', industry: 'technology' },
   *     ]
   *   }
   * ]
   * ```
   */
  data: z.array(SeedSchema).optional().describe('Seed Data / Fixtures for bootstrapping'),

  /**
   * Plugins: External Capabilities
   * List of plugins to load. Can be a Manifest object, a package name string, or a Runtime Plugin instance.
   */
  plugins: z.array(z.unknown()).optional().describe('Plugins to load'),

  /**
   * Required Capabilities
   *
   * Declarative dependency on platform-provided capabilities. The
   * runtime resolves each name to a built-in service plugin and
   * loads it automatically — no need to construct the plugin in
   * `plugins[]` or pass `--preset` flags at the CLI level.
   *
   * Built-in capability names (mapped in `@objectstack/cli`):
   *   `ai`         → AIServicePlugin (`@objectstack/service-ai`)
   *   `ai-studio`  → AIStudioPlugin (`@objectstack/service-ai-studio`; implies `ai`)
   *   `automation` → AutomationServicePlugin (+ default node packs)
   *   `analytics`  → AnalyticsServicePlugin
   *   `audit`      → AuditPlugin
   *   `i18n`       → I18nPlugin
   *
   * INTENT, not presence (#1597). Listing a capability here is an explicit
   * declaration that this app REQUIRES it, so the platform resolves it
   * fail-fast at startup: if the provider package is not installed (or its
   * plugin throws while starting), boot ABORTS with a clear error instead of
   * silently degrading. This is the opposite of "load it if the package happens
   * to be installed" — a capability the app merely bundles but does NOT list
   * here is loaded best-effort (absent ⇒ quiet skip), and tier gating remains an
   * orthogonal deny (a capability whose tier is off never loads, whatever the
   * intent). Use this for the AI service too: `requires: ['ai']` makes a missing
   * `@objectstack/service-ai` a hard boot error rather than a broken-but-booted app.
   *
   * Tokens must be members of the platform vocabulary
   * (`PLATFORM_CAPABILITY_TOKENS`, canonical kebab-case). An UNKNOWN token — a
   * typo or stale reference no runtime provides — is a `defineStack` **error**,
   * not a silent no-op (framework#3265). The legacy camelCase spellings
   * `aiStudio`/`aiSeat` were deprecated aliases in the prior release and were
   * removed in framework#3308 — use `ai-studio`/`ai-seat`.
   *
   * If a capability is also provided explicitly via `plugins[]`, the
   * explicit instance wins (and the resolver does not double-register).
   *
   * @example
   * ```ts
   * defineStack({
   *   manifest: { ... },
   *   requires: ['ai', 'automation', 'analytics'],
   *   objects: [...],
   * });
   * ```
   */
  requires: z.array(z.string()).optional().describe('Capability names this stack requires from the platform (canonical kebab-case tokens from PLATFORM_CAPABILITY_TOKENS; an unknown token is a defineStack error, declared-but-missing ⇒ fail-fast at startup)'),

  /**
   * Plugin tier presets to auto-register (e.g. `core`, `ai`, `ui`, `auth`).
   * Overrides the `--preset` flag; omit to use the preset default. Set a list
   * WITHOUT `ai` to run without the AI service (Community-Edition deployments).
   */
  tiers: z.array(z.string()).optional().describe('Plugin tier presets to enable; overrides --preset'),

  /**
   * DevPlugins: Development Capabilities
   * List of plugins to load ONLY in development environment.
   * Equivalent to `devDependencies` in package.json.
   * Useful for loading dev-tools, mock data generators, or referencing local sibling packages for debugging.
   */
  devPlugins: z.array(z.union([ManifestSchema, z.string()])).optional().describe('Plugins to load only in development (CLI dev command)'),

  /**
   * DevHint: One Sentence For The First-Run Operator
   *
   * Free-form text the development boot banner prints under the credential
   * block — the channel for what {@link DevLoginSchema} cannot express: "run
   * `pnpm seed:demo` first", "sign in with SSO against the local IdP", "the
   * Hiring group needs a position, see README".
   *
   * Composes as `'single'`: two stacks declaring DIFFERENT hints is a
   * composition ERROR naming both, never a silent last-wins — the same rule
   * `api` / `server` / `i18n` carry, for the same reason (an application's
   * first-run instruction is not a detail a composer may pick for the author).
   *
   * Read only on a development boot; a production boot prints nothing.
   */
  devHint: z.string().optional().describe('One sentence the development boot banner prints under the credential block (dev only)'),

  /**
   * DevLogins: First-Run Credentials The Application Contributes
   *
   * The accounts an operator should actually sign in with on this application,
   * printed beneath the platform's own seeded dev admin (#17556). See
   * {@link DevLoginSchema} for what one entry means — in particular that it
   * CREATES NOTHING and grants nothing; it names accounts the application seeds
   * by other means so the banner can point at one that shows something.
   *
   * ADDITIVE, never a replacement: the seeded-admin line still prints, because
   * that account exists whether or not the application mentions it and an
   * application-controlled key must not be able to suppress a platform
   * disclosure.
   *
   * Composes as `'concat'`: composing two applications yields BOTH publishers'
   * personas, since dropping one would hide an audience the composed artifact
   * still serves. An artifact ENVELOPE key like `plugins` / `devPlugins` — the
   * banner reads it off the top level, so it stays there rather than being
   * folded into an assembled package body where nothing would read it.
   *
   * Read only on a development boot; a production boot prints nothing.
   */
  devLogins: z.array(DevLoginSchema).optional().describe('First-run credentials the application contributes to the development boot banner (dev only)'),

  /**
   * DemoStaff: The Demo Accounts This Application's Seed Data Is Dealt To
   *
   * The people the application's demo `data` names as record owners. See
   * {@link DemoStaffSchema} for what one entry means. Unlike `devLogins`, an
   * entry here DOES create an account that can sign in — which is exactly why
   * the key is development-only end to end:
   *
   * - `os build` writes no `demoStaff` into the artifact
   *   (`objectstack.json`), so a deployment booted from one has none to
   *   provision;
   * - `@objectstack/plugin-auth` provisions the accounts only on a local
   *   development boot (`os dev`), after the development admin, and a boot
   *   that is not one creates nothing and says why.
   *
   * Composes as `'concat'`: composing two applications provisions both
   * publishers' demo accounts. Names and addresses stay unique across the
   * composed list (a cross-reference error names both entries), and every
   * `position` / `permissionSets` entry must name one the stack declares. An
   * artifact ENVELOPE key like `devLogins`: its one reader takes it off the top
   * level of the definition the boot loaded, so it is never folded into an
   * assembled package body.
   */
  demoStaff: z.array(DemoStaffSchema).optional().describe('Demo accounts the development boot creates for the seed data to be dealt to (dev only, never in the built objectstack.json)'),

  /**
   * Compiled Runtime Bundle Reference
   *
   * Path (relative to the JSON artifact) to a sibling ESM module emitted
   * by `objectstack build`. The module exports `{ functions: Record<string, Function> }`
   * containing every inline `Hook.handler` (and top-level `functions` map
   * entry) that was lowered to a string ref during compilation.
   *
   * Runtimes (StandaloneStack, multi-tenant artifact-bind path) MUST
   * dynamic-import this file on boot and merge `module.functions` into
   * `bundle.functions` before `bindHooks(...)` runs — otherwise every
   * declarative hook will fail to resolve its handler.
   *
   * The two-product layout (JSON + ESM) is the canonical build artifact
   * shape for the platform. Authoring tools (`defineStack`, Studio
   * inline editor) must NOT set this field directly; it is populated
   * exclusively by the compiler.
   *
   * @example "./objectstack-runtime.7a70cd6576d17ff6.mjs"
   */
  runtimeModule: z.string().optional().describe('Path (relative to the artifact JSON) of the compiled runtime ESM bundle. Set by `objectstack build`; do not author by hand.'),
};


/**
 * How {@link composeStacks} treats one top-level key of the artifact envelope
 * (#5005) — the value half of {@link COMPOSE_KEY_DISPOSITIONS}.
 *
 * - `'concat'`    — an array collection; the inputs' arrays are concatenated
 *                   in stack order. Every metadata collection (`objects` aside)
 *                   and the envelope's `packages` / `requires` lists compose
 *                   this way, so a downstream seam that merges N artifacts may
 *                   concatenate a `'concat'` key without reading its element
 *                   type.
 * - `'single'`    — one scalar/object configuration value; identical
 *                   declarations pass through, differing ones are a
 *                   composition ERROR naming the key and both stacks (never
 *                   last-wins, never deep-merge).
 * - `'manifest'`  — the singular package identity; picked by the `manifest`
 *                   option (`'first'` / `'last'` / index, or folded into
 *                   `packages` under `'preserve'`).
 * - `'objects'`   — merged per object name by the `objectConflict` strategy.
 * - `'functions'` — a named-handler map; merged by handler name, a duplicate
 *                   name is an ERROR.
 */
export type ComposeDisposition = 'concat' | 'single' | 'manifest' | 'objects' | 'functions';

/**
 * Every top-level key {@link ObjectStackDefinitionSchema} declares — the
 * artifact envelope's key set: the two envelope-only keys (`manifest`,
 * `packages`) plus every member of the collections shape. The key half of
 * {@link COMPOSE_KEY_DISPOSITIONS}; {@link STACK_DEFINITION_KEYS} is its
 * runtime value.
 */
export type StackDefinitionKey = 'manifest' | 'packages' | keyof typeof STACK_DEFINITION_COLLECTIONS_SHAPE;

/**
 * The composition rule for EVERY top-level key of `ObjectStackDefinition`
 * (#5005) — and, since #14877, THE exported source of the artifact envelope's
 * top-level key set.
 *
 * ## Exported, frozen: derive from it, never copy it (#14877)
 *
 * A downstream seam that walks an artifact's top level — a hosted publish, an
 * artifact merge, an assembler — needs two answers: *which keys exist* and
 * *what composing each one means*. The collection half of the first answer
 * was already derivable (`PLURAL_TO_SINGULAR`, `METADATA_ALIASES`); the rest
 * (`manifest`, `requires`, `packages`, …) had to be hand-copied per consumer,
 * and the copy drifted silently twice (cloud#897: `roles` → `positions` dropped
 * every hosted `positions[]`; cloud#1888: an artifact merge dropped
 * `packages[]`). So this table is public: read its keys for the key set
 * ({@link STACK_DEFINITION_KEYS} is that derivation, done once), and index it
 * for the rule (`COMPOSE_KEY_DISPOSITIONS[key] === 'concat'` is the question
 * "may I concatenate this across artifacts?"). A key added to the schema
 * reaches every deriving consumer the day it lands — a copy would not.
 *
 * It is `Object.freeze`d: the contract is read-only, and a consumer cannot
 * widen or retarget it by assignment. It is literal-typed (`as const`), so
 * `(typeof COMPOSE_KEY_DISPOSITIONS)[K]` is K's disposition rather than the
 * union — the derivations below depend on that. The pin
 * `compose-key-dispositions-export.pin.test.ts` holds this key set equal to
 * `ObjectStackDefinitionSchema`'s shape in both directions, so the table cannot
 * drift from the schema without a red test naming the key.
 *
 * ## Why a total table and not a list
 *
 * `composeStacks` used to build its result from an empty object by filling in
 * `manifest`, `i18n`, `objects` and a hand-maintained array whitelist. Anything
 * absent from that whitelist was not "left alone" — it was **deleted**, with no
 * error, no warning, and no way for a consumer to tell "the composer dropped it"
 * apart from "the author never wrote it". Composition is the platform's
 * app-packaging / install story, so that silence reached real security config:
 * `api.enforceProjectMembership` (the per-environment 403 gate) and, as of
 * #4910, `server.security.rateLimit` both vanished the moment a stack was
 * composed with any other one. Seven declared array collections
 * (`datasourceMapping`, `datasets`, `jobs`, `emailTemplates`, `docs`, `books`,
 * `tiers`) and the whole `functions` handler map went the same way; `tools`
 * escaped the same fate only because ADR-0109 noticed and patched the list.
 *
 * A whitelist makes forgetting the default. This table makes it a **type
 * error**: it `satisfies Record<StackDefinitionKey, …>` — the stack schema's
 * own declared key set, read off `STACK_DEFINITION_COLLECTIONS_SHAPE` plus the
 * two envelope keys — so a new top-level key does not compile until someone
 * states what composing it means. It is additionally `as const`, because
 * {@link AssembledPackageBodyKey} derives the assembled package body's key set
 * from these literal dispositions rather than transcribing them. That is
 * the structural half of the fix; {@link composeStacks} carries the runtime
 * half (an undeclared key warns rather than disappearing), so a key that
 * reaches composition without a rule — via `strict: false`, or a raw object —
 * still reports itself.
 *
 * ## Note on `i18n` (#5051)
 *
 * `i18n` carried a last-wins of its own through #5005 — the one key here that
 * already had a deliberate, working strategy, and #5005's subject was keys that
 * got *dropped*. That left it as the only top-level key still resolving a
 * disagreement by silent override: the very shape the maintainer rejected for
 * `api`/`server` — an earlier stack's declaration overwritten without a word by
 * whoever composes after it. #5051 closed the inconsistency — `i18n` is
 * `'single'` like every other non-array configuration key. Which locales an
 * application supports is not a detail a composer may pick for the author: the
 * `translations` bundles each stack ships are written against its own
 * `supportedLocales`, so overriding one stack's declaration leaves the other
 * stack's bundles addressing locales the composed app no longer admits.
 */
export const COMPOSE_KEY_DISPOSITIONS = Object.freeze({
  // ── Bespoke strategies (unchanged by #5005) ──
  manifest: 'manifest',
  objects: 'objects',
  functions: 'functions',

  // ── Array collections — concatenated in stack order ──
  // ADR-0130 D4's artifact package list. Not a metadata collection like the
  // rest of this block — it carries package MANIFESTS, not authored metadata —
  // but its composition rule is the same one for the same reason: composing two
  // stacks that each carry package entries must yield BOTH publishers' entries,
  // since dropping one would lose a package the composed artifact still
  // delivers. Declared here in the change that declares the key, as the table's
  // docblock requires.
  //
  // ⚠️ This disposition governs stacks that already CARRY a `packages` list.
  // It does not, on its own, repair `manifest:`'s deliberate pick-one semantics
  // above (`selectManifest`, first/last): two stacks that each declare only the
  // SINGULAR `manifest` would still lose N−1 of them. Folding those in is the
  // `manifest: 'preserve'` option (ADR-0130 follow-up row 3), which is opt-in
  // and composes `packages` itself — see `preservePackageEntries`. Concat stays
  // the rule for every other strategy, and preserve's own output concatenates
  // in stack order too, so the two agree rather than compete.
  packages: 'concat',
  datasources: 'concat',
  datasourceMapping: 'concat',
  translations: 'concat',
  objectExtensions: 'concat',
  picklists: 'concat',
  picklistExtensions: 'concat',
  apps: 'concat',
  views: 'concat',
  // [#5320] Machine-assembled channel (never authorable — the schema types it
  // `never`, so no authored stack reaches composition carrying it). Assembled
  // manifests are not `composeStacks` inputs today; if two ever were, their
  // non-container view artifacts would concatenate like every other collection.
  viewItems: 'concat',
  pages: 'concat',
  dashboards: 'concat',
  reports: 'concat',
  datasets: 'concat',
  actions: 'concat',
  // `themes` left this table with the key (commit 35ad101bc) — the total-record type is
  // what forces this comment to move in lockstep with the schema.
  flows: 'concat',
  jobs: 'concat',
  emailTemplates: 'concat',
  docs: 'concat',
  books: 'concat',
  positions: 'concat',
  permissions: 'concat',
  capabilities: 'concat',
  sharingRules: 'concat',
  queues: 'concat',
  assignmentRules: 'concat',
  apis: 'concat',
  webhooks: 'concat',
  agents: 'concat',
  tools: 'concat',
  skills: 'concat',
  hooks: 'concat',
  mappings: 'concat',
  analyticsCubes: 'concat',
  connectors: 'concat',
  data: 'concat',
  plugins: 'concat',
  requires: 'concat',
  tiers: 'concat',
  devPlugins: 'concat',
  // #17556 — BOTH publishers' personas survive a compose, for the reason
  // `packages` concatenates: dropping one would hide an audience the composed
  // artifact still serves. `devHint` is the scalar half and is `'single'` below.
  devLogins: 'concat',
  // Both applications' demo accounts are provisioned after a compose; the
  // cross-reference pass keeps names and addresses unique across the result.
  demoStaff: 'concat',

  // ── Single-valued configuration — same value passes, difference throws ──
  api: 'single',
  server: 'single',
  runtimeModule: 'single',
  // #17556 — two stacks declaring different first-run instructions is a
  // conflict to name, not a last-wins to resolve behind the authors' backs.
  devHint: 'single',
  // #8687: declared alongside the strict close (it was undeclared-but-honoured
  // before, so composition never saw it through a parsed stack). One bundle
  // gets one `onEnable` (`AppPlugin` invokes a single hook at start()); two
  // stacks shipping DIFFERENT hooks cannot be merged without inventing an
  // execution order neither author wrote — refuse and name them, like
  // `api`/`server`. Multi-app hosts keep per-app hooks by composing PLUGINS
  // (each AppPlugin carries its own bundle), not by folding stacks into one.
  onEnable: 'single',
  // #5051: the last key still on last-wins; aligned here, see the note above.
  i18n: 'single',
  // Deployment configuration the boot reads off the top level — one product
  // name, one mail configuration and one SMS configuration per booted stack,
  // so two stacks declaring different ones is a conflict to name, like
  // `api` / `server`.
  appName: 'single',
  email: 'single',
  sms: 'single',
} as const satisfies Record<StackDefinitionKey, ComposeDisposition>);

/**
 * The artifact envelope's top-level key set — every key
 * {@link ObjectStackDefinitionSchema} declares — as a frozen list (#14877).
 *
 * DERIVED from {@link COMPOSE_KEY_DISPOSITIONS} by `Object.keys`, never a
 * second literal: the table is total over the schema's declared keys, so this
 * list is too, and a consumer that iterates it sees a new top-level key the
 * day the schema declares one. Read it where a seam needs "the keys an
 * artifact may carry" without caring what composing each one means; index the
 * table where it does.
 */
export const STACK_DEFINITION_KEYS: readonly StackDefinitionKey[] = Object.freeze(
  Object.keys(COMPOSE_KEY_DISPOSITIONS) as StackDefinitionKey[],
);

/**
 * All array fields on `ObjectStackDefinition` that are simply concatenated.
 * Derived from {@link COMPOSE_KEY_DISPOSITIONS} so the two cannot drift.
 * @internal
 */
const CONCAT_ARRAY_FIELDS = STACK_DEFINITION_KEYS
  .filter((key) => COMPOSE_KEY_DISPOSITIONS[key] === 'concat');


/**
 * The keys an ASSEMBLED package body carries beyond its manifest fields.
 *
 * DERIVED from {@link COMPOSE_KEY_DISPOSITIONS}, never transcribed: that table
 * is total over the stack schema's declared keys, so a metadata family added to
 * the stack arrives here without anyone remembering to add it. Transcribing the
 * list instead would fail SILENTLY and in the worst direction — the load gate
 * would refuse a multi-package artifact naming a key its author correctly
 * wrote, and the refusal would look like a defect in the author's metadata.
 *
 * Five `concat` keys are excluded — the artifact ENVELOPE keys, declared once
 * in {@link ASSEMBLED_PACKAGE_BODY_ENVELOPE_KEYS} for this type and the runtime
 * shape alike:
 *
 * - `packages`: an artifact carries packages, a package inside it does not
 *   carry packages of its own (ADR-0130 D1 — the artifact is the co-ownership
 *   boundary, and nesting would put a second boundary inside the first).
 * - `plugins` / `devPlugins`: runtime ASSEMBLY instructions, not metadata
 *   (#15219, maintainer ruling A for both keys, 2026-09-04). `plugins` holds
 *   what a host hands to `kernel.use()` — live plugin instances, manifests or
 *   package names (`z.array(z.unknown())`) — and `devPlugins` is the `os dev`
 *   load list. An artifact is inert JSON: a plugin written inside
 *   `packages[i].manifest` could never be constructed by a loader, so a reader
 *   that resolved it there would register garbage where it used to skip in
 *   silence. An artifact carries metadata; a host assembles plugins — at the top
 *   level, where `composeStacks` still concatenates them (`concat` stays, for
 *   in-memory composition) and where `os serve` / `os migrate` read them.
 *   Inside a body both are refused by the manifest's strict close, naming the
 *   key.
 * - `devLogins`: what the DEVELOPMENT BOOT BANNER prints (#17556), not metadata
 *   a package registers. Its one reader is the CLI, which reads it off the top
 *   level of the definition it booted, so an entry folded into
 *   `packages[i].manifest` would be parsed, stored and never printed — the
 *   declared-but-unread shape ADR-0049 exists about. Excluded for the same
 *   reason `plugins` is, one layer over: the artifact is inert JSON describing
 *   an application, and which account an operator should sign in with is a
 *   property of the BOOT, not of a package inside it. `concat` stays at the top
 *   level, where composing two applications keeps both publishers' personas.
 * - `demoStaff`: the demo accounts a DEVELOPMENT boot creates, for the same
 *   reason as `devLogins`, and one more: `os build` leaves the key out of the
 *   artifact it writes, so a body could only ever carry it by hand — and its one
 *   reader, the boot that hands it to `@objectstack/plugin-auth`, reads the top
 *   level of the definition it loaded.
 *
 * @internal
 */
type AssembledPackageBodyKey = Exclude<{
  [K in keyof typeof COMPOSE_KEY_DISPOSITIONS]:
    (typeof COMPOSE_KEY_DISPOSITIONS)[K] extends 'concat' | 'objects' | 'functions' ? K : never;
}[keyof typeof COMPOSE_KEY_DISPOSITIONS], AssembledPackageBodyEnvelopeKey>;

/**
 * The `concat` keys of {@link COMPOSE_KEY_DISPOSITIONS} that belong to the
 * artifact envelope and are therefore NOT assembled into a package body — the
 * reasons, per key, sit on {@link AssembledPackageBodyKey}. One declaration
 * feeds both that type and {@link assembledPackageBodyShape}, so the static and
 * runtime halves cannot name different sets.
 * @internal
 */
const ASSEMBLED_PACKAGE_BODY_ENVELOPE_KEYS = ['packages', 'plugins', 'devPlugins', 'devLogins', 'demoStaff'] as const satisfies readonly StackDefinitionKey[];

/** One member of {@link ASSEMBLED_PACKAGE_BODY_ENVELOPE_KEYS}. @internal */
type AssembledPackageBodyEnvelopeKey = (typeof ASSEMBLED_PACKAGE_BODY_ENVELOPE_KEYS)[number];

/** The dispositions that mark a stack key as a metadata COLLECTION. @internal */
const ASSEMBLED_PACKAGE_BODY_DISPOSITIONS: readonly string[] = ['concat', 'objects', 'functions'];

/**
 * Runtime half of {@link AssembledPackageBodyKey}: the collection members of
 * {@link STACK_DEFINITION_COLLECTIONS_SHAPE}, read off the same disposition
 * table the type is derived from, minus the same
 * {@link ASSEMBLED_PACKAGE_BODY_ENVELOPE_KEYS}.
 *
 * The return type is `Pick<typeof STACK_DEFINITION_COLLECTIONS_SHAPE,
 * AssembledPackageBodyKey>`, which is what makes the derivation mechanical
 * rather than a promise: `Pick` requires every derived key to exist on that
 * shape, so a collection declared in the disposition table but living outside
 * the collections shape is a COMPILE error here, not a key that quietly goes
 * missing from every assembled package body.
 *
 * @internal
 */
function assembledPackageBodyShape(): Pick<typeof STACK_DEFINITION_COLLECTIONS_SHAPE, AssembledPackageBodyKey> {
  const shape: Record<string, unknown> = {};
  for (const [key, disposition] of Object.entries(COMPOSE_KEY_DISPOSITIONS)) {
    // Envelope keys stay on the artifact: `packages` cannot nest,
    // `plugins` / `devPlugins` are assembly instructions no body could carry,
    // and `devLogins` is boot-banner text whose only reader looks at the top
    // level, as is `demoStaff`, the development boot's demo accounts.
    if ((ASSEMBLED_PACKAGE_BODY_ENVELOPE_KEYS as readonly string[]).includes(key)) continue;
    if (!ASSEMBLED_PACKAGE_BODY_DISPOSITIONS.includes(disposition)) continue;
    shape[key] = (STACK_DEFINITION_COLLECTIONS_SHAPE as Record<string, unknown>)[key];
  }
  return shape as Pick<typeof STACK_DEFINITION_COLLECTIONS_SHAPE, AssembledPackageBodyKey>;
}

/**
 * One package as it is ASSEMBLED into a release artifact, and as the load path
 * registers it (ADR-0130 D4; #14242 decision B, maintainer 2026-09-02).
 *
 * ## The two stages this schema exists to separate
 *
 * `ManifestSchema` describes a package at AUTHORING time: its `objects` key is
 * `z.array(z.string())` — GLOB PATTERNS naming the files a file-based loader
 * should read. What reaches the ADR-0130 load path is an ASSEMBLED payload
 * whose `objects` are object DEFINITIONS: `composeStacks(…, { manifest:
 * 'preserve' })` folds each input stack's own metadata onto its manifest,
 * `AppPlugin` flattens an artifact into `{ ...bundle.manifest, ...bundle }`
 * before calling `manifest.register()`, and `ObjectQL.registerApp` iterates
 * those bodies as definitions.
 *
 * One schema was being asked to describe both stages, so a full parse of a real
 * artifact entry REFUSED it (`manifest.objects.0: expected string, received
 * object`) and the load path could only gate the wrapper. #14242 recorded three
 * roads and the maintainer took **B**: give the assembled form its own
 * declaration, so both stages are describable and a load-time consumer has
 * something correct to parse against. ⛔ Widening `ManifestSchema.objects` to a
 * union of both spellings (road C) was REJECTED by name: a union that accepts
 * both stages makes neither stage checkable, which is the tolerance-at-the-
 * consumer shape this repository refuses (Prime Directive #12).
 *
 * ## What it is, mechanically
 *
 * The manifest's own fields, plus every metadata COLLECTION the stack schema
 * declares minus the envelope keys — the key set derived from one table rather
 * than transcribed (see {@link AssembledPackageBodyKey}). Where the two halves
 * declare the SAME key, the collection wins, because that is what the assembled
 * payload actually carries and what `registerApp` reads:
 *
 * | key | manifest (authoring) | assembled body |
 * | --- | --- | --- |
 * | `objects` | glob patterns | object definitions |
 * | `datasources` | glob patterns | datasource definitions |
 * | `permissions` | required-capability grant block (ADR-0025) | permission sets |
 *
 * That precedence is not chosen here: it is `AppPlugin`'s flatten order
 * (`{ ...manifest, ...bundle }`) stated as a declaration. A manifest key the
 * assembled stage overrides therefore has no expression in an assembled body —
 * write it in the package's own stack, where the collection form is read.
 *
 * NO `strictObject` spelling appears here, and none is needed. This schema is
 * `ManifestSchema.extend(...)`, and `.extend()` carries the base's unknown-key
 * posture: commit 4d0d9445a closed `ManifestSchema`, so an assembled body is closed too,
 * BY INHERITANCE — an undeclared key on one is REFUSED, by name and with the
 * declared spelling offered for a near miss. ⛔ Do not read the absence of the
 * `strictObject` spelling as a declined posture; it is an inherited one.
 *
 * Two gates therefore land at the seam that registers a body: that inherited
 * unknown-key refusal, and the collection-SHAPE gate #14242 asked for — a body
 * whose collections are the wrong shape (globs where definitions belong) is
 * refused, loudly, there rather than registered and silently owning nothing.
 * ⛔ Never re-open this surface with `.loose()` or a `.catchall()` to make an
 * assembled body tolerant: that would leave this declaration the one door in
 * the chain accepting what the manifest it extends refuses.
 *
 * ## A non-array `packages` is MALFORMED, not absent
 *
 * This is the single statement of the rule. The key is
 * declared on {@link ObjectStackDefinitionSchema} as an ARRAY of
 * {@link ArtifactPackageSchema} entries, each wrapping one body of this
 * schema. It therefore has two readings:
 *
 * - **Absent**: a SINGLE-package artifact. This is ADR-0130 D4's second
 *   branch, where the artifact itself is the one package body.
 * - **An array**: N package entries, each gated by {@link ArtifactPackageSchema}.
 *
 * Any other value, such as `null`, `{}`, `0` or `'x'`, is neither reading. It
 * is malformed and REFUSED; it is never read as absent. `resolveArtifactPackageOrder`
 * (`@objectstack/core`) raises the refusal as `INVALID_ARTIFACT_PACKAGES`
 * (ADR-0112, `status: 422`). A reader that fell through to the artifact's
 * top level instead would answer questions about an artifact the loader
 * refuses. One reader would then boot what another refuses, which is the
 * split this rule closes.
 *
 * `null` is named first on purpose: ABSENT means `undefined` and nothing
 * else. The key's `.optional()` admits `undefined`, not `null`, so this schema
 * refuses `null` (`invalid_type`), `composeStacks` refuses it with two or more
 * inputs (`STACK_SCHEMA_INVALID`), and every reader refuses it with the
 * resolver's envelope. The readers once treated it as absent; they were
 * aligned to this declaration (#19926, ruling A), and ⛔ never the reverse.
 */
/*
 * ANNOTATED, not inferred — and annotated with a STRUCTURAL type, not a named
 * one. Both halves were measured on #14513, neither is a preference.
 *
 * Not inferred: inferring it emits the manifest and all ~35 collection
 * declarations a SECOND time inside `ObjectStackDefinitionSchema`'s own
 * inferred type, which `tsc` refuses to serialize at all:
 *
 *   TS7056: The inferred type of this node exceeds the maximum length the
 *           compiler will serialize. An explicit type annotation is needed.
 *
 * Structural, not named: this schema is the element type of the stack
 * schema's `packages` key, so whatever is written here is printed INSIDE
 * `ObjectStackDefinitionSchema`'s declaration — and that declaration is
 * embedded by every schema that carries a stack (`system/environment-artifact.zod.ts`
 * among them). The declaration bundler inlines STRUCTURAL types into each chunk
 * that embeds them, but a NAMED type alias can only be imported from the chunk
 * that declares it. Two earlier shapes of this annotation named an alias
 * (`z.ZodType<AssembledPackageBodyParsed, AssembledPackageBody>`), and the
 * measured consequence was not local: `stack.zod` became a shared chunk that
 * the `environment-artifact` chunk imports, so every consumer of
 * `@objectstack/spec/system` started loading the whole stack schema
 * declaration it never loaded before — `packages/qa/http-conformance`'s
 * type-check program went from 691,580 to 734,202 lines of definitions
 * (+42,622, the size of `ObjectStackDefinitionSchema`'s declaration), from
 * 4.47 GB to 4.88 GB of heap, and past the 4096 MB ceiling
 * `scripts/check-type-check-coverage.mjs` pins as CI's. A first attempt that
 * ALSO referenced `typeof STACK_DEFINITION_COLLECTIONS_SHAPE` per key from the
 * alias emitted the collections shape a second time on top (21,443 lines).
 *
 * `Record<string, unknown>` on both sides is therefore the whole of the static
 * contract: an assembled body is an object. The two aliases below are derived
 * FROM this annotation (ADR-0122), never the other way round, so no name can
 * re-enter the stack schema's printed type. What a consumer loses is the
 * static field typing inside an assembled body; the RUNTIME schema still
 * carries the manifest's every field plus every collection's full declaration
 * (the key set derived from `COMPOSE_KEY_DISPOSITIONS`, see
 * `assembledPackageBodyShape`), so a wrong-shaped body is refused exactly as
 * before. Readers of assembled bodies (`compile.ts`, `artifact-packages.ts`)
 * already treat them as records and narrow at the point of use — the honest
 * shape for a payload whose collections are attributed per package only at
 * composition time.
 */
export const AssembledPackageBodySchema: z.ZodType<Record<string, unknown>, Record<string, unknown>> =
  lazySchema(() =>
    ManifestSchema.extend(assembledPackageBodyShape())
      .describe('One package as assembled into a release artifact (ADR-0130 D4)'));

/**
 * The assembled package body as authored — derived from the schema's
 * annotation above, deliberately structural (see the note there).
 */
export type AssembledPackageBody = z.input<typeof AssembledPackageBodySchema>;
/** Post-parse shape of {@link AssembledPackageBody} — defaults applied, transforms run (ADR-0122). */
export type AssembledPackageBodyParsed = z.infer<typeof AssembledPackageBodySchema>;

/**
 * `hooks`, as a JSON document can hold it: the assembled declaration with its
 * `handler` narrowed to the lowered string ref.
 *
 * The narrowing is written HERE rather than on `HookSchema`, because the
 * authoring door must keep accepting the inline callable — `objectstack build`
 * is what lowers it, and `data/hook.zod.ts` says so in its own words: 「The
 * JSON artifact therefore only ever contains the string form.」 `handler` keeps
 * the base's `.optional()`: a hook that carries a `body` instead declares no
 * handler at all, and the registry record of a hook whose handler was an inline
 * callable has none either (the projection drops it).
 *
 * `safeExtend`, not `extend` (#21565): `HookSchema` carries an object-level
 * check — a hook `body` may not target a stored-metadata table — and zod
 * refuses to overwrite a key on a refined object with `extend`. `safeExtend`
 * accepts the narrower `handler` and keeps that check, so an artifact's parse
 * refuses the same hook the authoring door does.
 */
function jsonStageHooksKey() {
  return z.array(HookSchema.safeExtend({
    handler: z.string().optional()
      .describe('Handler function name — the lowered string ref the JSON artifact carries'),
  })).optional().describe('Object Lifecycle Hooks, as a JSON document carries them');
}

/**
 * `functions`, as a JSON document can hold it: the two LOWERED members of
 * {@link FlowFunctionEntrySchema} for the map form, and the array member with
 * its callable branch dropped.
 *
 * Both lowered spellings are kept, not just the record one: `objectstack build`
 * emits `{ myFn: 'myFn' }` for a bare entry and
 * `{ myFn: { handler: 'myFn', effect: 'writes' } }` for a declared one, so a
 * stage that admitted only the second would refuse artifacts this repo really
 * writes.
 *
 * @param handlerOptional the RECORD stage's one difference from the artifact
 * stage. A registry row is `toRecordManifest`'s structural JSON projection of
 * the live assembled body, and that projection drops the callable it finds
 * under `handler` — so the record of a declared function is the declaration
 * MINUS its handler. Nothing replaces it, and nothing should: a ref minted
 * anywhere but `objectstack build` is not guaranteed to be the ref `build`
 * mints, so an absent `handler` is the honest statement 「declared here, not
 * serialisable」. `effect` carries whatever optionality each form already gives
 * it — `.default('pure')` on the map declaration, `.optional()` on the array
 * entry — and neither is restated here.
 */
function jsonStageFunctionsKey(handlerOptional: boolean) {
  const handlerRef = z.string().min(1)
    .describe('The lowered handler ref (built artifacts) — the callable rides in the sibling ESM module');
  return z.union([
    z.record(z.string(), z.union([
      handlerRef,
      handlerOptional
        ? FlowFunctionLoweredDeclarationSchema.extend({ handler: handlerRef.optional() })
        : FlowFunctionLoweredDeclarationSchema,
    ])),
    // Transcribed rather than derived from the authoring array member above:
    // that member is declared INLINE inside the assembled body's own shape, and
    // narrowing it in place is the one thing this pair may not do. The key sets
    // are held equal by a pin in `stack-json-stage-package-body.test.ts`, so a
    // key added there and not here reddens by name.
    z.array(z.object({
      name: z.string(),
      handler: handlerOptional ? handlerRef.optional() : handlerRef,
      packageId: z.string().optional(),
      effect: FlowFunctionEffectSchema.optional(),
    })),
  ]).optional().describe('Named handler functions, lowered to the refs a JSON document carries');
}

/**
 * One package as an INERT JSON release artifact carries it — the third of the
 * four stages a package body passes through, and the first one that is really
 * JSON.
 *
 * ## Why this is a separate declaration and not a narrowing of the assembled body
 *
 * {@link AssembledPackageBodySchema} spans the IN-MEMORY composed stage, where
 * `functions` and `hooks` legitimately hold live callables:
 * `composeStacks(stacks, { manifest: 'preserve' })` builds exactly such a body
 * and the load path registers it, which is the invariant this file states
 * further down. Narrowing the assembled body would refuse a published
 * composition function's own output — so the artifact stage gets its own name
 * instead, and the assembled one is ⛔ untouched.
 *
 * ## What it buys, measured
 *
 * Exactly two of the assembled body's members have no JSON Schema form —
 * `functions` (a `z.function()` branch) and `hooks` (a `z.custom()` branch) —
 * and one unrepresentable member costs every embedder its whole JSON Schema.
 * With both narrowed to their lowered spellings this body converts under
 * `z.toJSONSchema`, so a JSON surface that wants the assembled stage can
 * declare it instead of writing `z.unknown()` and accepting anything.
 *
 * ADR-0130 D4 is what says an artifact is inert JSON: 「a plugin written inside
 * `packages[i].manifest` could never be constructed by a loader, so a reader
 * that resolved it there would register garbage where it used to skip in
 * silence.」 A callable in an artifact is the same case.
 */
/*
 * ANNOTATED with the same STRUCTURAL type as the assembled body above, for the
 * same two measured reasons recorded there (TS7056 on the inferred type; a
 * named alias turning `stack.zod` into a shared chunk). ⛔ Do not replace either
 * annotation with an inferred or named type without re-reading that note.
 */
export const ArtifactStagePackageBodySchema: z.ZodType<Record<string, unknown>, Record<string, unknown>> =
  lazySchema(() =>
    ManifestSchema.extend({
      ...assembledPackageBodyShape(),
      functions: jsonStageFunctionsKey(false),
      hooks: jsonStageHooksKey(),
    }).describe('One package as an inert-JSON release artifact carries it (ADR-0130 D4)'));

/** The artifact-stage package body as authored. */
export type ArtifactStagePackageBody = z.input<typeof ArtifactStagePackageBodySchema>;
/** Post-parse shape of {@link ArtifactStagePackageBody} — defaults applied, transforms run (ADR-0122). */
export type ArtifactStagePackageBodyParsed = z.infer<typeof ArtifactStagePackageBodySchema>;

/**
 * One package as the package REGISTRY records it — the fourth stage, and the
 * one that had no declaration until now.
 *
 * It is {@link ArtifactStagePackageBodySchema} with `functions[].handler`
 * OPTIONAL, in both the map-record form and the array form, and nothing else.
 * That single difference is the whole distance between an artifact and a
 * record: an artifact is written by `objectstack build`, which lowers every
 * callable to a ref, while a record is `toRecordManifest`'s structural JSON
 * projection of a LIVE body, which drops the callable and mints nothing in its
 * place. A record therefore reports what each function is named and what it
 * declared, with `handler` absent where the callable was.
 *
 * ⛔ Never widen this to `z.unknown()` to make a row fit. A row that parses
 * through neither this stage nor the authoring one is a producer defect, and
 * this is the declaration that has to keep saying so.
 *
 * ## Its published type is deliberately an index signature
 *
 * This schema is declared `z.ZodType<Record<string, unknown>, Record<string,
 * unknown>>`, so the published type of a record-stage body is an index
 * signature: any object assigns to it. It is the `manifest` of
 * `AssembledInstalledPackageSchema` (`@objectstack/spec/api-assembled`), so an
 * authoring-stage `InstalledPackage` assigns to `AssembledInstalledPackage`,
 * and a row whose `manifest` belongs to neither stage type-checks as an
 * `InstalledPackageAtEitherStage`. That is the accepted static contract — the
 * maintainer ruling on #19324 (letter 丙) — not a gap to tighten in passing.
 *
 * The RUNTIME schema is the enforced contract. It carries the manifest's every
 * field, every collection's full declaration and the two lowered members
 * above, so `.parse()` refuses a wrong-shaped body member by member. Narrow a
 * record-stage body by parsing it, never by trusting its static type.
 *
 * Why not inferred: the body is the whole metadata vocabulary, and `tsc`
 * refuses to print it into the declarations that embed it — TS7056, 「The
 * inferred type of this node exceeds the maximum length the compiler will
 * serialize」. #14513 measured that on the assembled body; for this stage,
 * dropping this annotation, the artifact stage's and the cast below fails the
 * declaration build with TS7056 at `PackageApiContracts` (measured on #19324
 * at `d1ca8741dd` and again at `3bd28e2b2e`). Why not a named type: #14513
 * measured that an alias declared in this module turns `stack.zod` into a
 * shared declaration chunk its embedders import, and recorded the heap failure
 * that followed beside {@link AssembledPackageBodySchema}; for this stage that
 * reading is inherited, not re-measured.
 *
 * The precise form, if the schema depth ever allows it, is the one #19324
 * measured as A2: infer this stage and the artifact stage (drop both
 * annotations and the cast), and give compact `typeof`-based annotations to
 * the four declarations that embed the body — `PackageApiContracts`,
 * `InstalledPackageAtEitherStageSchema`, `ListInstalledPackagesResponseSchema`
 * and `GetInstalledPackageResponseSchema`. At `d1ca8741dd` it built, turned
 * all five of the gap's measured type readings into compile errors, and left
 * the runtime bundles byte-identical. Its cost is declaration size: +20,209
 * lines in the then `./api` entry (one expansion of this stage) and +44,342 in
 * the root entry (this stage and the artifact stage). The heaviest type-check
 * program under CI's heap ceiling, `qa/http-conformance`'s, was not measured
 * under it.
 */
/*
 * ANNOTATED structurally — see the note on the artifact stage above, and the
 * section of this docblock on the published type for what that costs a
 * consumer. The `as unknown as z.ZodObject<z.ZodRawShape>` cast below is that
 * annotation's price: the artifact stage's declared type no longer says it is
 * an object, so `.extend()` is reached through a cast. The cast is type-only
 * and emits nothing; at runtime `.extend()` runs on the artifact stage's
 * object schema.
 */
export const RecordStagePackageBodySchema: z.ZodType<Record<string, unknown>, Record<string, unknown>> =
  lazySchema(() =>
    (ArtifactStagePackageBodySchema as unknown as z.ZodObject<z.ZodRawShape>).extend({
      functions: jsonStageFunctionsKey(true),
    }).describe('One package as the package registry records it — the artifact stage with `functions[].handler` optional'));

/** The record-stage package body as authored. */
export type RecordStagePackageBody = z.input<typeof RecordStagePackageBodySchema>;
/** Post-parse shape of {@link RecordStagePackageBody} — defaults applied, transforms run (ADR-0122). */
export type RecordStagePackageBodyParsed = z.infer<typeof RecordStagePackageBodySchema>;

/**
 * The origins one artifact entry may state for its package — the subset of
 * {@link InstalledPackageSourceSchema} a LOAD path can register.
 *
 * One merged artifact may carry packages of different origins: a control plane
 * merges an environment's marketplace installs into the artifact it boots the
 * environment from, beside the environment's own code. The entry is where the
 * producer that merged it says which is which, so the registry row records the
 * producer's statement instead of the load door's `code` default.
 *
 * `authored` is not a member: an authored package is installed from
 * `sys_packages` through `installPackage`, never registered from an artifact,
 * and `ObjectQL.registerApp` refuses it. No new value is declared here — this
 * is a narrowing of the one closed origin set, so the registry stays the only
 * declaration of what an origin means.
 */
export const ArtifactPackageSourceSchema = lazySchema(() => InstalledPackageSourceSchema.extract(['code', 'marketplace'])
  .describe('Where an artifact-carried package came from: code (the deployment\'s own code) or marketplace (installed from the marketplace)'));
export type ArtifactPackageSource = z.input<typeof ArtifactPackageSourceSchema>;

/**
 * One package carried by a release artifact, in its ASSEMBLED form — the
 * element type of `packages` on {@link ObjectStackDefinitionSchema}.
 *
 * Same WRAPPER as {@link ArtifactPackageEntrySchema} — the body sits under
 * `manifest:`, the structural position ADR-0130 D4 reserves so a future
 * `{ ref, integrity }` external segment is an ADDITIVE key rather than a
 * reshape — with the body half declared at the stage the artifact is actually
 * in: {@link AssembledPackageBodySchema}.
 *
 * The authoring entry is a valid instance of this one: a body carrying manifest
 * fields and no collections parses green, which is exactly what a hand-written
 * `{ manifest: { id, name, version, type } }` entry is. What it does NOT admit
 * is an authoring manifest whose `objects` are globs — refused here, on
 * purpose, because a glob in a compiled artifact names files nobody will read.
 *
 * `source` is the entry's one key beside the body: the origin the producer
 * that assembled the artifact states for this package
 * ({@link ArtifactPackageSourceSchema}). The load path stamps it on the
 * package's registry row (`InstalledPackageSchema.source`); an entry that
 * states none is registered with the load door's own statement, `code` unless
 * the door says otherwise. It sits on the WRAPPER, not in the body, because it
 * describes how the package reached this artifact, not the package itself.
 */
export const ArtifactPackageSchema = lazySchema(() => strictObject({
  surface: 'an assembled artifact package entry',
  history:
    'The entry is a wrapper object whose package body lives under `manifest:` — the '
    + 'structural position ADR-0130 D4 reserves so a future `{ ref, integrity }` external '
    + 'segment is an additive key rather than a reshape. An inlined body (`id`, `name`, '
    + '`version`, `objects`, … written directly on the array element) is therefore refused: '
    + 'wrap it as `{ manifest: { … } }`.',
}, {
  manifest: AssembledPackageBodySchema.describe('The assembled package body this artifact entry carries'),
  source: ArtifactPackageSourceSchema.optional()
    .describe('Where this package came from, stamped on its registry row: code (the deployment\'s own code) or marketplace (installed from the marketplace). Absent: the registering door\'s own statement, `code` by default'),
}).describe('One package carried by a release artifact, assembled (ADR-0130 D4)'));

export type ArtifactPackage = z.input<typeof ArtifactPackageSchema>;
/** Post-parse shape of {@link ArtifactPackage} — defaults applied, transforms run (ADR-0122). */
export type ArtifactPackageParsed = z.infer<typeof ArtifactPackageSchema>;

/**
 * ObjectStack Ecosystem Definition
 *
 * This schema represents the "Full Stack" definition of a project or environment.
 * It is used for:
 * 1. Project Export/Import (YAML/JSON dumps)
 * 2. IDE Validation (IntelliSense)
 * 3. Runtime Bootstrapping (In-memory loading)
 * 4. Platform Reflection (API & Capabilities Discovery)
 */
/**
 * 1. DEFINITION PROTOCOL (Static)
 * ----------------------------------------------------------------------
 * Describes the "Blueprint" or "Source Code" of an ObjectStack Plugin/Project.
 * This represents the complete declarative state of the application.
 *
 * Usage:
 * - Developers write this in files locally.
 * - AI Agents generate this to create apps.
 * - CI Tools deploy this to the server.
 */
/*
 * #8687 — the TOP-LEVEL door is `strictObject` like every inner authorable
 * surface the #4001 campaign closed. Before this, an unknown top-level key
 * parsed green and was silently dropped: a `flow`-for-`flows` typo (or the
 * stale `approvalProcesses`) shipped an artifact missing that whole metadata
 * family, with `os validate` — even `--strict` — exiting 0, because the
 * `defineStack:` diagnostic was printed at load, outside the warning tally.
 *
 * The near-miss guidance that used to arrive through `lintUnknownStackKeys`
 * (`objectz` → "did you mean `objects`?") now arrives through the refusal
 * itself: `strictObject`'s error map suggests the closest declared key, and
 * the lint deliberately goes quiet on a strict schema (its own posture rule —
 * see `kernel/metadata-authoring-lint.ts`), so there is one voice, not two.
 *
 * The `guidance` entries are the curated half: retired/never-keys where a
 * rename suggestion would be wrong. `storage` mirrors `STACK_KEY_GUIDANCE`
 * (`data/authoring-key-lint.ts`), which stays exported for the generic lint
 * API but no longer fires for this surface.
 */
export const ObjectStackDefinitionSchema = lazySchema(() => strictObject({
  surface: 'this stack definition',
  history:
    'Until this surface was closed (the outermost door), an unknown top-level stack '
    + 'key parsed green and its value was silently dropped — a one-character typo could ship '
    + 'an artifact missing a whole metadata family while `os validate` exited 0. The declared '
    + 'keys are enumerated by `ObjectStackDefinitionSchema` (@objectstack/spec, stack.zod.ts) '
    + 'and in the stack-definition reference docs.',
  guidance: {
    storage:
      'the file-storage backend is a deployment concern, not an application declaration. '
      + 'Configure it with the OS_STORAGE_* environment variables, or per-deployment in Setup → '
      + 'Settings → Storage (which also holds credentials — a stack definition would commit them '
      + 'to git and to any published artifact).',
    approvals:
      'approvals are not a top-level collection (ADR-0019): author an approval as a flow with '
      + 'one or more Approval nodes, in `flows`.',
    approvalProcesses:
      'approvals are not a top-level collection (ADR-0019, standalone `approvals` removed in '
      + '7.4): author an approval as a flow with one or more Approval nodes, in `flows`.',
    workflows:
      'there is no top-level `workflows` collection (ADR-0020): a record state machine is a '
      + '`state_machine` validation rule on the object it governs.',
    portals:
      'the top-level `portals` collection was removed — nothing ever consumed it. '
      + 'Author external-user UI with `apps`/`views` plus positions and permission sets.',
    themes:
      '`themes` was removed in @objectstack/spec 17.1 (ADR-0049) — authored themes '
      + 'were parsed and stored, but no framework package ever read them back, no first-party '
      + 'app mounted the spec-aware theme provider, and nothing selected an active theme, so '
      + 'a declared theme changed nothing on screen. Delete the key. To colour the shipped '
      + 'console, set `app.branding.primaryColor` / `accentColor` — the one live colour '
      + 'surface (it drives `--primary`, `--accent` and their derived variables).',
    onDisable:
      'no kernel, runtime or service ever called `onDisable` (the uninvoked lifecycle '
      + 'family is retired), so a value written here goes nowhere. Do teardown inside the '
      + 'resources `onEnable` acquires.',
  },
}, {
  /** System Configuration */
  manifest: ManifestSchema.optional().describe('Project Package Configuration'),

  /**
   * The artifact's package list (ADR-0130 D4) — **optional**, and read beside
   * `manifest` rather than instead of it.
   *
   * A release artifact MAY carry N package manifests so a product can be split
   * into modules **without renaming a single object** (which is what separate
   * namespaces would cost: the object `name` IS the table name, the REST path,
   * the formula token and the saved-view key — ADR-0129 D1–D2 — and
   * rename-on-install is ADR-0048's standing non-goal).
   *
   * ## Read BOTH shapes — the schema shape IS the compatibility mechanism
   *
   * - `packages` present → iterate it.
   * - `packages` absent → treat `manifest` (singular) as a **single-element
   *   list**.
   *
   * A value that is present but is not an array takes neither branch. The rule
   * for it is stated once, beside {@link AssembledPackageBodySchema}.
   *
   * `manifest` is therefore RETAINED, not replaced. A replacement would break
   * every artifact already built and on disk at every customer; the read-both
   * rule is the term ADR-0130's whole compatibility claim rests on, which is
   * why D4 states it as the schema decision rather than an implementation note.
   * An existing single-`manifest` artifact takes the second branch and its
   * behaviour is unchanged.
   *
   * ## The element is the ASSEMBLED entry (#14242 B)
   *
   * Each entry is `{ manifest: <assembled package body> }` — manifest fields
   * plus the metadata collections that package owns, which is the payload
   * `ObjectQL.registerApp` iterates. This key is read at LOAD time, so the
   * authoring-time {@link ArtifactPackageEntrySchema} (whose `manifest.objects`
   * are glob patterns) cannot describe it: that mismatch was #14242, and the
   * maintainer's decision (2026-09-02) was to declare the assembled stage
   * rather than widen the authoring one. A hand-written manifest-only entry
   * still parses — it is an assembled body carrying no collections.
   *
   * `composeStacks([...], { manifest: 'preserve' })` is what produces this list
   * from N authored stacks; `os build` / `os compile` writes it into the
   * artifact, and the load path registers each entry in dependency-topological
   * order (ADR-0130 D5, ADR-0116's one sorter).
   */
  packages: z.array(ArtifactPackageSchema).optional()
    .describe('Assembled package bodies carried by this release artifact (ADR-0130 D4)'),

  ...STACK_DEFINITION_COLLECTIONS_SHAPE,
}).superRefine(applyApiEndpointGates)
  .superRefine(applyPermissionSetOwnerBindingGate)
  .superRefine(applyCollectionItemOwnerStampGate)
  .superRefine(applyControlledByParentExtensionGate));

export type ObjectStackDefinition = z.input<typeof ObjectStackDefinitionSchema>;
/** Post-parse shape of {@link ObjectStackDefinition} — defaults applied, transforms run (ADR-0122). */
export type ObjectStackDefinitionParsed = z.infer<typeof ObjectStackDefinitionSchema>;

/**
 * Extract the element type from an array type.
 * @internal
 */
type ExtractArrayItem<T> = T extends (infer Item)[] ? Item : never;

/**
 * Input type for `defineStack()` that accepts both array and map format
 * for all named metadata collections.
 * 
 * Map format allows defining metadata using the key as the `name` field:
 * ```ts
 * // Array format (traditional)
 * objects: [{ name: 'task', fields: { ... } }]
 * 
 * // Map format (key becomes name)
 * objects: { task: { fields: { ... } } }
 * ```
 * 
 * The output type is always arrays (`ObjectStackDefinition`).
 */
export type ObjectStackDefinitionInput =
  Omit<z.input<typeof ObjectStackDefinitionSchema>, MapSupportedField> & {
    [K in MapSupportedField]?: MetadataCollectionInput<
      ExtractArrayItem<NonNullable<z.input<typeof ObjectStackDefinitionSchema>[K]>>
    >;
  };

// Alias for backward compatibility
export const ObjectStackSchema = lazySchema(() => ObjectStackDefinitionSchema);
export type ObjectStack = ObjectStackDefinition;

/**
 * Options for `defineStack()`.
 */
export interface DefineStackOptions {
  /**
   * When `true` (default), enables strict validation:
   * - All Zod schemas are validated (field names, types, etc.)
   * - Cross-reference validation runs (views/actions/workflows reference valid objects)
   * - Ensures data integrity and catches errors early
   *
   * When `false`, validation is skipped for maximum flexibility
   * (e.g., when views reference objects provided by other plugins).
   * Use this ONLY when you need to bypass validation for advanced use cases.
   *
   * @default true
   */
  strict?: boolean;

  /**
   * Object names provided by the OTHER packages of the same release artifact
   * (ADR-0130 D1 — "the release artifact is the co-ownership boundary").
   *
   * `defineStack` sees exactly ONE stack, so "defined in objects" and "defined
   * in the artifact" are the same question for a single-package app and two
   * different questions for a package that co-owns a namespace with its
   * siblings. This option is how the second question is asked: the
   * ARTIFACT-SCOPED reference classes — `permissions[].objects` and
   * `data[].object` — resolve against this stack's own objects PLUS these
   * names.
   *
   * ⚠️ It widens exactly those two classes and nothing else. `hooks[].object`
   * and an app's own `navigation` `objectName` stay refused against the
   * stack's own objects even when the name appears here, because ADR-0130 §1.5
   * measured both of those refusals and recorded them as the SHAPE of the seam:
   * *"navigation crosses only through contributions, and the split must follow
   * hook ownership."* Widening them would delete a decision, not honour one.
   *
   * ## Why the two classes cross
   *
   * ADR-0130's 2026-09-02 addendum (#14487) rules that **permission sets stay
   * whole in the `type: app` package** — a set is authored per ROLE, so no
   * module owns one, and ADR-0086 D3 gives a set exactly one owning package.
   * Once the app package also owns objects of its own, its sets necessarily
   * grant on objects owned by its modules. Seed rows are the same shape: data
   * placed into a co-owned object, not a claim on its definition.
   *
   * ## Why an OPTION and not a metadata key
   *
   * The addendum is explicit that **no `module` or grouping key is added to a
   * permission set**, so the opt-in cannot live on the authored item the way
   * an app nav item's `requiresObject` does. It is a property of the
   * COMPOSITION this stack is built for, not of the stack's own metadata, and
   * it therefore leaves `ObjectStackDefinitionSchema` — and every artifact
   * already built from it — untouched.
   *
   * ## The claim is verified, not trusted — in a composition of two or more packages
   *
   * A name listed here that no package in the artifact actually defines is
   * refused by {@link composeStacks} **in a composition of two or more
   * packages**, with the same `STACK_CROSS_REFERENCE_INVALID` envelope and the
   * same per-finding message. The qualifier is load-bearing: `composeStacks`
   * returns a single input untouched, so a one-package composition — like a
   * stack that is never composed — leaves the claim unverified. See
   * {@link collectArtifactCrossReferenceErrors}'s known boundary.
   *
   * Omitting the option keeps `defineStack`'s own behaviour byte-for-byte. It
   * does not exempt the stack from the artifact pass, which re-runs the two
   * rules over every input: a no-op for anything that passed the strict parse,
   * and the first application of those rules to anything that bypassed it.
   *
   * @example
   * ```ts
   * const service = defineStack(serviceConfig);              // owns crm_case
   * const app = defineStack(appConfig, {                     // owns crm_account …
   *   artifactObjects: service.objects?.map((o) => o.name),  // … grants on crm_case
   * });
   * export default composeStacks([service, app], { manifest: 'preserve' });
   * ```
   */
  artifactObjects?: readonly string[];

  /**
   * Flow names provided by the OTHER packages of the same release artifact
   * (ADR-0130 D1, #25514) — the {@link artifactObjects} question, asked of the
   * one reference class whose target is a FLOW.
   *
   * A `type: 'flow'` action's `target` — registered (`actions[]`), authored on
   * an object (`objects[].actions[]`) or inline on a page element — resolves
   * against this stack's own `flows` PLUS these names. The measured shape is a
   * sales action on an app-owned object launching a flow that a module package
   * of the same artifact ships: the runtime registers every package's flows in
   * one automation engine, so the launch works, and only this per-stack check
   * could not see the flow.
   *
   * ⚠️ It WIDENS a check and never switches one on. A stack declaring no flows
   * of its own keeps the existing leniency — its flow targets are not resolved
   * at all, because a plugin may serve them — so these names are consulted only
   * where a target used to be refused: when the stack's own `flows` is
   * non-empty. Nothing else reads them.
   *
   * ## The claim is verified, not trusted — in a composition of two or more packages
   *
   * Every target that resolved ONLY through this list is recorded on the
   * returned stack — a non-enumerable symbol beside the provenance mark, never
   * a key of `ObjectStackDefinitionSchema` — and {@link composeStacks} refuses
   * the composition when no input of it defines that flow, with the same
   * `STACK_CROSS_REFERENCE_INVALID` envelope and the same per-finding message
   * the per-stack pass prints. A listed name no target uses claims nothing, so
   * it is not checked. The boundary is {@link artifactObjects}' own: a
   * one-package composition, or a stack that is never composed, leaves the
   * claim unverified.
   *
   * Omitting the option keeps `defineStack`'s behaviour byte-for-byte.
   *
   * @example
   * ```ts
   * const revenue = defineStack(revenueConfig);           // owns quote_generation
   * const app = defineStack(appConfig, {                  // generate_quote → quote_generation
   *   artifactFlows: revenue.flows?.map((f) => f.name),
   * });
   * export default composeStacks([revenue, app], { manifest: 'preserve' });
   * ```
   */
  artifactFlows?: readonly string[];
}

/**
 * Validate that every object name is prefixed with the package namespace.
 *
 * Rules:
 * - When `manifest.namespace` is set, every `object.name` MUST start with
 *   `${namespace}_` (single underscore). Returns one error per offender.
 * - Names starting with `sys_` are platform-reserved and always allowed.
 * - Names containing `__` (legacy FQN double-underscore form) are flagged
 *   so authors migrate to the canonical single-prefix form.
 * - When `manifest.namespace` is absent (legacy stacks), the check is
 *   skipped — `defineStack` does not invent a prefix on the author's
 *   behalf because doing so would silently introduce a second writing
 *   style.
 *
 * The rule applies recursively to references on other metadata too
 * (views, dashboards, reports, flows, approvals, hooks, app navigation,
 * sharing rules, permissions) — but those are checked by the existing
 * `validateCrossReferences` against the canonical object set, so mis-
 * prefixed references will surface there once the objects are correct.
 */
function validateNamespacePrefix(config: ObjectStackDefinition): string[] {
  const errors: string[] = [];
  const ns = config.manifest?.namespace;
  if (!ns || !config.objects) return errors;

  // Single source of the per-object prefix rule — shared verbatim with the
  // runtime publish enforcement in MetadataManager.publishPackage.
  for (const obj of config.objects) {
    const err = validateObjectNamespacePrefix(obj.name, ns);
    if (err) errors.push(err);
  }
  return errors;
}

/**
 * Validate the "at most one App per package" rule — ADR-0019 (app-as-consumer-unit) D1/D3.
 *
 * A consumer package (`manifest.type === 'app'`) must not define **more than
 * one** app — that is the banned "suite contains apps" shape. Fold the apps
 * into a single app with multiple tabs, or split into separate packages. Zero
 * apps is allowed (a package may still be under authoring, or define its app
 * elsewhere); non-`app` package types are internal contributions and are not
 * constrained here.
 *
 * Mirrors {@link validateNamespacePrefix}: returns one error per violation;
 * `defineStack` aggregates and throws.
 */
function validateSingleApp(config: ObjectStackDefinition): string[] {
  if (config.manifest?.type !== 'app') return [];
  const apps = config.apps ?? [];
  if (apps.length <= 1) return [];
  const names = apps.map((a) => a.name).join(', ');
  return [
    `An 'app' package must define at most one app, but found ${apps.length} (${names}). ` +
      `Fold them into one app with multiple tabs, or split into separate packages — ADR-0019 (app-as-consumer-unit) D3.`,
  ];
}

/**
 * [ADR-0131 D6] The types the metadata-type registry declares
 * runtime-uncreatable (`allowRuntimeCreate: false`) — the flag the save door
 * reads, so an unmanaged install's one write path cannot create an item of
 * any of them. Derived, never listed.
 */
const RUNTIME_UNCREATABLE_TYPES: ReadonlySet<string> = new Set(
  DEFAULT_METADATA_TYPE_REGISTRY.filter((entry) => !entry.allowRuntimeCreate).map((entry) => entry.type),
);

/**
 * [ADR-0131 D6] A package that PERMITS the `unmanaged` install mode must be
 * copyable — the authoring half of "a declared mode is enforced" (the stage-0
 * ACCEPT's Q5 on the D6 execution card).
 *
 * An unmanaged install copies every metadata item into the environment ledger
 * through the one save door, or copies nothing. So a package that declares
 * `installModes` with `'unmanaged'` while it carries what that door cannot
 * write is refused HERE, naming each key, instead of passing `os validate` and
 * being refused at the install door:
 *
 *  - a non-empty collection whose metadata type the registry declares
 *    runtime-uncreatable ({@link RUNTIME_UNCREATABLE_TYPES});
 *  - a key the shared classification refuses
 *    (`UNMANAGED_INSTALL_KEY_DISPOSITIONS`: code, an extension of another
 *    package's items, an artifact envelope), on the stack or on its manifest.
 *
 * The classification is the one the install door's import planner reads
 * (`kernel/unmanaged-install.ts`), so the two refusals cannot disagree. ⛔ No
 * partial copy and no `OS_METADATA_WRITABLE` hatch: the remedy is to stop
 * permitting `unmanaged`, or to move what cannot be copied out of the package.
 *
 * Mirrors {@link validateSingleApp}: one finding per key; `defineStack`
 * aggregates and throws.
 */
function validateUnmanagedInstallMode(config: ObjectStackDefinition): string[] {
  if (!resolveInstallModes(config.manifest).includes('unmanaged')) return [];
  const findings: string[] = [];
  const judge = (value: unknown, key: string, where: string): void => {
    if (!unmanagedInstallValueCarries(value)) return;
    const type = PLURAL_TO_SINGULAR[key];
    if (type !== undefined) {
      if (RUNTIME_UNCREATABLE_TYPES.has(type)) {
        const count = Array.isArray(value) ? value.length : Object.keys(value as object).length;
        findings.push(
          `\`${where}\` carries ${count} '${type}' item(s), and the metadata-type registry declares '${type}' `
          + 'runtime-uncreatable, so an unmanaged install cannot copy them into the environment.',
        );
      }
      return;
    }
    const disposition = UNMANAGED_INSTALL_KEY_DISPOSITIONS[key];
    if (disposition === undefined || !UNMANAGED_INSTALL_REFUSING_DISPOSITIONS.has(disposition)) return;
    findings.push(
      disposition === 'code'
        ? `\`${where}\` is code, which has no metadata form an unmanaged install can copy into the environment.`
        : disposition === 'uncopyable'
          ? `\`${where}\` extends items another package owns, and an unmanaged install has no environment row for that.`
          : `\`${where}\` describes an artifact of several packages, and an unmanaged install copies one package.`,
    );
  };
  for (const [key, value] of Object.entries(config)) {
    // `manifest` is the package's own manifest here, judged key by key below —
    // never the nested-manifest envelope the classification names for a body.
    if (key === 'manifest') continue;
    judge(value, key, key);
  }
  for (const [key, value] of Object.entries(config.manifest ?? {})) {
    judge(value, key, `manifest.${key}`);
  }
  return findings;
}

/**
 * Platform-provided object names (`sys_` / `cloud_` / `ai_` prefixes — the
 * same classification the seed loader applies). These objects are contributed
 * by the runtime, never by the stack, so cross-reference checks must not
 * demand they appear in `config.objects`: an app legitimately seeds the
 * ADR-0090 business-unit tree (`sys_business_unit`) or grants a delegated
 * administrator CRUD on the RBAC link tables (`sys_user_position`, ADR-0090
 * D12). The typo net stays intact for the stack's OWN objects.
 *
 * Kept as a PREFIX test at this layer on purpose: these are hard `defineStack`
 * throws, and a third-party package may legitimately contribute a prefixed
 * object this repo's registry cannot know about — failing the build on that
 * would be worse than the typo it catches. The narrower "prefixed but no known
 * package registers it" signal (`sys_approval_process`, issue #3583) is an
 * ADVISORY finding, so it lives in `@objectstack/lint`'s reference rules where
 * it can warn instead of throw — see `isPlatformProvidedObjectName`.
 */
function isPlatformObjectName(name: string): boolean {
  return hasPlatformObjectPrefix(name);
}

/**
 * Collect all object names defined in a stack definition.
 */
function collectObjectNames(config: ObjectStackDefinition): Set<string> {
  const names = new Set<string>();
  if (config.objects) {
    for (const obj of config.objects) {
      // [#18239] `composeStacks`' artifact pass reads its unparsed inputs through
      // here, and `mergeObjects` skips a non-object entry rather than refusing
      // it — so skip it here too instead of dereferencing it.
      if (!isRecord(obj)) continue;
      names.add(obj.name);
    }
  }
  return names;
}

/**
 * One inline action found on a page, plus the subject string that identifies it
 * in an error message.
 */
interface InlineActionSite {
  /** Canonical action shape — post-{@link InlineActionSchema}, so `to` is already `target`. */
  action: { type?: string; name?: string; target?: string };
  /** Message subject, e.g. `Inline action 'new_task' on page 'home' (regions.0.components.2)`. */
  where: string;
}

const isRecord = (value: unknown): value is Record<string, unknown> =>
  typeof value === 'object' && value !== null && !Array.isArray(value);

/** A node is component-shaped when it is an object carrying a string `type`. */
const isComponentNode = (value: unknown): value is Record<string, unknown> =>
  isRecord(value) && typeof value.type === 'string';

/**
 * Visit every component a page carries, with its locatable path, parent before
 * children — the one traversal of a page's component tree the cross-reference
 * checks share (inline actions, #6889; master-detail detail columns, #20928;
 * line-items columns, #24190).
 * `visit` receives the node and its `properties` record; a node without one is
 * not visited, since every check here reads under `properties`.
 *
 * Three traversal facts make this a walk rather than a loop:
 *
 * - **Roots are plural.** Components hang off `regions[].components[]` AND off
 *   `slots.<name>`, where each slot is one component *or* an array of them.
 * - **Containers nest through a loose record.** `PageComponentSchema.properties`
 *   is `z.record(z.string(), z.unknown())`, and container props declare their
 *   children as `z.array(z.unknown())` (`children`, plus a card's `footer`), so
 *   a button nested inside a container survives parse as raw data. We recurse
 *   into any array under `properties` whose entries are component-shaped, which
 *   reaches a child list directly under `properties` without this walk naming
 *   its key.
 * - **Panels nest one record deeper.** A `page:tabs` or `page:accordion` node
 *   carries its components as `properties.items[].children`, and each item is
 *   a panel record (`{ label, value?, children }`), not a component, so the
 *   shape rule above stops at it. Where panels hang is not this walk's to
 *   list: it descends the panel positions of `pageComponentSlotPositions`
 *   (`ui/component.zod.ts`), the one list the component rows derive and the
 *   other page walks read (the exported `walkAddressedPageComponents`, the
 *   ADR-0087 conversion walker, lint's `walkPageComponents`), authorable
 *   spellings only, matched by shape on every component as they match it. A
 *   record under a key no row declares a panel list is not descended, nor is
 *   a key of a panel record no row declares: the renderer draws nothing from
 *   either, so nothing there is a component of the page.
 */
function forEachPageComponent(
  page: Record<string, unknown>,
  visit: (node: Record<string, unknown>, props: Record<string, unknown>, path: string) => void,
): void {
  const panelPositions = pageComponentSlotPositions().flatMap(({ key, panelKey, retired }) =>
    panelKey !== undefined && !retired ? [{ key, panelKey }] : []);

  const visitComponent = (node: unknown, path: string): void => {
    if (!isComponentNode(node)) return;
    const props = isRecord(node.properties) ? node.properties : undefined;
    if (!props) return;

    visit(node, props, path);

    for (const [key, value] of Object.entries(props)) {
      if (!Array.isArray(value)) continue;
      value.forEach((child, index) => {
        if (isComponentNode(child)) visitComponent(child, `${path}.properties.${key}.${index}`);
      });
    }

    // A panel list: only each panel's child list is descended, never the
    // panel record itself.
    for (const { key, panelKey } of panelPositions) {
      const panels = props[key];
      if (!Array.isArray(panels)) continue;
      panels.forEach((panel, index) => {
        const children = isRecord(panel) ? panel[panelKey] : undefined;
        if (!Array.isArray(children)) return;
        children.forEach((child, childIndex) => {
          visitComponent(child, `${path}.properties.${key}.${index}.${panelKey}.${childIndex}`);
        });
      });
    }
  };

  if (Array.isArray(page.regions)) {
    page.regions.forEach((region, regionIndex) => {
      if (!isRecord(region) || !Array.isArray(region.components)) return;
      region.components.forEach((component, componentIndex) => {
        visitComponent(component, `regions.${regionIndex}.components.${componentIndex}`);
      });
    });
  }

  if (isRecord(page.slots)) {
    for (const [slot, value] of Object.entries(page.slots)) {
      if (Array.isArray(value)) {
        value.forEach((component, index) => visitComponent(component, `slots.${slot}.${index}`));
      } else {
        visitComponent(value, `slots.${slot}`);
      }
    }
  }
}

/**
 * Every inline action a page's component tree carries, each with a locatable
 * path — the traversal `validateCrossReferences` needs and `config.actions`
 * cannot supply (#6889).
 *
 * An action authored **inline** on a page element (`element:button` →
 * `properties.action`, an {@link InlineActionSchema}) never enters
 * `config.actions`, so before this walk NO cross-reference check visited one: a
 * dangling `type: 'modal'` target built clean and failed only when a user
 * clicked, while the identical target on a *registered* action was a build
 * error. Inline is also the shape AI authoring emits most readily — a button
 * with its behaviour written right there — so it is the surface that most needs
 * authoring-time rejection.
 *
 * The traversal is {@link forEachPageComponent}'s: every root, every nesting,
 * a `page:tabs` or `page:accordion` item's `children` included.
 *
 * Candidates are normalized by parsing with `InlineActionSchema` rather than
 * read key-by-key: that schema's preprocess is what canonicalizes the legacy
 * `to` spelling onto `target`, and page-component `properties` are a loose
 * record, so a raw node has NOT been through it. Reading `action.target ??
 * action.to` here would be a second, hand-mirrored copy of the producer's
 * normalization — the consumer-side leniency Prime Directive #12 rejects.
 *
 * When that parse fails the node is still checked, from its raw `type`/`target`
 * strings. A node that is not a valid inline action is broken on some *other*
 * axis (a key page-component `properties` does not validate today), and the
 * fallback neither invents a target nor accepts one — it only keeps a dangling
 * reference from hiding behind an unrelated defect. The legacy `to` spelling is
 * deliberately NOT read there: canonicalization stays the schema's job.
 */
function collectInlinePageActions(page: unknown): InlineActionSite[] {
  if (!isRecord(page)) return [];
  const pageName = typeof page.name === 'string' ? page.name : '(unnamed)';
  const sites: InlineActionSite[] = [];

  forEachPageComponent(page, (_node, props, path) => {
    if (!isRecord(props.action)) return;
    const parsed = InlineActionSchema.safeParse(props.action);
    const action = parsed.success
      ? (parsed.data as InlineActionSite['action'])
      : {
        type: typeof props.action.type === 'string' ? props.action.type : undefined,
        name: typeof props.action.name === 'string' ? props.action.name : undefined,
        target: typeof props.action.target === 'string' ? props.action.target : undefined,
      };
    // An inline action's `name` is optional (the button supplies its own
    // label), so the path is the only identity an anonymous one has.
    const subject = action.name ? `Inline action '${action.name}'` : 'Inline action';
    sites.push({ action, where: `${subject} on page '${pageName}' (${path})` });
  });

  return sites;
}

/**
 * Scope segment of the runtime's action key for an object-less action.
 *
 * Must stay in lockstep with `GLOBAL_ACTION_OBJECT_KEY` in
 * `@objectstack/objectql` (`action-governance.ts`) — the literal `executeAction`
 * registers and looks up an object-less action under. Spelled here rather than
 * imported because the spec sits below every runtime package.
 */
const GLOBAL_ACTION_SCOPE = 'global';

/**
 * Join origins for a refusal line: `a`, `a and b`, `a, b and c`.
 */
function joinDeclarationOrigins(origins: readonly string[]): string {
  if (origins.length <= 1) return origins.join('');
  return `${origins.slice(0, -1).join(', ')} and ${origins[origins.length - 1]}`;
}

/**
 * Same-scope duplicate action keys — one refusal line per colliding key.
 *
 * The runtime registers and dispatches every action under one exact-string
 * key, `<scope>:<name>`, where the scope is the owning object's name or
 * {@link GLOBAL_ACTION_SCOPE} for an object-less action (`packages/objectql`'s
 * `executeAction`; the runtime's `collectActionDeclarations` and
 * `standaloneActionObjectName` build the same key), with no wildcard
 * semantics. Two declarations that resolve to one key collapse to one handler
 * registration: whichever registers second wins (`registerAction` is a plain
 * `Map.set`), and the other stays a live, declared, permission-gated button
 * whose handler is unreachable — nothing at author, build or boot time says
 * so, and the loser fails only when a user clicks it (the ADR-0078 shape
 * arriving at collection level). Measured on main before this check: two
 * standalone globals sharing a name, two standalone actions bound to the same
 * object, a bound standalone beside an embedded twin on the same object
 * (`mergeActionsIntoObjects` APPENDS, so both survived into `object.actions`)
 * and two embedded twins all built clean.
 *
 * Scope resolution follows the runtime's DECLARATION-RESOLUTION key: a
 * standalone action is scoped by its `objectName` (post-parse — the legacy
 * `object` alias is already canonicalized) or global; an embedded action is
 * scoped by the object it is written on, whatever its own `objectName` says —
 * that is how `collectActionDeclarations` and `resolveRouteActionDeclaration`
 * key it. (The REGISTRATION key — `collectBundleActions` /
 * `standaloneActionOwnerKey` — reads the action's own `objectName` instead; the
 * walk
 * deliberately follows the resolution side, where the by-name collision the
 * card describes happens.)
 *
 * Two embedded twins on ONE object never reach this walk on the strict path:
 * the object parse refuses them first (#26725, `duplicate-action-names.ts`),
 * because the object save door parses an object alone. This walk keeps the
 * pairs that span two collections.
 *
 * Every site counts, byte-identical twins included: the merge appends, so a
 * pair that is one declaration to the eye is two entries under one key in the
 * shipped artifact — `collectActionDeclarations` pushes every embedded entry,
 * MCP `listActions` lists both, and bare-name `resolveActionByName` refuses
 * the ambiguity. The identical case is therefore a delete, not a rename, and
 * the message says so. A consequence worth knowing: a stack BUILT by
 * `defineStack` carries each bound action in both positions, so feeding a
 * built stack back in is refused too — author the source shape, not the
 * artifact.
 *
 * Deliberately NOT refused: the cross-scope pair — one global and one
 * object-bound declaration sharing a `name`. They occupy two distinct keys, and
 * the precedence the runtime already implements for by-name readers
 * (`resolveRouteActionDeclaration` reads the object's own `actions` before a
 * standalone declaration) is documented on the `actions` collection, not
 * changed here.
 */
/**
 * An `operation: 'update'` action writes ONE record — the current one — on the
 * object it belongs to (#14092). Which object that is, `ActionSchema` cannot
 * tell: the same schema parses an action embedded on an object (the object is
 * implicit) and a standalone one in `stack.actions`, where only `objectName`
 * can say. So the standalone form is judged here, the one place standalone-
 * ness is knowable: a GLOBAL action (no `objectName`) has no current record
 * and nothing to write to, and is refused with the two spellings that do. An
 * embedded action is never visited — the object it is written on binds it.
 */
function collectGlobalUpdateActionErrors(config: ObjectStackDefinition): string[] {
  const errors: string[] = [];
  for (const [i, action] of (config.actions ?? []).entries()) {
    if (action.operation !== 'update' || action.objectName) continue;
    errors.push(
      `Action '${action.name}' (stack.actions[${i}]) is \`operation: 'update'\` — a single-record field write — `
      + 'but declares no `objectName`, so there is no object to write to: a global action has no current record. '
      + "Set `objectName: 'the_object'` (defineStack merges it into that object's actions) or declare it inside "
      + "the object's own `actions`.",
    );
  }
  return errors;
}

function collectDuplicateActionKeyErrors(config: ObjectStackDefinition): string[] {
  const originsByKey = new Map<string, string[]>();
  const note = (scope: string, name: string, origin: string): void => {
    const key = `${scope}:${name}`;
    const list = originsByKey.get(key) ?? [];
    list.push(origin);
    originsByKey.set(key, list);
  };

  for (const [i, action] of (config.actions ?? []).entries()) {
    if (action.objectName) {
      note(action.objectName, action.name, `stack.actions[${i}] (objectName '${action.objectName}')`);
    } else {
      note(GLOBAL_ACTION_SCOPE, action.name, `stack.actions[${i}] (no objectName, so scope '${GLOBAL_ACTION_SCOPE}')`);
    }
  }
  for (const obj of config.objects ?? []) {
    for (const [j, action] of (obj.actions ?? []).entries()) {
      note(obj.name, action.name, `objects['${obj.name}'].actions[${j}] (embedded on the object)`);
    }
  }

  const errors: string[] = [];
  for (const [key, origins] of originsByKey) {
    if (origins.length < 2) continue;
    errors.push(
      `Action key '${key}' is declared ${origins.length === 2 ? 'twice' : `${origins.length} times`}: ` +
        `${joinDeclarationOrigins(origins)}. The runtime registers and dispatches every action under ` +
        `this one exact-string key, so only one of these handlers is reachable and the other ` +
        `declaration is a dead button. Rename one of them within this scope, bind one to a ` +
        `different object, or remove the duplicate.`,
    );
  }
  return errors;
}

/**
 * Same-stack duplicate `functions` names in the ARRAY form (#22902) — one
 * refusal line per colliding name, naming the name and every index.
 *
 * Functions live in one flat namespace resolved by name: a hook's `handler`,
 * an action's `target` and a flow `script` node's `config.function` all look a
 * function up by its name, and the engine registers each under that name
 * (`registerFunction` is a plain `Map.set`). The map form cannot author one
 * name twice — an object key is unique — so it is never visited. The array
 * form can, and nothing refused it, so the two entries diverged silently and
 * differently on each path. Measured on main `7dbb89dc5` with
 * `[{ name: 'kc_a', handler: first }, { name: 'kc_a', handler: second }]`:
 *
 * - `objectstack build` exited 0 and shipped
 *   `[{ name: 'kc_a' }, { name: 'kc_a__2' }]`: `lowerCallables` mints refs in
 *   one namespace, so the second entry took a suffixed internal ref the author
 *   never wrote and nothing references — `kc_a` ran `first`;
 * - a source boot (no build) registered `kc_a` as `second` and dropped
 *   `first`, with no notice (`collectBundleFunctionEntries` keys by name, last
 *   wins).
 *
 * So the same stack ran different code under `kc_a` depending on whether it
 * was built. {@link composeStacks} already refuses the cross-stack case
 * (`composeFunctions`, `STACK_COMPOSE_FUNCTION_CONFLICT`); this is its
 * one-stack sibling, in the aggregate beside the action-key check. Every entry
 * counts, byte-identical twins included: two entries are two registrations
 * under one name whatever they hold, and only one can own it.
 */
function collectDuplicateFunctionNameErrors(config: ObjectStackDefinition): string[] {
  const functions = config.functions;
  if (!Array.isArray(functions)) return [];

  const indicesByName = new Map<string, number[]>();
  for (const [i, entry] of functions.entries()) {
    const list = indicesByName.get(entry.name) ?? [];
    list.push(i);
    indicesByName.set(entry.name, list);
  }

  const errors: string[] = [];
  for (const [name, indices] of indicesByName) {
    if (indices.length < 2) continue;
    errors.push(
      `Function '${name}' is declared ${indices.length === 2 ? 'twice' : `${indices.length} times`} ` +
        `in the \`functions\` array: ${joinDeclarationOrigins(indices.map((i) => `stack.functions[${i}]`))}. ` +
        `Functions are registered and resolved by name, so only one of these entries can own ` +
        `'${name}' and the others would be silently renamed or dropped. Rename one of them, or ` +
        `merge them into a single entry.`,
    );
  }
  return errors;
}

/**
 * Same-stack duplicate entries in the named collections (#22934) — one refusal
 * line per (collection, identity) collision, naming the collection, the
 * identity and every index. The sibling of the action-key and `functions`
 * checks above, for the 27 collections whose entries the runtime registers
 * under one identity each.
 *
 * Measured on main `246edf5b3` with every collection below carrying two entries
 * under one identity, on a source boot (`os serve`, no build) and through
 * `os build` → an artifact-backed boot: `defineStack` and `os validate`
 * accepted every pair (exit 0, `valid: true`, no finding naming it), and the
 * boot then kept one entry silently or diverged —
 *
 * - 23 collections, and `objectExtensions`, kept only the LAST entry on both
 *   paths, the earlier entries' content gone with no notice at the default log
 *   level;
 * - `datasources`: the metadata described the last entry while the driver
 *   connected with the first one's configuration;
 * - `hooks`: the metadata listed one hook while both handlers were bound and
 *   ran;
 * - `docs`: `os validate` and `os build` refused the pair (`docs/duplicate-name`)
 *   while a source boot kept the last.
 *
 * The identity is the string the registrars key an entry by: `name` for 24
 * collections, the `(name, locale)` pair for `emailTemplates` (an i18n bundle
 * is one name across several locales), the extended object (`extend`) for
 * `objectExtensions`, and for `views` the slot every registrar files the entry
 * under — an aggregated container under the object it binds to
 * ({@link deriveViewContainerObject}), any other entry under its own `name`,
 * falling back to the same derivation.
 * An entry with no readable identity claims no slot and is not counted.
 *
 * Deliberately NOT in the table, each for a reason that is not "nobody looked":
 * `plugins` (last-one-wins with one warn is the kernel's declared contract, and
 * plugins are host assembly, not artifact metadata); `agents` (withdrawn for
 * app packages, ADR-0063 §2 — the runtime never loads one); `picklistExtensions`
 * (the registry merges a package's contributions by option value and refuses a
 * duplicate value); `actions` and `functions` (their own checks above).
 *
 * Every entry counts, byte-identical twins included: two entries are two
 * registrations under one identity whatever they hold. The map form of a
 * map-supported collection reaches this check already normalized (key → `name`,
 * an explicit `name` winning), so two map keys whose entries spell one `name`
 * collide here too. Cross-package reuse of a name is untouched (ADR-0048 §3.4):
 * a multi-package project (`composeStacks(…, { manifest: 'preserve' })`)
 * carries each package's collections in its own `packages[i]` body, which this
 * check does not read. The same-package case is the one §3.4 leaves to
 * authoring-time hygiene (`os lint`'s duplicate-name advisory); it is refused
 * here at the contract, as the action-key check already does for actions.
 */
interface SameStackEntryIdentity {
  /** The identity the registrars key this collection's entries by, or `undefined` when an entry has none. */
  readonly identity: (entry: unknown) => string | undefined;
  /** The finding's subject for one identity: `Datasource 'x'`. */
  readonly subject: (identity: string) => string;
  /** What the runtime does with the pair, measured — one sentence. */
  readonly consequence: (identity: string) => string;
  /** The fix, one sentence. */
  readonly remedy: (identity: string) => string;
}

function readEntryName(entry: unknown): string | undefined {
  if (!entry || typeof entry !== 'object') return undefined;
  const name = (entry as { name?: unknown }).name;
  return typeof name === 'string' && name ? name : undefined;
}

const RENAME_OR_MERGE = (): string => 'Rename one of them, or merge them into a single entry.';

/** The 23 collections whose boot keeps the last entry under a name, on both paths. */
function lastWinsByName(noun: string, plural: string): SameStackEntryIdentity {
  return {
    identity: readEntryName,
    subject: (name) => `${noun} '${name}'`,
    consequence: () =>
      `The runtime registers ${plural} by name, so only the last of these entries is kept and the ` +
      `others are silently dropped.`,
    remedy: RENAME_OR_MERGE,
  };
}

const SAME_STACK_ENTRY_IDENTITY = Object.freeze({
  objects: lastWinsByName('Object', 'objects'),
  datasources: {
    identity: readEntryName,
    subject: (name) => `Datasource '${name}'`,
    consequence: () =>
      'The runtime registers datasources by name, and its two halves disagree on which entry won: ' +
      'the metadata describes the last of these entries while the driver connects with the first ' +
      "one's configuration.",
    remedy: RENAME_OR_MERGE,
  },
  pages: lastWinsByName('Page', 'pages'),
  dashboards: lastWinsByName('Dashboard', 'dashboards'),
  reports: lastWinsByName('Report', 'reports'),
  datasets: lastWinsByName('Dataset', 'datasets'),
  flows: lastWinsByName('Flow', 'flows'),
  jobs: lastWinsByName('Job', 'jobs'),
  // An i18n bundle is one `name` across several `locale` tags, so the identity
  // is the pair — the registry's `ITEM_KEY_DISCRIMINATORS` entry, keyed as
  // `name@locale` with an untagged entry keyed as the floor tag (the schema's
  // own default). Two entries collide only on one name AND one locale.
  emailTemplates: {
    identity: (entry) => {
      const name = readEntryName(entry);
      if (name === undefined) return undefined;
      const locale = (entry as { locale?: unknown }).locale;
      const tag = typeof locale === 'string' && locale.trim() ? locale.trim() : EMAIL_TEMPLATE_FLOOR_LOCALE;
      return `${name}@${tag}`;
    },
    subject: (key) => {
      const at = key.lastIndexOf('@');
      return `Email template '${key.slice(0, at)}' for locale '${key.slice(at + 1)}'`;
    },
    consequence: () =>
      'The runtime keys email templates by name and locale, so only the last of these entries is kept ' +
      'for that locale and the others are silently dropped.',
    remedy: () =>
      'Rename one of them, give each its own `locale` (one entry per locale is an i18n bundle), or merge ' +
      'them into a single entry.',
  },
  books: lastWinsByName('Book', 'books'),
  positions: lastWinsByName('Position', 'positions'),
  permissions: lastWinsByName('Permission set', 'permission sets'),
  capabilities: lastWinsByName('Capability', 'capabilities'),
  sharingRules: lastWinsByName('Sharing rule', 'sharing rules'),
  queues: lastWinsByName('Queue', 'queues'),
  assignmentRules: lastWinsByName('Assignment rule', 'assignment rules'),
  webhooks: lastWinsByName('Webhook', 'webhooks'),
  hooks: {
    identity: readEntryName,
    subject: (name) => `Hook '${name}'`,
    consequence: () =>
      'The metadata keeps only the last of these entries under that name, yet every entry\'s handler ' +
      'is still bound and runs, so what the metadata lists is not what executes.',
    remedy: RENAME_OR_MERGE,
  },
  mappings: lastWinsByName('Mapping', 'mappings'),
  analyticsCubes: lastWinsByName('Analytics cube', 'analytics cubes'),
  connectors: lastWinsByName('Connector', 'connectors'),
  picklists: lastWinsByName('Picklist', 'picklists'),
  docs: lastWinsByName('Doc', 'docs'),
  tools: lastWinsByName('Tool', 'tools'),
  skills: lastWinsByName('Skill', 'skills'),
  views: {
    identity: (entry) =>
      isAggregatedViewContainer(entry)
        ? deriveViewContainerObject(entry)
        : readEntryName(entry) ?? deriveViewContainerObject(entry),
    subject: (object) => `View container '${object}'`,
    consequence: () =>
      'The runtime files a `views` container under the object it binds to (`object`, else ' +
      '`list.data.object`, else `form.data.object`, else its `name`), so these entries occupy one ' +
      'registry slot and only the last of them is kept in it.',
    remedy: () =>
      'Keep one container per object: merge their `list`, `form`, `listViews` and `formViews` into a ' +
      'single entry.',
  },
  apis: {
    identity: readEntryName,
    subject: (name) => `API endpoint '${name}'`,
    consequence: () =>
      "The runtime indexes endpoints by name, so only the last of these entries is routed and the " +
      "others' paths answer 404.",
    remedy: () => 'Give each endpoint its own name.',
  },
  apps: lastWinsByName('App', 'apps'),
  objectExtensions: {
    identity: (entry) => {
      if (!entry || typeof entry !== 'object') return undefined;
      const extend = (entry as { extend?: unknown }).extend;
      return typeof extend === 'string' && extend ? extend : undefined;
    },
    subject: (object) => `Object extension of '${object}'`,
    consequence: () =>
      'The runtime applies one extension of a target object per package, so only the last of these ' +
      "entries' fields register and the others' are silently dropped.",
    remedy: (object) => `Merge them into a single \`objectExtensions\` entry for '${object}'.`,
  },
} satisfies Partial<Record<keyof ObjectStackDefinition, SameStackEntryIdentity>>);

function collectDuplicateEntryErrors(config: ObjectStackDefinition): string[] {
  const errors: string[] = [];
  for (const [key, rule] of Object.entries(SAME_STACK_ENTRY_IDENTITY) as [
    keyof typeof SAME_STACK_ENTRY_IDENTITY,
    SameStackEntryIdentity,
  ][]) {
    const entries: unknown = config[key];
    if (!Array.isArray(entries)) continue;

    const indicesByIdentity = new Map<string, number[]>();
    for (const [i, entry] of entries.entries()) {
      const identity = rule.identity(entry);
      if (identity === undefined) continue;
      const list = indicesByIdentity.get(identity) ?? [];
      list.push(i);
      indicesByIdentity.set(identity, list);
    }

    for (const [identity, indices] of indicesByIdentity) {
      if (indices.length < 2) continue;
      errors.push(
        `${rule.subject(identity)} is declared ${indices.length === 2 ? 'twice' : `${indices.length} times`} ` +
          `in \`${key}\`: ${joinDeclarationOrigins(indices.map((i) => `stack.${key}[${i}]`))}. ` +
          `${rule.consequence(identity)} ${rule.remedy(identity)}`,
      );
    }
  }
  return errors;
}

/**
 * Two or more DEFAULT RECORD PAGES for one object (#23015, maintainer ruling A,
 * record 6134056653) — one refusal line per object, naming every page and where
 * each sits.
 *
 * At most one `isDefault: true` record page may exist for an object in a
 * deployment (`PageSchema.isDefault`): the renderer opens an object's record
 * view on its default record page with no tie-break, so with two the choice
 * would fall to registration order, which no author wrote. One stack is one
 * package, so two defaults in it are two defaults in every deployment that
 * installs it. "Default record page of object X" is the one reading
 * {@link defaultRecordPageObject} gives — the same one the registry's package
 * door and the metadata save door ask — so this door cannot pass a stack those
 * doors refuse, nor refuse one they accept.
 *
 * Counted by distinct page NAME within one package: two entries under one name
 * are the duplicate {@link collectDuplicateEntryErrors} already refuses, and are
 * not reported a second time here. An entry carrying a `holder` (the package it
 * lands in) is counted by that package and name, since two packages' pages
 * under one name are two pages (ADR-0048 §3.4). The object need not be one this stack defines (a stack may
 * ship the record page of a platform object), so this runs before the
 * object-count early return.
 *
 * `origins` labels each page's position for the finding (`stack.pages[3]`);
 * {@link collectComposedDefaultRecordPageErrors} reuses the reading over the
 * pages a composition brings together, with its own labels.
 */
function duplicateDefaultRecordPageFindings(
  entries: Iterable<{ readonly page: unknown; readonly origin: string; readonly holder?: string }>,
  scope: string,
): string[] {
  // object → page identity → { name, origins }. The identity is the page name,
  // or `holder|name` where the caller says which package an entry lands in.
  const byObject = new Map<string, Map<string, { name: string; origins: string[] }>>();
  for (const { page, origin, holder } of entries) {
    const object = defaultRecordPageObject(page);
    if (object === undefined) continue;
    const name = readEntryName(page);
    if (name === undefined) continue;
    const pages = byObject.get(object) ?? new Map<string, { name: string; origins: string[] }>();
    const key = holder === undefined ? name : `${holder}|${name}`;
    const found = pages.get(key) ?? { name, origins: [] };
    found.origins.push(origin);
    pages.set(key, found);
    byObject.set(object, pages);
  }

  const errors: string[] = [];
  for (const [object, pages] of byObject) {
    if (pages.size < 2) continue;
    const named = [...pages.values()].map(({ name, origins }) => `'${name}' (${joinDeclarationOrigins(origins)})`);
    errors.push(
      `Object '${object}' has ${pages.size === 2 ? 'two' : pages.size} default record pages in ${scope}: ` +
        `${joinDeclarationOrigins(named)}. Set \`isDefault: false\` on all but one of them. At most one ` +
        `record page may be \`isDefault: true\` for an object in a deployment: the record view opens that ` +
        `page with no tie-break, so with two the choice would fall to registration order.`,
    );
  }
  return errors;
}

/** The one-stack door: {@link duplicateDefaultRecordPageFindings} over `stack.pages`. */
function collectDuplicateDefaultRecordPageErrors(config: ObjectStackDefinition): string[] {
  const pages: unknown = config.pages;
  if (!Array.isArray(pages)) return [];
  return duplicateDefaultRecordPageFindings(
    pages.map((page, i) => ({ page, origin: `stack.pages[${i}]` })),
    '`pages`',
  );
}

/**
 * The composition door: {@link duplicateDefaultRecordPageFindings} over every
 * INPUT stack's `pages` together. Each input passed the one-stack door on its
 * own, and the pages they bring together land in one deployment — as one
 * package (the default manifest strategies, which concatenate `pages`) or as
 * several packages of one artifact (`manifest: 'preserve'`), where the
 * registry's package door would refuse the boot. Refused here first, in the
 * cross-reference envelope, so `os validate` and `os build` of a composed
 * project say what the boot would. An input whose `pages` is not an array is
 * skipped here: the concat pass refuses it by its own rule.
 */
function collectComposedDefaultRecordPageErrors(
  stacks: readonly ObjectStackDefinition[],
  preserve: boolean,
): string[] {
  const entries: Array<{ page: unknown; origin: string; holder?: string }> = [];
  for (const [i, stack] of stacks.entries()) {
    const pages: unknown = stack.pages;
    if (!Array.isArray(pages)) continue;
    for (const [j, page] of pages.entries()) {
      entries.push({
        page,
        origin: `${stackLabel(stack, i)} pages[${j}]`,
        // Under `preserve` each input stays its own package, so a page name two
        // inputs share is two pages; merged, it is one package's one name.
        ...(preserve ? { holder: String(i) } : {}),
      });
    }
  }
  return duplicateDefaultRecordPageFindings(entries, 'the composed stacks');
}

/**
 * [#25234 ruling A, refusal 3] One membership key declared on two objects.
 *
 * `current_user.KEY` is one request-wide name (`ExecutionContext.rlsMembership`
 * is a single bag), and `ObjectSchema.membershipKeys` gives the key its meaning
 * from the declaring object's rows. Two objects declaring one key would give it
 * two meanings with no author choosing between them, so the second declaration
 * is refused. One object cannot declare a key twice (the map is keyed by name);
 * this is the cross-object half.
 *
 * Counted by distinct object NAME, so two entries for one object are the
 * duplicate {@link collectDuplicateEntryErrors} (or the composition's object
 * conflict strategy) already answers, and are not reported a second time.
 * {@link collectComposedMembershipKeyErrors} reuses the reading over the objects
 * a composition brings together.
 */
function duplicateMembershipKeyFindings(
  entries: Iterable<{ readonly object: unknown; readonly origin: string }>,
  scope: string,
): string[] {
  // key → declaring object name → the positions that declare it there.
  const byKey = new Map<string, Map<string, string[]>>();
  for (const { object, origin } of entries) {
    if (!isRecord(object) || typeof object.name !== 'string') continue;
    const keys = object.membershipKeys;
    if (!isRecord(keys)) continue;
    for (const key of Object.keys(keys)) {
      const owners = byKey.get(key) ?? new Map<string, string[]>();
      const origins = owners.get(object.name) ?? [];
      origins.push(origin);
      owners.set(object.name, origins);
      byKey.set(key, owners);
    }
  }

  const errors: string[] = [];
  for (const [key, owners] of byKey) {
    if (owners.size < 2) continue;
    const named = [...owners].map(([object, origins]) => `'${object}' (${joinDeclarationOrigins(origins)})`);
    errors.push(
      `Membership key '${key}' is declared on ${owners.size === 2 ? 'two' : owners.size} objects in ${scope}: ` +
        `${joinDeclarationOrigins(named)}. Declare it on exactly one object, the roster whose rows define it, ` +
        `and rename the others. \`current_user.${key}\` is one request-wide name, so two declarations would ` +
        `give it two meanings.`,
    );
  }
  return errors;
}

/** The one-stack door: {@link duplicateMembershipKeyFindings} over `stack.objects`. */
function collectDuplicateMembershipKeyErrors(config: ObjectStackDefinition): string[] {
  const objects: unknown = config.objects;
  if (!Array.isArray(objects)) return [];
  return duplicateMembershipKeyFindings(
    objects.map((object, i) => ({ object, origin: `stack.objects[${i}]` })),
    '`objects`',
  );
}

/**
 * The composition door: {@link duplicateMembershipKeyFindings} over the
 * objects the composed artifact carries (after the object conflict strategy,
 * so an object `'override'` replaced no longer counts, and one `'merge'`
 * combined counts once). Each input passed the one-stack door alone; the key
 * namespace is the deployment's, so two inputs declaring one key on two
 * objects is refused here, under every manifest strategy. Each object is
 * labelled with the input stacks that define it.
 */
function collectComposedMembershipKeyErrors(
  stacks: readonly ObjectStackDefinition[],
  composedObjects: readonly unknown[] | undefined,
): string[] {
  if (!Array.isArray(composedObjects)) return [];
  const definedBy = new Map<string, string[]>();
  for (const [i, stack] of stacks.entries()) {
    for (const name of collectObjectNames(stack)) {
      definedBy.set(name, [...(definedBy.get(name) ?? []), stackLabel(stack, i)]);
    }
  }
  return duplicateMembershipKeyFindings(
    composedObjects.map((object) => ({
      object,
      origin: joinDeclarationOrigins(
        definedBy.get(isRecord(object) && typeof object.name === 'string' ? object.name : '') ?? ['the composition'],
      ),
    })),
    'the composed stacks',
  );
}

/**
 * [ADR-0112 · #15963] The envelope every refusal `defineStack` raises shares:
 * `status: 422` — an unprocessable authored entity, not a server fault, the
 * reading {@link StackCrossReferenceError} took from its two precedents — ONE
 * `code` per refusal site, and the findings that site collected in `issues`,
 * one entry per finding. Until #15963 only the cross-reference refusal carried
 * the envelope; its six siblings a few lines apart threw `new Error(message)`
 * with `code` and `status` both `undefined`, so a consumer that had learned to
 * branch on `error.code` read `undefined` from six of the seven and could not
 * tell "not a refusal" from "a refusal with no code yet".
 *
 * ⭐ One code per site, never a shared `STACK_VALIDATION_FAILED` catch-all:
 * the ledger's `boot-refusal` class is already at one-row-per-refusal
 * granularity (14 rows on the tree this landed against), and
 * `STACK_CROSS_REFERENCE_INVALID` is an instance of that granularity, not an
 * exception to it. Each member's `code` is spelled `STACK_<subject>_<condition>`
 * in the ledger's own suffix vocabulary.
 *
 * ⛔ Module-local, like its first member: `packages/spec/src/index.ts`
 * re-exports this module with `export *`, and the ADR-0112 contract is the
 * `code` / `status` pair, read structurally by every consumer.
 *
 * ⛔ Never name a member `ValidationError`: `validationFailureDetails`
 * (`@objectstack/types`) duck-types a RECORD-validation failure on that `name`
 * and would answer `400 VALIDATION_FAILED` + `fields[]` for it.
 *
 * Every member is registered in the ADR-0112 ledger under `@objectstack/spec`
 * (#16449, under the #16404 ruling: a `code` that ships in `dist` is the
 * published face, door or no door — a consumer's `catch (e) { switch (e.code) }`
 * pins the spelling the moment it ships). No wire door raises them —
 * `defineStack` runs at authoring and boot time (see the first member's note)
 * — so the registration widens `ErrorCode` without changing any HTTP body;
 * `check:dispatcher-error-vocabulary` holds every `packages/spec/src` stamp
 * site to that ledger.
 *
 * `issues` is HETEROGENEOUS across members, on purpose: the six semantic
 * refusals carry one string per finding, the schema arm carries the zod issue
 * objects — `TIssue` names which, and a reader branches on `code` before it
 * reads `issues`, never on the element shape.
 */
abstract class StackRefusalError<TIssue = string> extends Error {
  abstract readonly code: string;
  readonly status = 422;
  /** One entry per finding, in the order the validator collected them. */
  readonly issues: readonly TIssue[];

  protected constructor(name: string, message: string, issues: readonly TIssue[]) {
    super(message);
    this.name = name;
    this.issues = issues;
  }
}

/**
 * [ADR-0112] The cross-reference refusal `defineStack` raises when a stack's
 * items name objects the stack does not define — carried as an envelope
 * (`code` + `status`), never a bare `Error`.
 *
 * Before it carried one, all five REFUSED item classes of the ADR-0130 matrix
 * (action `objectName`, view `data.object`, permission-set `objects`, seed
 * dataset `object`, import mapping `targetObject`) plus the `hooks[].object`
 * rule threw `new Error(message)` with `code` and `status` both `undefined`,
 * so they were distinguishable only by MESSAGE TEXT — the fragile shape the
 * ADR-0112 envelope exists to remove, and one that five message-substring pins
 * had already come to depend on.
 *
 * ⭐ Why the code names the rule FAMILY and not one item class: a raise site
 * throws an AGGREGATE. {@link validateCrossReferences} returns every finding as
 * a `string[]` and `defineStack` throws the whole set at once, so a single
 * refusal can carry findings from several classes together — a per-class code
 * would have to pick one of several true answers. The classes stay
 * machine-readable in {@link StackCrossReferenceError.issues}, one entry per
 * finding, which is the structured form of what was previously only
 * newline-joined prose. The family is also WIDER than "undefined object": the
 * same aggregate carries the duplicate-action-key, duplicate-function-name,
 * global-`update`-action and mapping `javascript`-transform findings, so a
 * `…_UNDEFINED_OBJECT` spelling would be false for those.
 *
 * ⭐ There are TWO raise sites since #18202, one per PASS, and they share this
 * code deliberately — same rule family, same finding text, two resolution
 * scopes:
 *
 * - `defineStack` — the PER-STACK pass. Header:
 *   `defineStack cross-reference validation failed (N issues):`.
 * - `composeStacks` — the ARTIFACT pass, which re-raises the two
 *   ARTIFACT-SCOPED rules ({@link collectSeedDataObjectErrors},
 *   {@link collectPermissionGrantObjectErrors}) over the composed object set,
 *   so a reference that {@link DefineStackOptions.artifactObjects} let past the
 *   per-stack pass is still refused when NO package in the artifact defines it.
 *   Header: `composeStacks artifact cross-reference validation failed (N issues):`.
 *
 * The HEADER names the pass, which is what a reader needs to know; the `code`
 * names the rule family, which is what a machine matches on. Splitting the code
 * per pass would make the pass — not the defect — the machine-readable half.
 *
 * `status: 422` matches both precedents for this defect class
 * (`ObjectOwnershipConflictError`, `NamespaceConflictError` in
 * `packages/objectql/src/registry.ts`) — an unprocessable authored entity, not
 * a server fault.
 *
 * ⛔ Deliberately NOT exported. `packages/spec/src/index.ts` re-exports this
 * module with `export *`, so exporting this class would widen the PUBLISHED
 * api-surface of the contract package; the ADR-0112 contract is the `code` /
 * `status` fields, which every reader — `resolveThrownHttpError` and this
 * repo's rejection pins alike — reads structurally rather than by `instanceof`.
 * Export it the day a consumer needs the narrowed type, as its own change.
 *
 * Registered in the ADR-0112 ledger under `@objectstack/spec` since #16449
 * (the #16404 ruling; before it the code shipped unregistered — recorded as
 * under-tiered on #14552 and not reopened). No wire door raises it:
 * `defineStack` runs at authoring and boot time (`os validate`, `os build`,
 * the `os serve` / `os migrate` host configs and `DevPlugin`); no HTTP domain
 * handler calls it. The ledger row carries that reachability reading.
 *
 * Since #15963 the envelope half (`status`, `issues`) lives on
 * {@link StackRefusalError}, which every `defineStack` refusal now extends;
 * this class keeps its `code`, its `name` and its message byte-for-byte.
 */
class StackCrossReferenceError extends StackRefusalError {
  readonly code = 'STACK_CROSS_REFERENCE_INVALID';

  constructor(message: string, issues: readonly string[]) {
    super('StackCrossReferenceError', message, issues);
  }
}

/**
 * [ADR-0112 · #15963] The SCHEMA refusal — `ObjectStackDefinitionSchema.safeParse`
 * itself failed. ⭐ Judged on its own rather than copied from the five semantic
 * cross-checks below, because it is a different kind of failure: an aggregate
 * of zod issues against the schema the stack declares, not a rule evaluated on
 * an already-parsed stack. The reading that settled its shape, taken on the
 * tree this landed against:
 *
 * - `packages/spec` has NO zod-failure envelope to reuse. `formatZodError` /
 *   `safeParsePretty` are prose formatters (they return a string); every
 *   `extends Error` in this package is a domain refusal and none wraps a
 *   `ZodError`. So "reuse spec's existing zod-failure channel" names a
 *   channel that does not exist — the only existing channel is the message.
 * - The two zod-shaped refusals the ADR-0112 ledger DOES carry are both spelled
 *   `*_SCHEMA_INVALID`: `METADATA_SCHEMA_INVALID` (`SchemaValidationError` in
 *   `@objectstack/metadata-core` — "a put's spec fails Zod validation against
 *   the canonical schema", carrying the zod `issues` structurally; its docstring
 *   says 422 but nothing in the tree assigns it a status) and
 *   `FLOW_INPUT_SCHEMA_INVALID` ("a node's config contradicts the schema the
 *   definition itself declares", answered 422 by
 *   `packages/runtime/src/flow-dispatch-status.ts`). The zod-shaped refusal
 *   `metadata-protocol` actually stamps at 422 is `INVALID_METADATA`
 *   (`protocol.ts`, `runtime-authoring-gate.ts`). An authored stack failing its
 *   own schema is that class exactly: the `issues` shape from the first, the
 *   422 from the other two.
 * - The other two channels a zod failure travels on in this repo are both the
 *   wrong vocabulary here. `400 VALIDATION_ERROR` is the REQUEST-syntax bucket
 *   (`packages/rest` answers a malformed body with it, passing raw zod issue
 *   codes through as field errors — ADR-0112 D6); `defineStack` serves no
 *   request. `VALIDATION_FAILED` + `fields[]` is objectql's RECORD-validation
 *   vocabulary, and `validationFailureDetails` (`@objectstack/types`)
 *   recognises it by duck-typing on `code` OR `name === 'ValidationError'` —
 *   reusing it would make "this stack is mis-authored" indistinguishable from
 *   "this record write was refused" to every reader of the dispatcher's
 *   envelope, the exact conflation an `error.code` exists to prevent.
 *
 * So: its own arm, `STACK_SCHEMA_INVALID`, `status: 422` like every other
 * `defineStack` refusal, and `issues` carrying the zod issues STRUCTURALLY
 * (path + code + message per entry — what `SchemaValidationError.issues`
 * carries and what `zodIssuesToFields` consumes) rather than the formatted
 * lines: the message already renders those, and the envelope's job is the
 * machine-readable half. The issue COUNT the header states is `issues.length`
 * either way. The message text is byte-for-byte what the bare `Error` carried.
 */
class StackSchemaInvalidError extends StackRefusalError<z.core.$ZodIssue> {
  readonly code = 'STACK_SCHEMA_INVALID';

  constructor(message: string, issues: readonly z.core.$ZodIssue[]) {
    super('StackSchemaInvalidError', message, issues);
  }
}

/**
 * [ADR-0112 · #15963] `requires` names a token no runtime provides —
 * {@link validateKnownCapabilities}. One entry per DISTINCT unknown token, in
 * declaration order.
 */
class StackCapabilityUnknownError extends StackRefusalError {
  readonly code = 'STACK_CAPABILITY_UNKNOWN';

  constructor(message: string, issues: readonly string[]) {
    super('StackCapabilityUnknownError', message, issues);
  }
}

/**
 * [ADR-0112 · #15963] An object's name lacks the `manifest.namespace` prefix —
 * {@link validateNamespacePrefix}. The writing-style hint the message appends
 * stays in the message only; `issues` carries the per-object findings.
 */
class StackNamespacePrefixInvalidError extends StackRefusalError {
  readonly code = 'STACK_NAMESPACE_PREFIX_INVALID';

  constructor(message: string, issues: readonly string[]) {
    super('StackNamespacePrefixInvalidError', message, issues);
  }
}

/**
 * [ADR-0112 · #15963] An `app` package declares more than one app — the banned
 * "suite contains apps" shape, ADR-0019 (app-as-consumer-unit) D3 —
 * {@link validateSingleApp}.
 * Spelled `_VIOLATION` like the ledger's other rule-violation refusals
 * (`UNIQUE_VIOLATION`, `EXTERNAL_SCHEMA_MODE_VIOLATION`).
 */
class StackSingleAppViolationError extends StackRefusalError {
  readonly code = 'STACK_SINGLE_APP_VIOLATION';

  constructor(message: string, issues: readonly string[]) {
    super('StackSingleAppViolationError', message, issues);
  }
}

/**
 * [ADR-0112 · #15963] A permission grant uses a HIERARCHY scope while `requires`
 * omits `hierarchy-security` — {@link validateHierarchyScopeCapability}, the
 * declared-capability class that fails CLOSED. Spelled `_REQUIRED` like the
 * ledger's other "a declaration is owed and absent" refusals
 * (`WRITABLE_PACKAGE_REQUIRED`).
 */
class StackHierarchyScopeCapabilityRequiredError extends StackRefusalError {
  readonly code = 'STACK_HIERARCHY_SCOPE_CAPABILITY_REQUIRED';

  constructor(message: string, issues: readonly string[]) {
    super('StackHierarchyScopeCapabilityRequiredError', message, issues);
  }
}

/**
 * [ADR-0112 · #15963] An auto-launched flow is declared while `requires` omits
 * `triggers`, `automation`, or both — the pair that installs its trigger
 * (#20332) — {@link validateTriggerCapability}, the declared-capability class
 * that fails SILENT. One code for every arm: which token is missing is in the
 * finding, not in the code. Same `_REQUIRED` spelling as its hierarchy sibling.
 */
class StackTriggerCapabilityRequiredError extends StackRefusalError {
  readonly code = 'STACK_TRIGGER_CAPABILITY_REQUIRED';

  constructor(message: string, issues: readonly string[]) {
    super('StackTriggerCapabilityRequiredError', message, issues);
  }
}

/**
 * [ADR-0112 · ruling A on #24910] A webhook is declared while `requires` omits
 * `webhooks`, `realtime`, or both — the pair that dispatches it —
 * {@link validateWebhookCapability}, the third declared-capability refusal and,
 * like its trigger sibling, of the class that fails SILENT. One code for every
 * arm: which token is missing is in the finding, not in the code. Same
 * `_REQUIRED` spelling as its trigger and hierarchy siblings.
 */
class StackWebhookCapabilityRequiredError extends StackRefusalError {
  readonly code = 'STACK_WEBHOOK_CAPABILITY_REQUIRED';

  constructor(message: string, issues: readonly string[]) {
    super('StackWebhookCapabilityRequiredError', message, issues);
  }
}

/**
 * [ADR-0131 D6 · ADR-0112] A package permits the `unmanaged` install mode
 * while it carries what an unmanaged install cannot copy —
 * {@link validateUnmanagedInstallMode}. Spelled in this family's `STACK_*`
 * vocabulary, one code per raise site; its install-time counterpart is
 * `UNMANAGED_INSTALL_UNCOPYABLE` (`importUnmanagedPackage`,
 * `@objectstack/metadata-protocol`), which judges the same body with the same
 * key classification (`kernel/unmanaged-install.ts`).
 */
class StackUnmanagedInstallUncopyableError extends StackRefusalError {
  readonly code = 'STACK_UNMANAGED_INSTALL_UNCOPYABLE';

  constructor(message: string, issues: readonly string[]) {
    super('StackUnmanagedInstallUncopyableError', message, issues);
  }
}

/**
 * [ADR-0112 · #20367 ruling B] `composeStacks` refuses an input no stack
 * producer built — the composition half of the one-authoring-shape rule
 * (`stack-provenance.ts` states it). The per-stack refusals above run only
 * inside `defineStack`, so an input that never passed through it arrives
 * unjudged; composing it would publish those findings nowhere. `issues` carries
 * one entry per refused input, naming it the way every other composition
 * refusal does.
 *
 * The SAME code `os validate` / `os build` raise for an unmarked default export
 * (`@objectstack/cli`, `utils/stack-provenance-refusal.ts`): one condition, one
 * vocabulary, two emitters — the `ENVIRONMENT_NOT_FOUND` precedent in the
 * ADR-0112 ledger. Module-local like every member above.
 */
class StackProvenanceMissingError extends StackRefusalError {
  readonly code = 'STACK_PROVENANCE_MISSING';

  constructor(message: string, issues: readonly string[]) {
    super('StackProvenanceMissingError', message, issues);
  }
}

/**
 * [ADR-0112 · #16348] The COMPOSITION half of the refusal family above. `composeStacks`
 * refuses six authored-entity conflicts, every one of them carrying the
 * literal `composeStacks conflict:` message prefix, and until this change
 * every one threw `new Error(message)` with `code` and `status` both
 * `undefined` — the silent shape the `defineStack` family shed one screen up,
 * in this same file. Two refusal families that are the same thing to an author
 * and two different things to a consumer is the asymmetry these six close.
 *
 * The envelope is the SAME one — {@link StackRefusalError}: `status: 422`, an
 * unprocessable authored entity rather than a server fault, and the findings
 * the site collected on `issues`, one entry per finding. The granularity is
 * the one the per-stack family landed with and the triage reading that set it:
 * ONE code per refusal site, never a shared `STACK_COMPOSE_CONFLICT`
 * catch-all. The `boot-refusal` class in the dispatcher vocabulary was already
 * at one-row-per-refusal granularity when that reading was taken, and
 * {@link StackCrossReferenceError} is an instance of that granularity rather
 * than an exception to it.
 *
 * ⭐ Why every member spells `STACK_COMPOSE_*` instead of continuing the
 * per-stack family's `STACK_<subject>_<condition>`: what these six refuse is a
 * disagreement BETWEEN stacks, a condition `defineStack` cannot raise at all —
 * each input is legal on its own, and the fix is always in the composition or
 * in one of the two authors' packages, never in a single malformed stack. A
 * bare `STACK_OBJECT_CONFLICT` would read as "this stack's object is
 * malformed" and send a consumer to the wrong half of the artifact.
 * {@link StackCrossReferenceError} is the deliberate exception in the other
 * direction: its two raise sites (the per-stack pass and the ARTIFACT pass
 * inside {@link composeStacks}) share one code because they are one rule
 * family evaluated over two scopes, so the code names the rule and the message
 * header names the pass.
 *
 * ⛔ The seventh bare `Error` in this file stays bare, and that is a reading
 * rather than an omission: `composeStacks internal error: no source stack
 * recorded for composed object …` inside
 * {@link collectComposedActionKeyCollisions} is the code discovering its own
 * bookkeeping is inconsistent, not an authored entity being refused. A 422
 * would tell an author their stack is unprocessable when the defect is ours.
 * Whether it takes a 500-class envelope of its own is a separate decision.
 *
 * Every member is registered in the ADR-0112 ledger under `@objectstack/spec`
 * (the #16404 ruling: a `code` that ships in `dist` is the published face,
 * door or no door — a consumer's `catch (e) { switch (e.code) }` pins the
 * spelling the moment it ships). `door: 'none'`, re-measured on the tree this
 * landed against: `composeStacks` occurs 7 times in non-test
 * `packages/runtime/src` + `packages/rest/src` source, all of them doc
 * comments or message prose in one file and NONE of them a call site, with
 * `defineStack` lighting the same probe 31 times across 8 files as the
 * positive control. The only non-test caller on the tree is an example's
 * `objectstack.config.ts`, which is authoring time by construction.
 *
 * ⛔ Module-local like every member above, and for the same reason:
 * `packages/spec/src/index.ts` re-exports this module with `export *`, so an
 * exported class would widen the published api-surface, while the ADR-0112
 * contract is the `code` / `status` pair every reader takes structurally.
 *
 * Message text is byte-for-byte what each bare `Error` carried. This adds the
 * machine-readable half; it rewords no sentence, and the message-substring
 * pins across this repo read the prose they always did.
 */
class StackComposeKeyConflictError extends StackRefusalError {
  readonly code = 'STACK_COMPOSE_KEY_CONFLICT';

  constructor(message: string, issues: readonly string[]) {
    super('StackComposeKeyConflictError', message, issues);
  }
}

/**
 * [ADR-0112 · #16348] `functions` is authored in the map form by one stack and the
 * array form by another — {@link composeFunctions}. The two shapes are merged
 * in kind and never converted, so the refusal is about the SHAPE, which is
 * what the code says; a same-shape duplicate name is its sibling below.
 */
class StackComposeFunctionsShapeConflictError extends StackRefusalError {
  readonly code = 'STACK_COMPOSE_FUNCTIONS_SHAPE_CONFLICT';

  constructor(message: string, issues: readonly string[]) {
    super('StackComposeFunctionsShapeConflictError', message, issues);
  }
}

/**
 * [ADR-0112 · #16348] Two stacks define a handler under the same name —
 * {@link composeFunctions}. Handlers resolve by name at boot, so composing
 * them would let one silently shadow the other.
 */
class StackComposeFunctionConflictError extends StackRefusalError {
  readonly code = 'STACK_COMPOSE_FUNCTION_CONFLICT';

  constructor(message: string, issues: readonly string[]) {
    super('StackComposeFunctionConflictError', message, issues);
  }
}

/**
 * [ADR-0112 · #16348] Under `objectConflict: 'merge'`, a later stack declares an
 * object-level collection — or, since #16075, a fixed-shape config object —
 * the composed object already carries with a DIFFERENT value —
 * {@link refuseUnmergeableCollections}. Only `fields` is shallow-merged; every
 * other collection or config object would be replaced wholesale. Spelled for
 * the key, not the object: the object itself composes fine, one of its
 * collections or config objects does not. The code keeps its #14848 name for
 * both kinds — one raise site, one refusal.
 */
class StackComposeCollectionConflictError extends StackRefusalError {
  readonly code = 'STACK_COMPOSE_COLLECTION_CONFLICT';

  constructor(message: string, issues: readonly string[]) {
    super('StackComposeCollectionConflictError', message, issues);
  }
}

/**
 * [ADR-0112 · #16348] The same object name is defined by more than one stack under the
 * DEFAULT `objectConflict: 'error'` strategy — {@link mergeObjects}. The
 * message names the two options that resolve it; the refusal is the strategy
 * doing its job, which is why it carries the same envelope as the rest rather
 * than a distinct class of its own.
 */
class StackComposeObjectConflictError extends StackRefusalError {
  readonly code = 'STACK_COMPOSE_OBJECT_CONFLICT';

  constructor(message: string, issues: readonly string[]) {
    super('StackComposeObjectConflictError', message, issues);
  }
}

/**
 * [ADR-0112 · #16348] Two stacks declare the same action key — the collision
 * `defineStack` refuses within one stack, arriving one composition step later
 * ({@link collectComposedActionKeyCollisions}). `issues` carries exactly what
 * that walk collected: one entry per colliding key, naming every declaring
 * stack and site, the same list the message renders as `✗` lines.
 */
class StackComposeActionKeyCollisionError extends StackRefusalError {
  readonly code = 'STACK_COMPOSE_ACTION_KEY_COLLISION';

  constructor(message: string, issues: readonly string[]) {
    super('StackComposeActionKeyCollisionError', message, issues);
  }
}

/**
 * Seed data → object references (#18202, ARTIFACT-SCOPED — see
 * {@link DefineStackOptions.artifactObjects}).
 *
 * Platform objects are runtime-provided seed targets — see
 * {@link isPlatformObjectName}.
 *
 * `resolvable` is the stack's own object names for a single-package stack, and
 * those plus the rest of the artifact's for a package that co-owns a namespace.
 * The MESSAGE is identical either way, which is what lets {@link composeStacks}
 * re-raise this rule over the artifact without inventing a second dialect for
 * the same finding.
 *
 * ## Why this guards shapes the strict parse already rejects
 *
 * Since #18202 this runs from {@link composeStacks} too, and composition
 * accepts inputs the strict parse never saw (`strict: false`, a hand-built
 * stack object). So `data` here can be a non-array, and an entry can be `null`
 * or a scalar. Those shapes are SKIPPED, never dereferenced: a rule whose job
 * is to resolve object references must not turn a malformed collection into a
 * bare `TypeError` with no `code` and no `status` — the refusal discipline of
 * this file is the ADR-0112 envelope. A non-array `data` no longer reaches
 * here from either caller — the strict parse rejects it before
 * {@link validateCrossReferences}, and {@link composeStacks}'s step 3 refuses it
 * (#19784) before the artifact pass — so the `Array.isArray` guard below is the
 * rule's own type guard, kept so it never depends on its caller's ordering, and
 * says nothing because no caller can reach it. An entry that is not an object,
 * or whose `object` is not a string, carries no object reference for this rule
 * to resolve and is simply not this rule's finding.
 */
function collectSeedDataObjectErrors(
  config: ObjectStackDefinition,
  resolvable: ReadonlySet<string>,
): string[] {
  const errors: string[] = [];
  const datasets: unknown = (config as { data?: unknown }).data;
  if (datasets === undefined || datasets === null) return errors;
  if (!Array.isArray(datasets)) return errors;
  for (const dataset of datasets) {
    if (!dataset || typeof dataset !== 'object') continue;
    const objectName: unknown = (dataset as { object?: unknown }).object;
    if (typeof objectName !== 'string' || objectName.length === 0) continue;
    if (!resolvable.has(objectName) && !isPlatformObjectName(objectName)) {
      errors.push(
        `Seed data references object '${objectName}' which is not defined in objects.`,
      );
    }
  }
  return errors;
}

/**
 * Permission-set / profile object grants → object references (#18202,
 * ARTIFACT-SCOPED — see {@link DefineStackOptions.artifactObjects}).
 *
 * A grant keyed by an object that isn't declared (e.g. a short `lead` instead
 * of the namespaced `crm_lead`) silently applies to NOTHING: the authenticated
 * path may namespace-resolve it, but the anonymous / explicit-permission-set
 * path does not — so the grant is simply lost (e.g. a public Web-to-Lead INSERT
 * is denied for "roles []"). Fail loudly at build time.
 * (`validateNamespacePrefix`'s doc already assumes this check lives here.)
 * Platform objects are legitimate grant targets (e.g. a delegated-admin set
 * carrying CRUD on the RBAC link tables, ADR-0090 D12) — skip them here.
 *
 * `resolvable` carries the same two readings as its seed-data sibling above,
 * and so does its shape guard: a non-array `permissions` is refused before
 * either caller reaches this rule (the strict parse; {@link composeStacks}'s
 * step 3, #19784), so its guard is a silent type guard like the sibling's, and
 * a `permissions` entry that is not an object is skipped, because this rule reads
 * `permissions[].objects` and an unparsed input may carry neither. Same reason
 * as the sibling — a malformed collection must not become a bare `TypeError`
 * in the pass whose refusals are ADR-0112 envelopes.
 */
function collectPermissionGrantObjectErrors(
  config: ObjectStackDefinition,
  resolvable: ReadonlySet<string>,
): string[] {
  const errors: string[] = [];
  const permissions: unknown = (config as { permissions?: unknown }).permissions;
  if (permissions === undefined || permissions === null) return errors;
  if (!Array.isArray(permissions)) return errors;
  for (const perm of permissions) {
    if (!perm || typeof perm !== 'object') continue;
    const grants = (perm as { objects?: Record<string, unknown> }).objects;
    if (!grants || typeof grants !== 'object') continue;
    for (const objName of Object.keys(grants)) {
      if (!resolvable.has(objName) && !isPlatformObjectName(objName)) {
        errors.push(
          `Permission '${(perm as { name?: string }).name ?? '(unnamed)'}' grants on object ` +
            `'${objName}' which is not defined in objects.`,
        );
      }
    }
  }
  return errors;
}

/**
 * The inline grid column type a column that declares NO `type` renders as,
 * keyed by the type of the child field it names — for the field types whose
 * column type carries a type-conditional refusal in
 * {@link InlineGridColumnSchema}, and for no other.
 *
 * Read from the renderer, not decided here: its column hydration leaves a
 * column that declares a `type` alone and otherwise derives the column type
 * from the child field's type, whose only `currency` arm is the `currency`
 * field type (the read point is recorded in `packages/spec/liveness/field.json`,
 * row `inlineColumns`). Today the column
 * schema's one type-conditional rule is the `currency` refusal of `scale`, so
 * `currency` is the one row; a new type-conditional rule on the column adds its
 * row here, and `inline-grid-column-carriers.test.ts` reds until it does.
 */
const HYDRATED_INLINE_COLUMN_TYPE: Readonly<Record<string, 'currency'>> = {
  currency: 'currency',
};

/** Own-key lookup — a column `name` such as `constructor` must not resolve up the prototype chain. */
const hasOwnKey = (record: object, key: string): boolean => Object.prototype.hasOwnProperty.call(record, key);

/**
 * The audit / ownership FKs the record page never turns into a related list
 * (objectui `deriveRelatedLists`, `AUDIT_FK_FIELDS`), so no entry may name one.
 */
const RELATED_LIST_AUDIT_FKS: ReadonlySet<string> = new Set(['created_by', 'updated_by', 'owner_id']);

/**
 * [#27069] Every name an object gives one of its related lists — each
 * `relatedLists` entry and each field group's `relatedList` — must match an
 * INBOUND relationship: a `lookup` / `master_detail` field of a child object
 * whose `reference` is this object. An entry is a child object name (every
 * relationship of that child), or `object.field` (that one FK).
 *
 * A cross-object question, so it is judged here, where every child's fields
 * are known, and not in the object's own parse. The children are the stack's
 * `objects`, every `packages[].manifest.objects`, and the fields their
 * `objectExtensions` add (an extension can be the one that adds the FK).
 *
 * Left unjudged, so nothing here guesses at fields it cannot see: an entry
 * naming a child this stack does not declare but a sibling package does
 * (`artifactScope`, {@link DefineStackOptions.artifactObjects}), or a platform
 * object ({@link isPlatformObjectName}). An entry naming a child that is
 * nowhere is refused, as is one naming a declared child with no such FK.
 *
 * The message names the entry and every inbound relationship that exists,
 * spelled the way an entry may name it.
 *
 * [#27478] A field group's `relatedList` that DOES name inbound relationships
 * must name body tables only (`isBodyTableRelationship`, ruling B on #27055):
 * the group positions a body table and never promotes a side card, so one that
 * names a side card or a hidden list would draw nothing at the group. Judged
 * here for the same reason — the FK's keys live on the child — and on the same
 * children: a child left unjudged above is left unjudged here. The sentence is
 * `fieldGroupBodyTableRefusal`'s, which `@objectstack/lint` writes too.
 */
function collectRelatedListNameErrors(
  config: ObjectStackDefinition,
  artifactScope: ReadonlySet<string>,
): string[] {
  const asRecord = (value: unknown): Record<string, unknown> | undefined =>
    isRecord(value) ? value : undefined;
  const bodies = Array.isArray((config as { packages?: unknown }).packages)
    ? ((config as { packages: unknown[] }).packages).map((entry) => asRecord(asRecord(entry)?.manifest) ?? {})
    : [];
  const objectLists: unknown[] = [config.objects, ...bodies.map((body) => body.objects)];
  const extensionLists: unknown[] = [
    (config as { objectExtensions?: unknown }).objectExtensions,
    ...bodies.map((body) => body.objectExtensions),
  ];

  // Child object name → its fields (declaration and extensions merged by name).
  const fieldsByObject = new Map<string, Record<string, unknown>>();
  const parents: Record<string, unknown>[] = [];
  for (const list of objectLists) {
    if (!Array.isArray(list)) continue;
    for (const obj of list) {
      const record = asRecord(obj);
      if (!record || typeof record.name !== 'string') continue;
      parents.push(record);
      fieldsByObject.set(record.name, { ...fieldsByObject.get(record.name), ...asRecord(record.fields) });
    }
  }
  for (const list of extensionLists) {
    if (!Array.isArray(list)) continue;
    for (const ext of list) {
      const record = asRecord(ext);
      if (!record || typeof record.extend !== 'string') continue;
      fieldsByObject.set(record.extend, { ...fieldsByObject.get(record.extend), ...asRecord(record.fields) });
    }
  }

  // Parent name → its inbound relationships, in child then field order.
  const inbound = new Map<string, NamedInboundRelationship[]>();
  for (const [child, fields] of fieldsByObject) {
    for (const [field, def] of Object.entries(fields)) {
      const fieldDef = asRecord(def);
      if (!fieldDef || (fieldDef.type !== 'lookup' && fieldDef.type !== 'master_detail')) continue;
      if (typeof fieldDef.reference !== 'string' || RELATED_LIST_AUDIT_FKS.has(field)) continue;
      const list = inbound.get(fieldDef.reference) ?? [];
      list.push({ child, field, def: fieldDef });
      inbound.set(fieldDef.reference, list);
    }
  }

  const spell = (relationships: Array<{ child: string; field: string }>): string => {
    if (relationships.length === 0) return 'it has none';
    const perChild = new Map<string, number>();
    for (const r of relationships) perChild.set(r.child, (perChild.get(r.child) ?? 0) + 1);
    const names = relationships.map((r) => (perChild.get(r.child) === 1 ? r.child : `${r.child}.${r.field}`));
    return `the inbound relationships are ${[...new Set(names)].map((n) => `'${n}'`).join(', ')}`;
  };

  const errors: string[] = [];
  // One verdict per object NAME: an object declared both top-level and in a
  // package body is judged once, on its first declaration.
  const seen = new Set<string>();
  for (const parent of parents) {
    const parentName = parent.name as string;
    if (seen.has(parentName)) continue;
    seen.add(parentName);
    const relationships = inbound.get(parentName) ?? [];
    // The inbound relationships an entry names: every FK of a bare child, or the one `object.field`.
    const namedBy = (entry: string): NamedInboundRelationship[] => {
      const dot = entry.indexOf('.');
      const child = dot === -1 ? entry : entry.slice(0, dot);
      const field = dot === -1 ? undefined : entry.slice(dot + 1);
      return relationships.filter((r) => r.child === child && (field === undefined || r.field === field));
    };
    const judge = (entry: unknown, where: string): void => {
      if (typeof entry !== 'string') return;
      const child = entry.includes('.') ? entry.slice(0, entry.indexOf('.')) : entry;
      if (namedBy(entry).length > 0) return;
      if (!fieldsByObject.has(child) && (artifactScope.has(child) || isPlatformObjectName(child))) return;
      errors.push(
        `Object '${parentName}' ${where} '${entry}' matches no inbound relationship of '${parentName}' ` +
          `(a lookup / master_detail field of a child object whose reference is '${parentName}'); ` +
          `${spell(relationships)}. Name the child object, or object.field when that child has more than one.`,
      );
    };
    if (Array.isArray(parent.relatedLists)) {
      parent.relatedLists.forEach((entry: unknown, i: number) => judge(entry, `relatedLists[${i}]`));
    }
    if (Array.isArray(parent.fieldGroups)) {
      parent.fieldGroups.forEach((group: unknown, i: number) => {
        const record = asRecord(group);
        if (record?.relatedList === undefined) return;
        judge(record.relatedList, `fieldGroups[${i}].relatedList`);
        if (typeof record.relatedList !== 'string') return;
        const refusal = fieldGroupBodyTableRefusal(parentName, i, record.relatedList, namedBy(record.relatedList));
        if (refusal !== undefined) errors.push(refusal);
      });
    }
  }
  return errors;
}

/**
 * [#20901] Inline grid columns whose TYPE comes from the child field, judged by
 * the column contract's own rules against the type they will render as.
 *
 * `InlineGridColumnSchema` refuses `scale` on a column that DECLARES
 * `type: 'currency'` (ruling B on #19629, remedy 乙 on #19910), and sees only
 * the declared type: an identity-only column (`{ name: 'amount', scale: 2 }`)
 * takes its type from the child field when the grid hydrates it, so a column
 * over a `currency` child field published green carrying the refused key. The
 * child field is a fact the stack holds, so this is where it is judged.
 *
 * ⛔ No second rule. The verdict is the column schema's own: the column is
 * re-parsed as `{ ...column, type: <resolved> }` and every issue that parse
 * raises is reported, with the schema's own message. A column is judged only
 * once it is a valid column WITHOUT the type, so an issue here is one the
 * resolved type brings. On the two carriers the stack's parse reaches, it
 * already passed that parse; on the two page carriers, whose `properties` the
 * stack's parse never reaches, the column is parsed alone first and a column
 * that fails is left to the component-props gate (`@objectstack/lint`'s
 * `validateComponentProps`), which reports its own defects against
 * `ComponentPropsMap`.
 *
 * All four carriers of the column are walked:
 *
 * - a relationship field's `inlineColumns` — the field sits on the CHILD
 *   object, so a column names a field of the object that owns the field;
 * - a form view's `subforms[].columns` (the container's `form` and each
 *   `formViews` entry) — a column names a field of the subform's
 *   `childObject`;
 * - [#20928] an `object-master-detail-form` page block's `details[].columns`,
 *   wherever the block sits on a page ({@link forEachPageComponent}) — a column
 *   names a field of the detail entry's `childObject`;
 * - [#24190] a `record:line_items` page block's `columns`, wherever the block
 *   sits on a page ({@link forEachPageComponent}) — a region's components, a
 *   container's component children, a `page:tabs` or `page:accordion` item's
 *   `children`, a slot — a column names a field of the child object the panel
 *   lists, resolved the way the renderer resolves it
 *   ({@link lineItemsChildObject}).
 *
 * Resolution is against the stack's own `objects`: a `childObject` this stack
 * does not declare, or a column naming no field of it, is not judged here — an
 * unresolved column is not a wrong one, and the console's render-time report
 * stays the backstop for it.
 */
function collectHydratedInlineColumnErrors(config: ObjectStackDefinition): string[] {
  const errors: string[] = [];
  const fieldsByObject = new Map<string, Record<string, unknown>>();
  for (const obj of config.objects ?? []) {
    if (!isRecord(obj) || !isRecord(obj.fields)) continue;
    fieldsByObject.set(obj.name, obj.fields);
  }

  const judge = (columns: unknown, childObject: string, where: string): void => {
    const childFields = fieldsByObject.get(childObject);
    if (!childFields || !Array.isArray(columns)) return;
    columns.forEach((column: unknown, k: number) => {
      if (!isRecord(column) || column.type !== undefined || typeof column.name !== 'string') return;
      const childField = hasOwnKey(childFields, column.name) ? childFields[column.name] : undefined;
      const fieldType = isRecord(childField) ? childField.type : undefined;
      const resolved = typeof fieldType === 'string' && hasOwnKey(HYDRATED_INLINE_COLUMN_TYPE, fieldType)
        ? HYDRATED_INLINE_COLUMN_TYPE[fieldType]
        : undefined;
      if (!resolved) return;
      // Valid without the type, or not judged here — see the docblock.
      if (!InlineGridColumnSchema.safeParse(column).success) return;
      const verdict = InlineGridColumnSchema.safeParse({ ...column, type: resolved });
      if (verdict.success) return;
      for (const issue of verdict.error.issues) {
        const at = issue.path.map((segment) => `.${String(segment)}`).join('');
        errors.push(
          `${where}[${k}]${at}: column '${column.name}' declares no \`type\`, so it renders as a ` +
            `\`${resolved}\` column (field '${childObject}.${column.name}' is \`${fieldType}\`). ${issue.message}`,
        );
      }
    });
  };

  for (const obj of config.objects ?? []) {
    if (!isRecord(obj) || !isRecord(obj.fields)) continue;
    for (const [fieldName, field] of Object.entries(obj.fields)) {
      if (!isRecord(field)) continue;
      judge(field.inlineColumns, obj.name, `Object '${obj.name}' field '${fieldName}' inlineColumns`);
    }
  }

  for (const [i, view] of (config.views ?? []).entries()) {
    const forms: Array<[where: string, form: unknown]> = [];
    if (view.form) forms.push([`View[${i}].form`, view.form]);
    for (const [key, form] of Object.entries(view.formViews ?? {})) {
      forms.push([`View[${i}].formViews.${key}`, form]);
    }
    for (const [where, form] of forms) {
      const subforms = isRecord(form) ? form.subforms : undefined;
      if (!Array.isArray(subforms)) continue;
      subforms.forEach((subform: unknown, j: number) => {
        if (!isRecord(subform) || typeof subform.childObject !== 'string') return;
        judge(subform.columns, subform.childObject, `${where}.subforms[${j}].columns`);
      });
    }
  }

  // [#20928] The page carriers: `properties` is an open record the stack's
  // parse never reaches, so `details` and `columns` are read raw.
  for (const page of config.pages ?? []) {
    if (!isRecord(page)) continue;
    const pageName = typeof page.name === 'string' ? page.name : '(unnamed)';
    forEachPageComponent(page, (node, props, path) => {
      if (node.type === 'object-master-detail-form' && Array.isArray(props.details)) {
        props.details.forEach((detail: unknown, j: number) => {
          if (!isRecord(detail) || typeof detail.childObject !== 'string') return;
          judge(
            detail.columns,
            detail.childObject,
            `Page '${pageName}' (${path}) object-master-detail-form details[${j}].columns`,
          );
        });
        return;
      }
      // [#24190] The fourth carrier: one grid per block, over the child object
      // the panel lists.
      if (node.type === 'record:line_items') {
        const childObject = lineItemsChildObject(node, props);
        if (childObject === undefined) return;
        judge(props.columns, childObject, `Page '${pageName}' (${path}) record:line_items columns`);
      }
    });
  }
  return errors;
}

/** Target types that hold any single string, so any string-valued source fits them. */
const LOOKUP_AUTOFILL_TEXT_TARGETS: ReadonlySet<string> = new Set(['text', 'textarea', 'markdown', 'richtext', 'html']);
/** Source types whose value is one plain string. */
const LOOKUP_AUTOFILL_STRING_SOURCES: ReadonlySet<string> = new Set([
  'text', 'textarea', 'markdown', 'richtext', 'html', 'email', 'url', 'phone', 'autonumber',
]);
/** The two amount types, which hold each other's value. */
const LOOKUP_AUTOFILL_AMOUNT_TYPES: ReadonlySet<string> = new Set(['number', 'currency']);
/** The relationship types, whose value is a record id of their `reference`. */
const LOOKUP_AUTOFILL_RELATIONSHIP_TYPES: ReadonlySet<string> = new Set(['lookup', 'master_detail']);
/** The option types that hold a list without declaring `multiple`. */
const LOOKUP_AUTOFILL_INHERENTLY_MULTI_TYPES: ReadonlySet<string> = new Set(['multiselect', 'checkboxes', 'tags']);
/** A `formula` source's value type, from its `returnType`. */
const LOOKUP_AUTOFILL_FORMULA_VALUE_TYPE: Readonly<Record<string, string>> = {
  number: 'number', currency: 'currency', text: 'text', boolean: 'boolean', date: 'date',
};

/**
 * Why a `source` field's value cannot go into a `target` field, or `undefined`
 * when it can (or when the source's value type is not known here). The rule is
 * the stored value's shape, not the label: the same type and multiplicity, a
 * string-valued source into a plain text target, `number` and `currency` into
 * each other, and a relationship only into a relationship over the same
 * object.
 */
function lookupAutofillTypeMismatch(
  target: Record<string, unknown>,
  source: Record<string, unknown>,
): string | undefined {
  const targetType = target.type;
  let sourceType = source.type;
  if (sourceType === 'formula') {
    sourceType = typeof source.returnType === 'string' ? LOOKUP_AUTOFILL_FORMULA_VALUE_TYPE[source.returnType] : undefined;
  }
  // A `summary`'s value type follows its operation and its rolled-up field,
  // and a formula with no `returnType` declares none: not known here, so not
  // judged — an unresolved type is not a wrong one.
  if (typeof targetType !== 'string' || typeof sourceType !== 'string' || sourceType === 'summary') return undefined;
  const isList = (def: Record<string, unknown>, type: string): boolean =>
    def.multiple === true || LOOKUP_AUTOFILL_INHERENTLY_MULTI_TYPES.has(type);
  const pairing = `\`${String(source.type)}\`${source.type === 'formula' ? ` returning \`${sourceType}\`` : ''} → \`${targetType}\``;
  if (isList(target, targetType) !== isList(source, sourceType)) {
    return `one holds a list and the other a single value (${pairing})`;
  }
  if (LOOKUP_AUTOFILL_RELATIONSHIP_TYPES.has(targetType) || LOOKUP_AUTOFILL_RELATIONSHIP_TYPES.has(sourceType)) {
    if (LOOKUP_AUTOFILL_RELATIONSHIP_TYPES.has(targetType) && LOOKUP_AUTOFILL_RELATIONSHIP_TYPES.has(sourceType)
      && target.reference === source.reference) return undefined;
    const over = (def: Record<string, unknown>): string => (typeof def.reference === 'string' ? ` over '${def.reference}'` : '');
    return `a record id fills only a relationship over the same object (${pairing.replace(' → ', `${over(source)} → `)}${over(target)})`;
  }
  if (targetType === sourceType) return undefined;
  if (LOOKUP_AUTOFILL_TEXT_TARGETS.has(targetType) && LOOKUP_AUTOFILL_STRING_SOURCES.has(sourceType)) return undefined;
  if (LOOKUP_AUTOFILL_AMOUNT_TYPES.has(targetType) && LOOKUP_AUTOFILL_AMOUNT_TYPES.has(sourceType)) return undefined;
  return `the target cannot hold the source's value (${pairing})`;
}

/**
 * [#27945] Each `lookupAutofill` pair's `source` names a field of the object
 * the lookup references, which the picked record carries, and whose value the
 * pair's target can hold. A source the referenced object does not declare
 * arrives as nothing, an `internal` one is omitted from every read, and a value
 * of the wrong shape is refused by the save the pick fed — so each would parse
 * and fill nothing, or fill something the save then refuses (ADR-0049 declared
 * = enforced).
 *
 * Judged here because only the stack holds the referenced object; the target
 * half (a writable field of the declaring object, named once) is the object
 * parse's own (`refuseDishonestLookupAutofill` in `data/object.zod.ts`), which
 * has already passed by the time this pass runs. The type rule is
 * {@link lookupAutofillTypeMismatch}.
 *
 * Resolution is against the stack's own `objects`, merged with its
 * `objectExtensions` by name: a referenced object this stack does not declare
 * is not judged — an unresolved source is not a wrong one, the stance of
 * {@link collectHydratedInlineColumnErrors}. An undeclared source that is one
 * of the audit-provenance columns the platform injects (`created_at`, …) is
 * not judged either: every record carries it without a declaration.
 */
function collectLookupAutofillErrors(config: ObjectStackDefinition): string[] {
  const errors: string[] = [];
  const fieldsByObject = new Map<string, Record<string, unknown>>();
  for (const obj of config.objects ?? []) {
    if (!isRecord(obj) || !isRecord(obj.fields)) continue;
    fieldsByObject.set(obj.name, { ...fieldsByObject.get(obj.name), ...obj.fields });
  }
  for (const ext of (config as { objectExtensions?: unknown }).objectExtensions as unknown[] ?? []) {
    if (!isRecord(ext) || typeof ext.extend !== 'string' || !isRecord(ext.fields)) continue;
    fieldsByObject.set(ext.extend, { ...fieldsByObject.get(ext.extend), ...ext.fields });
  }

  for (const [objectName, fields] of fieldsByObject) {
    for (const [fieldName, field] of Object.entries(fields)) {
      if (!isRecord(field) || !Array.isArray(field.lookupAutofill) || typeof field.reference !== 'string') continue;
      const referenced = fieldsByObject.get(field.reference);
      if (!referenced) continue;
      field.lookupAutofill.forEach((pair: unknown, i: number) => {
        if (!isRecord(pair) || typeof pair.source !== 'string') return;
        const where = `Object '${objectName}' field '${fieldName}' lookupAutofill[${i}].source`;
        const source = hasOwnKey(referenced, pair.source) ? referenced[pair.source] : undefined;
        if (!isRecord(source)) {
          if (hasOwnKey(AUDIT_FIELD_DEFS, pair.source)) return;
          errors.push(
            `${where}: '${pair.source}' is not a field of '${field.reference}', the object this lookup references, `
              + `so a pick has no value to copy. Name a field '${field.reference}' declares.`,
          );
          return;
        }
        if (source.internal === true) {
          errors.push(
            `${where}: '${field.reference}.${pair.source}' is \`internal\`, so no read returns it and a pick has no `
              + 'value to copy. Name a field the record carries.',
          );
          return;
        }
        const target = typeof pair.target === 'string' && hasOwnKey(fields, pair.target) ? fields[pair.target] : undefined;
        if (!isRecord(target)) return;
        const mismatch = lookupAutofillTypeMismatch(target, source);
        if (mismatch !== undefined) {
          errors.push(
            `${where}: '${field.reference}.${pair.source}' cannot fill '${objectName}.${String(pair.target)}' — `
              + `${mismatch}. Pair the target with a source whose value it holds.`,
          );
        }
      });
    }
  }
  return errors;
}

/**
 * [#24190] The child object a `record:line_items` block lists, resolved the
 * way objectui resolves it before `LineItemsPanel` hydrates its columns from
 * that object's schema — so the column is judged against the field it will
 * render.
 *
 * The block's `childObject` is optional because the node's object
 * `dataSource` binding can supply the object instead (`RecordLineItemsProps`),
 * and the block's binding mapping writes the binding's `object` onto
 * `childObject`: a binding that names an object wins over an authored
 * `childObject`. An API binding (`provider: 'api'`) names no object, and the
 * panel then reads `childObject` as authored. The `isRecord` / `typeof`
 * guards are this rule's own type guards, as in the rest of this page walk:
 * the stack's parse has already judged the node's `dataSource`, and it never
 * reaches `properties`.
 */
function lineItemsChildObject(
  node: Record<string, unknown>,
  props: Record<string, unknown>,
): string | undefined {
  const binding = node.dataSource;
  if (isRecord(binding) && typeof binding.object === 'string' && binding.object.length > 0) {
    return binding.object;
  }
  return typeof props.childObject === 'string' ? props.childObject : undefined;
}

/**
 * A job's `pull.mapping` must name a mapping this stack declares, and that
 * mapping must carry a `connectorSource` (ruling Q1-B on the connector-sync
 * card: "`os validate` checks the mapping name").
 *
 * Both halves are refused here rather than at the first tick, where the
 * automation service would reject the run (`mapping_not_found` /
 * `no_connector_source`): a job is package-authored, and a reference its own
 * stack cannot resolve is an authoring defect the package would otherwise ship.
 * Resolved against the stack's own `mappings`, like every mapping reference in
 * this function. A disabled job is judged too — `enabled: false` turns a job
 * off, it does not make a dangling name correct.
 */
function collectJobPullMappingErrors(config: ObjectStackDefinition): string[] {
  const errors: string[] = [];
  const jobs = Array.isArray(config.jobs) ? config.jobs : [];
  if (jobs.length === 0) return errors;
  const mappings = new Map<string, { connectorSource?: unknown }>();
  for (const m of Array.isArray(config.mappings) ? config.mappings : []) {
    if (isRecord(m) && typeof m.name === 'string') mappings.set(m.name, m);
  }
  for (const job of jobs) {
    if (!isRecord(job) || !isRecord(job.pull)) continue;
    const name = job.pull.mapping;
    if (typeof name !== 'string' || name.length === 0) continue;
    const mapping = mappings.get(name);
    if (!mapping) {
      errors.push(
        `Job '${String(job.name)}' pulls mapping '${name}' which is not defined in mappings. ` +
          `Declare the mapping (its targetObject, fieldMapping and a connectorSource naming the ` +
          `rest or openapi connector it pulls from) or correct the name.`,
      );
      continue;
    }
    if (mapping.connectorSource === undefined) {
      errors.push(
        `Job '${String(job.name)}' pulls mapping '${name}', which declares no connectorSource — ` +
          `there is nothing to pull. Add connectorSource: { connector, action } to the mapping, ` +
          `naming the rest or openapi connector it reads from.`,
      );
    }
  }
  return errors;
}

/**
 * `demoStaff` — the development boot's demo accounts — judged against the
 * stack that declares them.
 *
 * Three refusals, each one a boot that would otherwise go wrong quietly:
 *
 * - **Two entries under one name.** A seed dataset deals a record to a person
 *   by name (`owner_id: 'Legal Counsel 1'`); with two accounts carrying that
 *   name the reference resolves to whichever the store returns first.
 * - **Two entries under one address** (compared without regard to case, as
 *   sign-in compares it). The second provisioning finds the first account and
 *   leaves it as it is, so the second entry's name, position and permission
 *   sets are silently never applied.
 * - **A position or permission set the stack does not declare.** The
 *   provisioning writes its assignments as the platform, and a platform write
 *   naming nothing in the security catalog is stored and grants nothing — an
 *   account that signs in to an empty application. Resolving against the
 *   stack's OWN declarations (top level and every assembled package body) is
 *   also the boundary: a demo account can hold only what its application
 *   declares, never a platform set such as `admin_full_access`.
 *
 * And three about `manager`, which the provisioning resolves within this same
 * list once every entry has its account:
 *
 * - **A manager that names no entry.** The boot has no account to link, so
 *   the approval rung it was declared for would reach nobody.
 * - **An entry that names itself.** The set-manager write refuses it, so the
 *   link would never land, and an approval routed to the submitter is the
 *   approval the manager rung exists to prevent.
 * - **A chain that loops back on itself.** The set-manager write refuses the
 *   link that closes the loop, so one entry of the loop would silently keep
 *   no manager, and which one would depend on the order the boot walked them.
 */
function collectDemoStaffErrors(config: ObjectStackDefinition): string[] {
  const errors: string[] = [];
  const staff = Array.isArray(config.demoStaff) ? config.demoStaff : [];
  if (staff.length === 0) return errors;

  const declaredPositions = new Set<string>();
  const declaredPermissionSets = new Set<string>();
  const collectNames = (entries: unknown, into: Set<string>) => {
    for (const entry of Array.isArray(entries) ? entries : []) {
      const name = readEntryName(entry);
      if (name !== undefined) into.add(name);
    }
  };
  collectNames(config.positions, declaredPositions);
  collectNames(config.permissions, declaredPermissionSets);
  for (const pkg of Array.isArray(config.packages) ? config.packages : []) {
    const body = isRecord(pkg) && isRecord(pkg.manifest) ? pkg.manifest : undefined;
    if (!body) continue;
    collectNames(body.positions, declaredPositions);
    collectNames(body.permissions, declaredPermissionSets);
  }

  const indicesByName = new Map<string, number[]>();
  const indicesByEmail = new Map<string, number[]>();
  const push = (map: Map<string, number[]>, key: string, i: number) => {
    const list = map.get(key) ?? [];
    list.push(i);
    map.set(key, list);
  };

  for (const [i, entry] of staff.entries()) {
    if (!isRecord(entry)) continue;
    const where = `stack.demoStaff[${i}]`;
    if (typeof entry.name === 'string' && entry.name) push(indicesByName, entry.name, i);
    if (typeof entry.email === 'string' && entry.email) push(indicesByEmail, entry.email.trim().toLowerCase(), i);
    if (typeof entry.position === 'string' && entry.position && !declaredPositions.has(entry.position)) {
      errors.push(
        `Demo account '${String(entry.name)}' (${where}) is assigned position '${entry.position}', which this ` +
          'stack does not declare in positions. A demo account can hold only a position its application ' +
          'declares; declare the position or correct the name.',
      );
    }
    for (const set of Array.isArray(entry.permissionSets) ? entry.permissionSets : []) {
      if (typeof set !== 'string' || !set || declaredPermissionSets.has(set)) continue;
      errors.push(
        `Demo account '${String(entry.name)}' (${where}) is granted permission set '${set}', which this stack ` +
          'does not declare in permissions. A demo account can hold only a permission set its application ' +
          'declares, never a platform set; declare the set or correct the name.',
      );
    }
  }

  for (const [name, indices] of indicesByName) {
    if (indices.length < 2) continue;
    errors.push(
      `Demo account name '${name}' is declared ${indices.length === 2 ? 'twice' : `${indices.length} times`} in ` +
        `\`demoStaff\`: ${joinDeclarationOrigins(indices.map((i) => `stack.demoStaff[${i}]`))}. Seed data deals ` +
        'a record to a person by name, so a reference to this name would resolve to whichever account the ' +
        'store returns first. Give each demo account its own name.',
    );
  }
  for (const [email, indices] of indicesByEmail) {
    if (indices.length < 2) continue;
    errors.push(
      `Demo account address '${email}' is declared ${indices.length === 2 ? 'twice' : `${indices.length} times`} in ` +
        `\`demoStaff\`: ${joinDeclarationOrigins(indices.map((i) => `stack.demoStaff[${i}]`))}. One address is ` +
        'one account, so every entry after the first would never be applied. Give each demo account its own ' +
        'address.',
    );
  }
  errors.push(...collectDemoStaffManagerErrors(staff, indicesByEmail));
  return errors;
}

/**
 * The `manager` half of {@link collectDemoStaffErrors}: every `manager` must
 * name another entry's address, and following the links from any entry must
 * reach an entry with no manager. A repeated address resolves to its first
 * entry here; the repeat itself is already refused above.
 */
function collectDemoStaffManagerErrors(
  staff: readonly unknown[],
  indicesByEmail: ReadonlyMap<string, number[]>,
): string[] {
  const errors: string[] = [];
  // Entry index -> the entry index its `manager` resolves to.
  const managerOf = new Map<number, number>();

  for (const [i, entry] of staff.entries()) {
    if (!isRecord(entry) || typeof entry.manager !== 'string' || !entry.manager) continue;
    const where = `stack.demoStaff[${i}]`;
    const address = entry.manager.trim().toLowerCase();
    const target = indicesByEmail.get(address)?.[0];
    if (target === i) {
      errors.push(
        `Demo account '${String(entry.name)}' (${where}) names itself as its manager ('${entry.manager}'). An ` +
          'approval routed to the manager rung would reach the person who submitted it, so the link is never ' +
          'written. Name another demo account, or leave manager out.',
      );
      continue;
    }
    if (target === undefined) {
      errors.push(
        `Demo account '${String(entry.name)}' (${where}) names manager '${entry.manager}', which is the address ` +
          'of no demoStaff entry. A manager must be another demo account of this stack; declare that person in ' +
          'demoStaff, or correct the address.',
      );
      continue;
    }
    managerOf.set(i, target);
  }

  // Walk each chain upward. An entry already known to reach a top (or to sit
  // in a reported loop) ends the walk, so every link is followed once.
  const settled = new Set<number>();
  for (const start of managerOf.keys()) {
    const path: number[] = [];
    const onPath = new Set<number>();
    let cursor: number | undefined = start;
    while (cursor !== undefined && !settled.has(cursor) && !onPath.has(cursor)) {
      path.push(cursor);
      onPath.add(cursor);
      cursor = managerOf.get(cursor);
    }
    if (cursor !== undefined && onPath.has(cursor)) {
      const loop = path.slice(path.indexOf(cursor));
      const names = [...loop, cursor].map((i) => {
        const entry = staff[i];
        return `'${isRecord(entry) ? String(entry.name) : `#${i}`}'`;
      });
      errors.push(
        `The managers declared in \`demoStaff\` form a loop: ${names.join(' → ')} ` +
          `(${joinDeclarationOrigins(loop.map((i) => `stack.demoStaff[${i}]`))}). A reporting chain must reach ` +
          'someone with no manager; the link that closes the loop would be refused at the boot, leaving one of ' +
          'these accounts with no manager. Remove manager from one of these entries.',
      );
    }
    for (const i of path) settled.add(i);
  }
  return errors;
}

/**
 * [ADR-0015 §4.2 · #25168] An object's `external` binding must not name a
 * managed datasource this stack declares.
 *
 * The half of the rule that needs the datasource's definition. The other half
 * — an `external` object whose `datasource` is the platform's managed primary,
 * `'default'` — needs only the object, so `ObjectSchema`'s refinement refuses
 * it inside the parse above and it never reaches this pass. Here the object
 * names some other datasource, and the verdict is read off that datasource's
 * PARSED definition, whose `schemaMode` carries the spec default (`'managed'`)
 * when none was declared.
 *
 * Resolved against the stack's own `datasources` only. A name this stack does
 * not declare — a datasource the host or another package registers, or one an
 * administrator stores at runtime — gets no verdict here: the stack cannot see
 * its `schemaMode`, and refusing what it cannot see would refuse a correct
 * binding. The predicate and the message are
 * {@link externalBindingDatasourceRefusal}'s, so this finding reads exactly as
 * the object parse's does.
 */
function collectExternalBindingDatasourceErrors(config: ObjectStackDefinition): string[] {
  const errors: string[] = [];
  const declared = new Map<string, { schemaMode?: unknown }>();
  for (const ds of Array.isArray(config.datasources) ? config.datasources : []) {
    if (isRecord(ds) && typeof ds.name === 'string') declared.set(ds.name, ds);
  }
  if (declared.size === 0) return errors;
  for (const obj of Array.isArray(config.objects) ? config.objects : []) {
    if (!isRecord(obj) || typeof obj.datasource !== 'string') continue;
    const datasource = declared.get(obj.datasource);
    if (datasource === undefined) continue;
    const refusal = externalBindingDatasourceRefusal(obj.name, obj.external, obj.datasource, datasource);
    if (refusal !== undefined) errors.push(refusal.message);
  }
  return errors;
}

/**
 * [ADR-0015 amendment D7 · ADR-0143] A datasource's `external.connector` must
 * name a connector instance this stack declares: a `connectors` entry with a
 * `provider` and an `auth` that is not `none` — the ADR-0143 instance auth
 * contract whose credential the datasource borrows.
 *
 * The datasource borrows that instance's credential, so a name this stack
 * cannot resolve would leave an API-backed datasource with no credential at
 * all, found by its first read as an upstream 401. Refused here instead (the
 * ruling: "refused at build when the named instance is not declared"), with
 * three findings, because the fixes differ:
 *
 *  - no `connectors` entry of that name — declare the instance or correct the
 *    name;
 *  - an entry with no `provider` — a catalog descriptor (ADR-0097), which is
 *    never materialized and holds no credential;
 *  - an instance with no `auth`, or `auth: { type: 'none' }` — nothing to
 *    lend; an unauthenticated upstream needs no `connector` on the datasource.
 *
 * Resolved against the stack's own `connectors`, like a job's mapping
 * reference: a datasource is package-authored, and a reference its own stack
 * cannot resolve is an authoring defect the package would otherwise ship. A
 * connector a plugin registers at runtime is not a declared instance and has
 * no connection record to share. A disabled instance (`enabled: false`) is
 * accepted: the switch turns the vendor off for its actions and its records
 * alike, which is the one-grant behaviour D7 asks for, not a dangling name.
 * Runs before the object-count early return: it needs no object. A
 * composition runs it once more over every input's datasources and connectors
 * ({@link collectComposedDatasourceConnectorErrors}), passing `shadowedLender`:
 * for a name declared more than once in one registration slot whose kept
 * entry cannot lend, it returns the fix to prescribe instead (the duplicate),
 * or `undefined` when no earlier declaration could have lent either.
 */
function collectDatasourceConnectorErrors(
  config: ObjectStackDefinition,
  shadowedLender?: (name: string) => string | undefined,
): string[] {
  const errors: string[] = [];
  const datasources = Array.isArray(config.datasources) ? config.datasources : [];
  const borrowing = datasources.filter(
    (ds) => isRecord(ds) && isRecord(ds.external) && typeof ds.external.connector === 'string',
  );
  if (borrowing.length === 0) return errors;
  const connectors = new Map<string, Record<string, unknown>>();
  for (const entry of Array.isArray(config.connectors) ? config.connectors : []) {
    if (isRecord(entry) && typeof entry.name === 'string') connectors.set(entry.name, entry);
  }
  for (const ds of borrowing) {
    const name = String((ds.external as Record<string, unknown>).connector);
    const entry = connectors.get(name);
    const subject = connectorBorrowSubject(ds.name, name);
    if (entry === undefined) {
      errors.push(
        `${subject}, which is not defined in connectors. Declare the connector instance it borrows ` +
          `from (a connectors entry named '${name}' with a provider and an auth credential, e.g. ` +
          `auth: { type: 'bearer', credentialRef }) or correct the name.`,
      );
      continue;
    }
    // The one door that sees a name declared twice in one registration slot:
    // the later entry is the one the runtime keeps, so an earlier instance
    // that could lend is shadowed, and the fix is the duplicate, not the
    // entry's provider or auth.
    const shadow = connectorCanLend(entry) ? undefined : shadowedLender?.(name);
    if (!connectorHasProvider(entry)) {
      errors.push(
        shadow !== undefined
          ? `${subject}, which declares no provider in the entry the composed artifact keeps — a catalog ` +
              `descriptor that holds no credential to lend (ADR-0097). ${shadow}`
          : `${subject}, which declares no provider — a connector entry with no provider is a catalog ` +
              `descriptor, never materialized, and holds no credential to lend (ADR-0097). Give it the ` +
              `provider that serves this vendor and an auth credential, or name a connector instance ` +
              `that has one.`,
      );
      continue;
    }
    if (!connectorHasCredential(entry)) {
      errors.push(
        shadow !== undefined
          ? `${subject}, which declares no auth credential in the entry the composed artifact keeps — ` +
              `there is nothing to borrow. ${shadow}`
          : `${subject}, which declares no auth credential — there is nothing to borrow. Declare the ` +
              `instance's auth (e.g. auth: { type: 'bearer', credentialRef }), or, if the upstream ` +
              `needs no credential, remove external.connector from the datasource.`,
      );
    }
  }
  return errors;
}

/** The subject every `external.connector` finding opens with. */
function connectorBorrowSubject(datasource: unknown, connector: string): string {
  return `Datasource '${String(datasource)}' borrows the credential of connector '${connector}' (external.connector)`;
}

/** A connector entry with a `provider`: an instance, not a catalog descriptor (ADR-0097). */
function connectorHasProvider(entry: Record<string, unknown>): boolean {
  return typeof entry.provider === 'string' && entry.provider.length > 0;
}

/** A connector entry whose `auth` holds a credential to lend: present, and not `type: 'none'`. */
function connectorHasCredential(entry: Record<string, unknown>): boolean {
  return isRecord(entry.auth) && entry.auth.type !== 'none';
}

/** A connector entry a datasource's `external.connector` can borrow from. */
function connectorCanLend(entry: Record<string, unknown>): boolean {
  return connectorHasProvider(entry) && connectorHasCredential(entry);
}

/**
 * [ADR-0015 §4.2 · #25211] {@link collectExternalBindingDatasourceErrors} over
 * a COMPOSITION: an `external` object of one input bound to a datasource
 * another input declares managed (or with no `schemaMode`).
 *
 * `defineStack` resolves a binding against its own stack's `datasources`, so a
 * pair split across two inputs reached the artifact with no verdict: each input
 * is legal alone, and the composed artifact registers both, the object as
 * federated and its datasource as managed. Judged here over the objects the
 * artifact carries (step 2's merge, after the conflict strategy) and the
 * `datasources` of every input, by the same collector, so the finding reads
 * exactly as the per-stack one does.
 *
 * What this can newly refuse: a cross-input pair, and, as with the artifact
 * pass's other rules, a same-stack pair in an input built with
 * `strict: false`, which never reached the per-stack pass. A strict input holds
 * no same-stack pair. A datasource name two inputs declare is judged against
 * the later declaration (the collector keeps the last one it meets).
 */
function collectComposedExternalBindingDatasourceErrors(
  stacks: readonly ObjectStackDefinition[],
  composedObjects: ObjectStackDefinition['objects'],
): string[] {
  const datasources = stacks.flatMap((stack) => (Array.isArray(stack.datasources) ? stack.datasources : []));
  return collectExternalBindingDatasourceErrors({ objects: composedObjects, datasources } as ObjectStackDefinition);
}

/** One declaration a composition input provides, and the registration slot it boots into. */
interface ProvidedCollectionEntry {
  entry: unknown;
  /** Where it was declared, for a finding: the input, or a package body of it. */
  declaredIn: string;
  /**
   * The registry slot the entry is judged in: the registry keys a
   * package-owned item by package id and name, so two entries under one name
   * in one slot are one item (the later wins), and in two slots they are two.
   * For a package body's own entry ({@link ProvidedCollectionEntry.inBody})
   * that is the slot it boots into. For a top-level entry that boots beside
   * package bodies it is a stand-in, one per input: see `inBody`.
   */
  slot: string;
  /**
   * Whether the entry boots as a package body's own item: an entry of a
   * `packages[]` body, or, under `preserve`, the top level of an input that
   * `preservePackageEntries` folds into a body of its own manifest id.
   *
   * `false` for every other top-level entry. When the artifact carries
   * package bodies, such an entry boots through the residual rule
   * (`unclaimedTopLevel`, `@objectstack/metadata`): it is not registered at
   * all when a body declares its name, and is registered under the composed
   * artifact's `manifest.id` (the last input's) when none does; a dev reload
   * then replaces the booted entries of the name with the artifact's
   * top-level list (`mergeDeclaredConnectorSources`,
   * `@objectstack/service-automation`). Its `slot` is therefore not the slot
   * it boots into: `'artifact'` under `last` and for an input with no
   * manifest id, and under `preserve` the input's own `package:${id}` for an
   * input that carries `packages` beside its own collections. Keeping such a
   * top level in a slot apart from the bodies is what refuses a disagreement
   * with a body's entry as ambiguous, which is the verdict the boot-or-reload
   * split asks for, so the stand-in stays.
   */
  inBody: boolean;
}

/**
 * Every entry of collection `key` that one composition input provides: the
 * input's own top level, plus each `packages[]` body when the input is itself
 * a multi-package artifact, whose collections live ONLY in those bodies
 * (#14512) — the {@link providedFlowNames} reading, for the same reason: the
 * top level alone would refuse an entry the input carries.
 *
 * Each entry object is listed once. A nested artifact whose bodies did not
 * reproduce its flattened half keeps both halves, holding the same entry
 * objects in each, so the bodies are read first and the top level adds only
 * what no body carries. The slot follows how the artifact boots: a package
 * body registers under its own id, and so does the top level of an input that
 * `preserve` folds into a package body. Any other top-level entry takes the
 * input's own `package:${id}` under `preserve` when the input has a manifest
 * id, and the `'artifact'` slot otherwise. When no input carries package
 * bodies, `'artifact'` is the composed artifact's one package. Beside package
 * bodies both are stand-ins, because such an entry boots through the residual
 * rule and a dev reload replaces it (see {@link ProvidedCollectionEntry.inBody}).
 */
function providedCollectionEntries(
  stack: ObjectStackDefinition,
  index: number,
  key: 'connectors' | 'datasources',
  preserve: boolean,
): ProvidedCollectionEntry[] {
  const entries: ProvidedCollectionEntry[] = [];
  const seen = new Set<unknown>();
  const input = stackLabel(stack, index);
  const collect = (list: unknown, declaredIn: string, slot: string, inBody: boolean): void => {
    if (!Array.isArray(list)) return;
    for (const entry of list) {
      if (seen.has(entry)) continue;
      seen.add(entry);
      entries.push({ entry, declaredIn, slot, inBody });
    }
  };
  const source = stack as Record<string, unknown>;
  if (Array.isArray(source.packages)) {
    for (const pkg of source.packages) {
      if (!isRecord(pkg) || !isRecord(pkg.manifest)) continue;
      const id = pkg.manifest.id ?? pkg.manifest.name;
      if (typeof id === 'string') collect(pkg.manifest[key], `package '${id}' of ${input}`, `package:${id}`, true);
      else collect(pkg.manifest[key], input, `input:${index}`, true);
    }
  }
  const ownId = stack.manifest?.id ?? stack.manifest?.name;
  const ownSlot = preserve && typeof ownId === 'string' ? `package:${ownId}` : 'artifact';
  collect(source[key], input, ownSlot, ownSlot !== 'artifact' && !Array.isArray(source.packages));
  return entries;
}

/**
 * [ADR-0015 amendment D7] {@link collectDatasourceConnectorErrors} over a
 * COMPOSITION: a datasource's `external.connector` against the `connectors` of
 * every input.
 *
 * `defineStack` judges the reference against its own stack only, and an input
 * built with `strict: false` never reaches that pass, so a dangling name it
 * carries reached the composed artifact with no verdict: the datasource has no
 * credential to borrow, and the author learns of the typo when it first
 * connects instead of when the artifact is built. Judged here over the
 * `datasources` and the `connectors` of every input, top level and package
 * bodies alike ({@link providedCollectionEntries}), by the same collector, so
 * the three findings and their fixes read exactly as the per-stack ones do.
 *
 * What this can newly refuse: a dangling name, a descriptor or an instance
 * with nothing to lend, carried by an input built with `strict: false`. A
 * cross-input pair resolves (a datasource in one input borrowing an instance
 * another declares, or one of a nested multi-package input's package bodies
 * declares), because the composed artifact registers both.
 *
 * A connector name declared more than once is judged by how the artifact
 * boots it. Within one registration slot the later declaration is the one the
 * registry keeps ({@link SAME_STACK_ENTRY_IDENTITY}'s `connectors` row), so
 * the kept entry is judged, and when it cannot lend but an earlier one in the
 * slot could, the finding names both and prescribes the duplicate's fix. In
 * DIFFERENT slots the kept entries are refused as ambiguous, in either
 * declaration order, when they disagree on whether they can lend. The build
 * cannot know which one the datasource gets, and one name meaning one grant
 * is what D7 asks for. Which mechanism makes it unknowable depends on where
 * the entries sit, and the finding names it:
 *
 * - two package bodies: the registry keeps one entry per package, and the
 *   lender answers whichever registers first;
 * - a package body and a top-level entry beside it: the boot does not
 *   register the top-level entry, so the body's lends, and a dev reload
 *   replaces the body's entry with the artifact's top-level entries of the
 *   name, the first of which lends ({@link ProvidedCollectionEntry.inBody});
 * - top-level entries of two inputs, beside bodies that do not declare the
 *   name: no door registers either as a package body's entry, and a dev
 *   reload lends from the first top-level entry of the name.
 *
 * When the kept entries agree, the verdict is the same whichever one lends.
 */
function collectComposedDatasourceConnectorErrors(
  stacks: readonly ObjectStackDefinition[],
  preserve: boolean,
): string[] {
  const datasources: unknown[] = [];
  const declarations = new Map<string, Map<string, ProvidedCollectionEntry[]>>();
  for (const [i, stack] of stacks.entries()) {
    for (const { entry } of providedCollectionEntries(stack, i, 'datasources', preserve)) datasources.push(entry);
    for (const provided of providedCollectionEntries(stack, i, 'connectors', preserve)) {
      const { entry, slot } = provided;
      if (!isRecord(entry) || typeof entry.name !== 'string') continue;
      const bySlot = declarations.get(entry.name) ?? new Map<string, ProvidedCollectionEntry[]>();
      bySlot.set(slot, [...(bySlot.get(slot) ?? []), provided]);
      declarations.set(entry.name, bySlot);
    }
  }

  const lends = (provided: ProvidedCollectionEntry): boolean => connectorCanLend(provided.entry as Record<string, unknown>);
  const connectors: unknown[] = [];
  const shadows = new Map<string, string>();
  const ambiguities = new Map<string, string>();
  for (const [name, bySlot] of declarations) {
    const kept = [...bySlot.values()].map((inSlot) => inSlot[inSlot.length - 1]);
    const lending = kept.filter(lends);
    const notLending = kept.filter((provided) => !lends(provided));
    if (lending.length > 0 && notLending.length > 0) {
      const sites = (list: ProvidedCollectionEntry[]): string => list.map((p) => p.declaredIn).join(', ');
      const disagree =
        `and they disagree: ${sites(lending)} declares an instance that can lend, and ` +
        `${sites(notLending)} declares an entry that cannot.`;
      const inBodies = kept.filter((provided) => provided.inBody).length;
      const where =
        inBodies === kept.length
          ? `which more than one package of the composed artifact declares, ${disagree} The runtime ` +
            `keeps one entry per package and lends from whichever registers first, so the datasource ` +
            `could boot with no credential.`
          : inBodies > 0
            ? `which the composed artifact declares both in a package body and at its top level, ` +
              `${disagree} The boot does not register a top-level entry whose name a package body ` +
              `declares, so the body's entry lends, and a dev reload replaces it with the artifact's ` +
              `top-level entries of the name, the first of which lends, so the entry the datasource ` +
              `borrows depends on whether the artifact was booted or reloaded and on the order of its inputs.`
            : `which more than one input declares at the top level of a composed artifact that ` +
              `carries package bodies, ${disagree} No door registers either as a package body's ` +
              `entry, and a dev reload lends from the first top-level entry of the name, so the build ` +
              `cannot tell which one lends, and the datasource could boot with no credential.`;
      ambiguities.set(
        name,
        `${where} Rename or remove the entry that cannot lend, so that one connector name means one instance.`,
      );
      continue;
    }
    const representative = kept[kept.length - 1];
    connectors.push(representative.entry);
    if (lends(representative)) continue;
    const inSlot = bySlot.get(representative.slot) ?? [];
    const lender = inSlot.slice(0, -1).reverse().find(lends);
    if (lender === undefined) continue;
    shadows.set(
      name,
      `Connector '${name}' is declared more than once: ${lender.declaredIn} declares an instance that ` +
        `can lend, and ${representative.declaredIn} declares the later entry, which the runtime keeps. ` +
        `Rename or remove the later entry, or give one of the two its own name and point ` +
        `external.connector at the instance.`,
    );
  }

  const errors: string[] = [];
  const judged: unknown[] = [];
  for (const ds of datasources) {
    const connector = isRecord(ds) && isRecord(ds.external) ? ds.external.connector : undefined;
    const ambiguity = typeof connector === 'string' ? ambiguities.get(connector) : undefined;
    if (ambiguity === undefined) judged.push(ds);
    else errors.push(`${connectorBorrowSubject((ds as Record<string, unknown>).name, connector as string)}, ${ambiguity}`);
  }
  errors.push(
    ...collectDatasourceConnectorErrors({ datasources: judged, connectors } as ObjectStackDefinition, (name) =>
      shadows.get(name),
    ),
  );
  return errors;
}

/**
 * Perform strict cross-reference validation on a parsed stack definition.
 * Returns an array of error messages (empty if valid).
 *
 * `artifactObjects` (#18202) widens the resolution scope of the two
 * ARTIFACT-SCOPED classes ONLY — see {@link DefineStackOptions.artifactObjects}
 * for which two, why those two, and why the rest of this function keeps
 * resolving against the stack's own objects alone. Omitted (every
 * single-package stack, which is every stack that does not opt in) the two
 * scopes are the same Set and this function behaves exactly as it did before
 * the option existed.
 *
 * `artifactFlows` (#25514) widens the flow target of a `type: 'flow'` action
 * the same way, and every target that resolved ONLY through it is appended to
 * `flowClaims` — the record {@link composeStacks} redeems (see
 * {@link DefineStackOptions.artifactFlows}).
 */
function validateCrossReferences(
  config: ObjectStackDefinition,
  artifactObjects?: ReadonlySet<string>,
  artifactFlows?: ReadonlySet<string>,
  flowClaims?: ArtifactFlowClaim[],
): string[] {
  const errors: string[] = [];
  const objectNames = collectObjectNames(config);

  // Runs BEFORE the object-count early return on purpose: an object-less
  // stack that declares two globals under one name collides on exactly the
  // same runtime key, and this check needs no object to resolve against.
  errors.push(...collectDuplicateActionKeyErrors(config));
  // Same placement, same reason: two `functions` array entries under one name
  // collide in the one function namespace whether or not there are objects.
  errors.push(...collectDuplicateFunctionNameErrors(config));
  // Same placement, same reason: two entries of one named collection under one
  // identity occupy one registry slot whether or not there are objects.
  errors.push(...collectDuplicateEntryErrors(config));
  // Same placement: two default record pages for one object are two defaults
  // whether or not this stack defines that object (#23015).
  errors.push(...collectDuplicateDefaultRecordPageErrors(config));
  // Same placement: one membership key on two objects is one request-wide name
  // with two meanings, whatever else the stack declares (#25234).
  errors.push(...collectDuplicateMembershipKeyErrors(config));
  // Same placement, same reason: a global `operation: 'update'` action is
  // wrong whether or not the stack declares any objects.
  errors.push(...collectGlobalUpdateActionErrors(config));
  // Same placement: a job's `pull` names a MAPPING, resolved against the
  // stack's mappings, and needs no object to resolve against.
  errors.push(...collectJobPullMappingErrors(config));
  // Same placement: the development boot's demo accounts resolve against the
  // stack's positions and permission sets, and need no object either.
  errors.push(...collectDemoStaffErrors(config));
  // Same placement: a datasource's `external.connector` resolves against the
  // stack's connectors and needs no object either (ADR-0015 amendment D7).
  errors.push(...collectDatasourceConnectorErrors(config));
  // Same placement: the names an object gives its related lists (`relatedLists`,
  // a field group's `relatedList`) resolve against the objects of the stack AND
  // its package bodies, so an artifact whose objects live only in package
  // bodies is judged too (#27069). Its scope is the artifact scope below.
  errors.push(...collectRelatedListNameErrors(
    config,
    artifactObjects && artifactObjects.size > 0 ? new Set([...objectNames, ...artifactObjects]) : objectNames,
  ));

  if (objectNames.size === 0) return errors;

  // [ADR-0015 §4.2 · #25168] An object's `external` binding against the
  // `schemaMode` of a datasource this stack declares.
  errors.push(...collectExternalBindingDatasourceErrors(config));

  // The resolution scope of the two ARTIFACT-SCOPED classes. Identical to
  // `objectNames` unless the caller declared sibling packages, so a stack that
  // does not opt in cannot observe that this line exists.
  const artifactScope: ReadonlySet<string> =
    artifactObjects && artifactObjects.size > 0
      ? new Set([...objectNames, ...artifactObjects])
      : objectNames;

  // Validate hook → object references
  if (config.hooks) {
    for (const hook of config.hooks) {
      if (hook.object) {
        const hookObjects = Array.isArray(hook.object) ? hook.object : [hook.object];
        for (const obj of hookObjects) {
          if (!objectNames.has(obj)) {
            errors.push(
              `Hook '${hook.name}' references object '${obj}' which is not defined in objects.`,
            );
          }
        }
      }
    }
  }

  // Validate view data source → object references (nested in data.object)
  if (config.views) {
    for (const [i, view] of config.views.entries()) {
      const checkViewData = (data: unknown, viewLabel: string) => {
        if (data && typeof data === 'object' && 'provider' in data && 'object' in data) {
          const d = data as { provider: string; object: string };
          if (d.provider === 'object' && d.object && !objectNames.has(d.object)) {
            errors.push(
              `${viewLabel} references object '${d.object}' which is not defined in objects.`,
            );
          }
        }
      };

      if (view.list?.data) {
        checkViewData(view.list.data, `View[${i}].list`);
      }
      if (view.form?.data) {
        checkViewData(view.form.data, `View[${i}].form`);
      }
    }
  }

  // Validate identity-only inline grid columns against the child field's type
  // (#20901) — every carrier (#20928 added the master-detail page block's,
  // #24190 the line-items block's), the column schema's own verdict.
  errors.push(...collectHydratedInlineColumnErrors(config));

  // Validate each lookup-pick autofill source against the referenced object
  // (#27945) — the half the object's own parse cannot see.
  errors.push(...collectLookupAutofillErrors(config));

  // Validate seed data → object references. ARTIFACT-SCOPED (#18202).
  errors.push(...collectSeedDataObjectErrors(config, artifactScope));

  // Validate mapping → object references + executable-transform gate (#2611).
  // A mapping whose targetObject doesn't exist can never be applied by the
  // import endpoint (it 400s on target mismatch), and a `javascript`
  // transform has no server-side sandbox — both must fail at build time,
  // not at first use (Prime Directive #12: reject at the producer).
  if (config.mappings) {
    for (const m of config.mappings) {
      if (m.targetObject && !objectNames.has(m.targetObject)) {
        errors.push(
          `Mapping '${m.name}' targets object '${m.targetObject}' which is not defined in objects.`,
        );
      }
      for (const entry of m.fieldMapping ?? []) {
        if (entry.transform === 'javascript') {
          errors.push(
            `Mapping '${m.name}' uses transform 'javascript', which the import path does not execute ` +
              `(no server-side sandbox). Use none/constant/map/split/join/lookup, ` +
              `or model the logic as a flow.`,
          );
        }
      }
    }
  }

  // Validate permission-set / profile object grants → object references.
  // ARTIFACT-SCOPED (#18202) — the rule's own doc carries why it fails loudly.
  errors.push(...collectPermissionGrantObjectErrors(config, artifactScope));

  // Validate app navigation → object/dashboard/page/report references
  if (config.apps) {
    const dashboardNames = new Set<string>();
    if (config.dashboards) {
      for (const d of config.dashboards) {
        dashboardNames.add(d.name);
      }
    }
    const pageNames = new Set<string>();
    if (config.pages) {
      for (const p of config.pages) {
        pageNames.add(p.name);
      }
    }
    const reportNames = new Set<string>();
    if (config.reports) {
      for (const r of config.reports) {
        reportNames.add(r.name);
      }
    }
    // Every action name the stack defines, global + object-embedded — the same
    // "defined ANYWHERE in the stack" scope `validate-action-name-refs` (lint)
    // resolves name-bound action references against.
    const actionNames = new Set<string>();
    if (config.actions) {
      for (const a of config.actions) {
        actionNames.add(a.name);
      }
    }
    if (config.objects) {
      for (const obj of config.objects) {
        for (const a of obj.actions ?? []) {
          actionNames.add(a.name);
        }
      }
    }

    for (const app of config.apps) {
      const checkNavItems = (items: unknown[], appName: string) => {
        for (const item of items) {
          if (!item || typeof item !== 'object') continue;
          const nav = item as Record<string, unknown>;
          if (nav.type === 'object' && typeof nav.objectName === 'string' && !objectNames.has(nav.objectName)) {
            // `requiresObject` opts the nav item into "may be provided by
            // another stack / platform plugin" semantics — the frontend
            // hides the entry when the object isn't in the SchemaRegistry,
            // and stack-level cross-ref validation must skip it.
            if (!nav.requiresObject) {
              errors.push(
                `App '${appName}' navigation references object '${nav.objectName}' which is not defined in objects.`,
              );
            }
          }
          if (nav.type === 'dashboard' && typeof nav.dashboardName === 'string' && dashboardNames.size > 0 && !dashboardNames.has(nav.dashboardName)) {
            errors.push(
              `App '${appName}' navigation references dashboard '${nav.dashboardName}' which is not defined in dashboards.`,
            );
          }
          if (nav.type === 'page' && typeof nav.pageName === 'string' && pageNames.size > 0 && !pageNames.has(nav.pageName)) {
            errors.push(
              `App '${appName}' navigation references page '${nav.pageName}' which is not defined in pages.`,
            );
          }
          if (nav.type === 'report' && typeof nav.reportName === 'string' && reportNames.size > 0 && !reportNames.has(nav.reportName)) {
            errors.push(
              `App '${appName}' navigation references report '${nav.reportName}' which is not defined in reports.`,
            );
          }
          // Deep-link auto-run (#4848): a `runAction` that resolves to no
          // defined action is exactly the dead affordance the declared slot
          // exists to reject — the entry navigates and the auto-run silently
          // never fires. Size-gated like the dashboard/page/report checks
          // above: a stack declaring NO actions may be referencing one
          // provided by another package (lint's `validate-action-name-refs`
          // still reports it there).
          if (nav.type === 'object' && typeof nav.runAction === 'string' && actionNames.size > 0 && !actionNames.has(nav.runAction)) {
            errors.push(
              `App '${appName}' navigation deep-link references action '${nav.runAction}' (via runAction) which is not defined in actions (neither stack.actions nor any object's actions).`,
            );
          }
          // Recurse into children. NOT gated on `type === 'group'`: an `object`
          // nav item carries `children` too (NavigationItemSchema extends it
          // with a child array for per-view entries), and a targeted child
          // nested under one was previously skipped.
          if (Array.isArray(nav.children)) {
            checkNavItems(nav.children, appName);
          }
        }
      };
      // Both nav containers. `areas[]` was previously skipped entirely by an
      // `if (!app.navigation) continue`, so an areas-based app got NO nav
      // cross-reference checking at all (issue #3583).
      if (Array.isArray(app.navigation)) checkNavItems(app.navigation, app.name);
      if (Array.isArray(app.areas)) {
        for (const area of app.areas) {
          const nav = (area as { navigation?: unknown })?.navigation;
          if (Array.isArray(nav)) checkNavItems(nav, app.name);
        }
      }
    }
  }

  // Validate action → flow/modal cross-references
  // Note: When no flows/pages are defined (size === 0), targets are not validated
  // because the referenced items may be provided by a plugin.
  // This is consistent with dashboard/page/report validation in navigation.
  //
  // The name sets are hoisted out of the `config.actions` guard because the
  // INLINE walk below needs them too, and a stack whose only actions are inline
  // has no `config.actions` at all (#6889 probe row E was exactly that stack).
  const flowNames = new Set<string>();
  if (config.flows) {
    for (const flow of config.flows) {
      flowNames.add(flow.name);
    }
  }

  // One judgement for the three positions below. The leniency is the
  // stack's OWN flows being empty, unchanged by `artifactFlows` (#25514): the
  // option widens where a target is refused today and switches nothing on. A
  // target the option alone resolves is a claim on the artifact, recorded for
  // `composeStacks` to redeem rather than trusted.
  const checkFlowTarget = (subject: string, target: string | undefined): void => {
    if (!target || flowNames.size === 0 || flowNames.has(target)) return;
    if (artifactFlows?.has(target)) {
      flowClaims?.push({ subject, target });
      return;
    }
    errors.push(flowTargetMessage(subject, target));
  };

  const pageNames = new Set<string>();
  if (config.pages) {
    for (const page of config.pages) {
      pageNames.add(page.name);
    }
  }

  // [#17063] The `type: 'page'` list-view → page existence branch was REMOVED
  // here with the mount itself (ADR-0049 enforce-or-remove, maintainer ruling
  // 2026-09-09 「撤」). It was the THIRD surface in this function that named a
  // page; the surviving two — an app nav item's `pageName` and a modal action's
  // `target`, both below — are untouched, as is `pageNames` itself, which they
  // share. A list view can no longer carry `pageName` at all (the key is a
  // `retiredKey()` tombstone on `ListViewSchema`), so there is no reference
  // left to resolve rather than a resolution left unchecked.

  const extendedObjectNames = new Set<string>(
    (config.objectExtensions ?? [])
      .map((ext) => (isRecord(ext) ? ext.extend : undefined))
      .filter((name): name is string => typeof name === 'string' && name.length > 0),
  );
  if (config.actions) {
    for (const action of config.actions) {
      // Validate flow-type actions reference a defined flow
      if (action.type === 'flow') checkFlowTarget(`Action '${action.name}'`, action.target);

      // Validate modal-type actions reference a defined page
      if (action.type === 'modal' && action.target && pageNames.size > 0 && !pageNames.has(action.target)) {
        errors.push(
          `Action '${action.name}' references page '${action.target}' (via modal target) which is not defined in pages.`,
        );
      }

      // Validate action → object references (objectName). [#24400] Two kinds
      // of target outside this stack's `objects` are accepted, because this
      // stack's own metadata says the object exists elsewhere: one it EXTENDS
      // (`objectExtensions` — the route that shape's `guidance.actions` names,
      // since an extension cannot carry `actions`), and a KNOWN platform
      // object (`isPlatformProvidedObjectName`, a named list — not the
      // prefix, so `sys_organizaton` is still refused here). Such an action
      // stays at the top level ({@link mergeActionsIntoObjects}), and the
      // engine's registry attaches it to the object when the object is served;
      // a target no loaded package registers is refused at boot. Any other
      // name is refused here: this stack cannot tell another package's object
      // from a typo.
      if (
        action.objectName &&
        !objectNames.has(action.objectName) &&
        !extendedObjectNames.has(action.objectName) &&
        !isPlatformProvidedObjectName(action.objectName)
      ) {
        errors.push(
          `Action '${action.name}' references object '${action.objectName}' which is not defined in objects.`,
        );
      }
    }
  }

  // The SAME two target checks, one more traversal: actions authored directly
  // on an object (`config.objects[].actions[]`) — #7397, the #6889 defect one
  // authoring position over.
  //
  // Why the registered walk above cannot cover it: `validateCrossReferences`
  // runs BEFORE `mergeActionsIntoObjects`, and that merge only ever copies
  // top-level → object (by `objectName`), never the reverse. An action authored
  // ONLY on the object therefore never appears in `config.actions` and reached
  // no cross-reference check at all — measured on #7397, where an embedded
  // `type: 'modal', target: 'probe_nowhere'` built clean while the identical
  // action in the registered position was refused.
  //
  // This position carries the FULL `ActionSchema` (`object.zod.ts`'s
  // `actions: z.array(ActionSchema)`) — the identical symbol the registered
  // collection uses at `:256`, not a narrower embedded shape — so `name` is
  // required here and `target` has already been canonicalized by the parse
  // this function runs after. Only the SUBJECT of the message differs from the
  // registered rule: an embedded action is located by its owning object.
  //
  // Scope of the modal branch is the same #6739 ruling the other two arms
  // read: a `type: 'modal'` target names a PAGE, only.
  //
  // Third arm: `objectName` → declared object, mirrored onto the embedded
  // position (#7456, Option A — existence check, ruled 2026-08-11/12). This
  // is the identical check the registered walk applies above; only the
  // SUBJECT differs, same as the flow/modal arms just above. It does NOT
  // give `objectName` new meaning at this position — `mergeActionsIntoObjects`
  // still builds its map only from `config.actions`, so the key stays inert
  // for merge purposes. It only makes a dangling value refused at authoring
  // time, same as it already is in the registered position.
  //
  // Deliberately NOT checked: whether `objectName` here must equal the
  // owning object's own name (Option B), or whether the key should be
  // retired at this position instead (Option C) — both stay open per the
  // issue and are not foreclosed by this existence check.
  if (config.objects) {
    for (const obj of config.objects) {
      for (const action of obj.actions ?? []) {
        if (action.type === 'flow') checkFlowTarget(`Action '${action.name}' on object '${obj.name}'`, action.target);

        if (action.type === 'modal' && action.target && pageNames.size > 0 && !pageNames.has(action.target)) {
          errors.push(
            `Action '${action.name}' on object '${obj.name}' references page '${action.target}' (via modal target) which is not defined in pages.`,
          );
        }

        if (action.objectName && !objectNames.has(action.objectName)) {
          errors.push(
            `Action '${action.name}' on object '${obj.name}' references object '${action.objectName}' which is not defined in objects.`,
          );
        }
      }
    }
  }

  // The SAME two target checks, one more traversal: inline (page-element)
  // actions (#6889). Same rule, same message tail — only the subject differs,
  // because an inline action is located by page + path rather than by a
  // registry entry, and its `name` is optional.
  //
  // `objectName` has no inline counterpart to check: `InlineActionSchema` does
  // not pick that key, so an inline action cannot bind an object by name.
  //
  // Scope of the modal branch is the maintainer's #6739 ruling (2026-08-09):
  // "A — a `type: 'modal'` target names a PAGE, only." That is why the inline
  // branch mirrors the registered one exactly instead of also accepting an
  // object name — objectui's page-then-object resolution is consumer leniency
  // (self-labelled "Back-compat") and is being retired on its own card.
  if (config.pages) {
    for (const page of config.pages) {
      for (const { action, where } of collectInlinePageActions(page)) {
        if (action.type === 'flow') checkFlowTarget(where, action.target);

        if (action.type === 'modal' && action.target && pageNames.size > 0 && !pageNames.has(action.target)) {
          errors.push(
            `${where} references page '${action.target}' (via modal target) which is not defined in pages.`,
          );
        }
      }
    }
  }

  return errors;
}

/**
 * Stable-sort an actions array by explicit `order` (lower = higher / earlier).
 *
 * - Actions that leave `order` unset are treated as `0`.
 * - The sort is STABLE (`Array.prototype.sort` is stable since ES2019), so
 *   actions that tie on `order` — including the overwhelmingly common case where
 *   NOBODY sets `order` — keep their original registration order. This is what
 *   lets `order` promote a `record_header` action into the primary-button slot
 *   without disturbing everything else.
 * - Returns the SAME array reference untouched when no action opts in, so callers
 *   pay zero allocation on the common path and can cheaply detect "unchanged".
 *
 * @internal
 */
function sortActionsByOrder<T extends { order?: number }>(actions: T[]): T[] {
  if (!actions.some((a) => a.order !== undefined)) return actions;
  // Copy first so the stable sort never mutates the caller's array.
  return actions.slice().sort((a, b) => (a.order ?? 0) - (b.order ?? 0));
}

/**
 * Merge top-level actions into their target objects based on `objectName`, then
 * honour each action's explicit `order`.
 *
 * Actions with `objectName` are appended to the corresponding object's `actions`
 * array. Actions without `objectName` (global actions) are left in place. The
 * top-level `actions` array is preserved for global access (e.g., platform
 * overview, search).
 *
 * [#24400] An action whose `objectName` names an object NOT in this stack — one
 * this stack extends through `objectExtensions`, or a platform object, the two
 * cases `validateCrossReferences` accepts — is merged into nothing here,
 * because this merge cannot see another package's objects. It stays in the
 * top-level `actions`, registers as a standalone `action` item, and the
 * engine's `SchemaRegistry` attaches it to the target when the target is
 * served (`attachBoundActions`, in whichever order the two register). A
 * target no loaded package registers fails the boot, naming the action.
 *
 * Idempotent over its own output (#14847): a bound action the object already
 * carries BY IDENTITY is not appended again. That is the shape `composeStacks`
 * feeds it — inputs built by `defineStack`, each object already carrying the
 * copy its own build appended while the standalone still sits in `actions` —
 * and before this the second merge doubled every bound action in the composed
 * object (three copies for two declarations under `objectConflict: 'override'`
 * / `'merge'`). Identity, deliberately not equality: an author writing one
 * action in both positions produces two distinct objects, which commit 279431e7a's
 * same-key refusal (run before this merge) rejects and which this merge must
 * not quietly fold.
 *
 * After merging, every action group (each object's `actions` and the top-level
 * `actions`) is stable-sorted by `order` via {@link sortActionsByOrder}. Because
 * that sort is a no-op unless an author sets `order`, this is fully backward
 * compatible — arrays with no `order` keep their exact registration order and
 * reference. Renderers that pick a single primary action from `record_header`
 * (objectui) therefore see approve/reject-style actions in their declared
 * priority rather than in fragile cross-file registration order.
 *
 * This aligns with Salesforce/ServiceNow patterns where object metadata includes
 * its actions, so API responses like `/api/v1/meta/objects/:name` include actions
 * (already ordered) without downstream merge.
 *
 * @internal
 */
function mergeActionsIntoObjects(config: ObjectStackDefinition): ObjectStackDefinition {
  // [ADR-0112 · #19785] Shape guard, because `defineStack(config, { strict:
  // false })` hands this merge the normalized input with no parse in between.
  // A non-array `objects` is REFUSED with the strict parse's own envelope
  // (`STACK_SCHEMA_INVALID`, 422, the zod issue at `['objects']`) — never a bare
  // `TypeError` from `.map`, and never a pass-through: bound actions cannot be
  // merged into objects that are not a list, and a stack handed on in that
  // shape is one `composeStacks` refuses with this same code anyway. `strict:
  // false` skips VALIDATION (cross-references, schema detail); it never
  // promised to accept a shape this merge cannot read. `undefined` is the one
  // non-array that is not malformed — the key is simply absent — the same line
  // `mergeObjects` draws for the same key.
  const declaredObjects: unknown = (config as { objects?: unknown }).objects;
  if (declaredObjects !== undefined && !Array.isArray(declaredObjects)) {
    const { kind, issues } = describeNonArrayCollection('objects', declaredObjects);
    throw new StackSchemaInvalidError(
      `defineStack validation failed: 'objects' is ${kind}, not an array. Bound actions cannot be ` +
        `merged into it, and \`strict: false\` skips validation, not this shape — \`composeStacks\` ` +
        `refuses the same stack with the same code. Author 'objects' as an array or in the map form ` +
        `(\`{ name: { … } }\`), or drop \`strict: false\` to have every schema check run.`,
      issues,
    );
  }

  // [#19785] A non-object ENTRY is refused with the same envelope, one zod
  // issue per entry at `['objects', index]` (`expected: 'object'`) — the
  // strict parse's own answer for it. Never handed on: the merge cannot read
  // it, and a stack returned with it is a success whose objects are not all
  // objects — the next consumer (plugin-object registration) then drops every
  // object after it inside one warn-level catch, which is concealment, not
  // leniency.
  if (Array.isArray(declaredObjects) && declaredObjects.some((entry) => !isRecord(entry))) {
    const parsed = z.array(z.looseObject({})).safeParse(declaredObjects);
    const issues = parsed.success
      ? []
      : parsed.error.issues.map((issue) => ({ ...issue, path: ['objects', ...issue.path] }));
    const positions = declaredObjects
      .map((entry, index) => (isRecord(entry) ? null : `#${index} (${entry === null ? 'null' : Array.isArray(entry) ? 'an array' : `a ${typeof entry}`})`))
      .filter((position): position is string => position !== null);
    throw new StackSchemaInvalidError(
      `defineStack validation failed: 'objects' holds ${positions.length === 1 ? 'an entry' : 'entries'} ` +
        `that ${positions.length === 1 ? 'is' : 'are'} not an object — ${positions.join(', ')}. Bound actions ` +
        `cannot be merged into such an entry, and \`strict: false\` skips validation, not this shape. Author ` +
        `every entry of 'objects' as an object definition, or drop \`strict: false\` to have every schema ` +
        `check run.`,
      issues as z.core.$ZodIssue[],
    );
  }

  // [ADR-0112 · #19799] The same guard for every `actions` array this merge
  // reads — the top-level one and each object's own — because
  // `sortActionsByOrder` calls `.some` on it and reads `order` off each entry:
  // a non-array raised a bare `TypeError` (`actions.some is not a function`),
  // a `null` entry one reading `order`, and any other non-object entry was
  // handed on inside a success. Each is refused with the strict parse's own
  // envelope at the strict parse's own path — `['actions']` /
  // `['actions', index]`, `['objects', i, 'actions']` /
  // `['objects', i, 'actions', index]` — all findings in one refusal, as the
  // parse reports them. `undefined` is the one non-array that is not
  // malformed: the key is absent. This merge also ends `composeStacks`
  // (step 7), which refuses a non-array top-level `actions` in its own step 3
  // with this same code, so the message names both doors.
  const actionsProblems: string[] = [];
  const actionsIssues: z.core.$ZodIssue[] = [];
  const guardActions = (prefix: readonly (string | number)[], label: string, declared: unknown): void => {
    if (declared === undefined) return;
    const reroot = (issue: z.core.$ZodIssue): z.core.$ZodIssue =>
      ({ ...issue, path: [...prefix, ...issue.path] }) as z.core.$ZodIssue;
    if (!Array.isArray(declared)) {
      const { kind, issues } = describeNonArrayCollection('actions', declared);
      actionsProblems.push(`${label} is ${kind}, not an array`);
      actionsIssues.push(...issues.map(reroot));
      return;
    }
    const positions = declared
      .map((entry, index) =>
        isRecord(entry) ? null : `#${index} (${entry === null ? 'null' : Array.isArray(entry) ? 'an array' : `a ${typeof entry}`})`,
      )
      .filter((position): position is string => position !== null);
    if (positions.length === 0) return;
    const parsed = z.array(z.looseObject({})).safeParse(declared);
    if (!parsed.success) {
      actionsIssues.push(
        ...parsed.error.issues.map((issue) => reroot({ ...issue, path: ['actions', ...issue.path] } as z.core.$ZodIssue)),
      );
    }
    actionsProblems.push(
      `${label} holds ${positions.length === 1 ? 'an entry' : 'entries'} that ` +
        `${positions.length === 1 ? 'is' : 'are'} not an object — ${positions.join(', ')}`,
    );
  };
  guardActions([], "'actions'", (config as { actions?: unknown }).actions);
  for (const [index, obj] of ((declaredObjects as Record<string, unknown>[] | undefined) ?? []).entries()) {
    const label = typeof obj.name === 'string' ? `object '${obj.name}'` : `object #${index}`;
    guardActions(['objects', index], `${label}'s 'actions'`, obj.actions);
  }
  if (actionsProblems.length > 0) {
    throw new StackSchemaInvalidError(
      `Stack validation failed (the bound-action merge that ends \`defineStack\` and \`composeStacks\`): ` +
        `${actionsProblems.join('; ')}. Actions cannot be merged or ordered by \`order\` in that shape, and ` +
        `\`strict: false\` skips validation, not this shape. Author every 'actions' as an array of action ` +
        `definitions, or drop \`strict: false\` to have every schema check run.`,
      actionsIssues,
    );
  }

  // Honour `order` on the preserved top-level actions regardless of objects.
  const sortedTop = config.actions ? sortActionsByOrder(config.actions) : config.actions;
  const topChanged = sortedTop !== config.actions;

  if (!config.objects || config.objects.length === 0) {
    return topChanged ? { ...config, actions: sortedTop } : config;
  }

  // Build map: objectName → actions[] (top-level actions targeting an object)
  const actionsByObject = new Map<string, NonNullable<ObjectStackDefinition['actions']>>();
  for (const action of config.actions ?? []) {
    if (action.objectName) {
      const list = actionsByObject.get(action.objectName) ?? [];
      list.push(action);
      actionsByObject.set(action.objectName, list);
    }
  }

  // Merge into objects and sort each object's final actions by `order` (shallow
  // copy — only the `actions` field is modified; other fields stay shared
  // references, consistent with mergeObjects() and Zod output).
  let objectsChanged = false;
  const newObjects = config.objects.map((obj) => {
    const base = obj.actions ?? [];
    // Idempotent (#14847): append only the bound actions `base` does not carry
    // ALREADY — judged by identity, never by equality. The one way an entry of
    // `config.actions` can be the very same object as an entry of `obj.actions`
    // is a previous run of this merge having put it there: `defineStack` ends
    // here, so a BUILT stack carries each bound action in both positions, and
    // `composeStacks` — which concatenates its inputs' `actions` and hands the
    // surviving objects through as-is — ran this merge a second time over that
    // echo and doubled every bound action. A hand-written twin (one action
    // authored in both positions) is two objects after the strict parse, and
    // commit 279431e7a's same-key refusal has already run ahead of this merge to refuse
    // it; an equality skip here would have swallowed it instead.
    const fresh = (actionsByObject.get(obj.name) ?? []).filter((action) => !base.includes(action));
    const merged = fresh.length > 0 ? [...base, ...fresh] : base;
    const sorted = sortActionsByOrder(merged);
    // Untouched: nothing new merged in AND the sort was a no-op.
    if (sorted === base) return obj;
    objectsChanged = true;
    return { ...obj, actions: sorted };
  });

  if (!objectsChanged && !topChanged) return config;
  return {
    ...config,
    ...(objectsChanged ? { objects: newObjects } : {}),
    ...(topChanged ? { actions: sortedTop } : {}),
  };
}

/**
 * Type-safe helper to define a generic stack.
 *
 * In ObjectStack, the concept of "Project" and "Plugin" is fluid:
 * - A **Project** is simply a Stack that is currently being executed (the `cwd`).
 * - A **Plugin** is a Stack that is being loaded by another Stack.
 *
 * This unified definition allows any "Project" (e.g., Todo App) to be imported
 * as a "Plugin" into a larger system (e.g., Company PaaS) without code changes.
 *
 * @param config - The stack definition object
 * @param options - Optional settings. Use `{ strict: true }` to validate cross-references.
 * @returns The validated stack definition
 *
 * @example
 * ```ts
 * // Basic usage (pass-through, backward compatible)
 * const stack = defineStack({ manifest: { ... }, objects: [...] });
 *
 * // Map format — key becomes `name` field
 * const stack = defineStack({
 *   objects: {
 *     task: { fields: { title: { type: 'text' } } },
 *     project: { fields: { name: { type: 'text' } } },
 *   },
 *   apps: {
 *     project_manager: { label: 'Project Manager', objects: ['task', 'project'] },
 *   },
 * });
 *
 * // Strict mode — validates that views/workflows reference defined objects
 * const stack = defineStack({ manifest: { ... }, objects: [...], views: [...] }, { strict: true });
 * ```
 */
/**
 * [ADR-0057] HIERARCHY access scopes (`unit` / `unit_and_below` /
 * `own_and_reports`) are an ENTERPRISE capability — their enforcement ships in
 * `@objectstack/security-enterprise`, not the open edition. A stack that uses
 * one MUST declare `requires: ['hierarchy-security']`; otherwise the open
 * runtime would silently fail closed to owner-only (the metadata would lie,
 * ADR-0049). This makes that an authoring-time error instead.
 */
function validateHierarchyScopeCapability(data: unknown): string[] {
  const d = data as { requires?: unknown; permissions?: unknown };
  const requires = Array.isArray(d?.requires) ? (d.requires as string[]) : [];
  if (requires.includes('hierarchy-security')) return [];
  // The scope list and the finding sentence are shared with the runtime
  // metadata save/publish gate, which judges the same grant (#26188).
  return findHierarchyScopeGrants(d?.permissions).map((g) =>
    `${g.finding}. ` +
    `Declare \`requires: ['hierarchy-security']\` (provided by @objectstack/security-enterprise) — ` +
    `the open edition cannot enforce it and would fail closed to owner-only.`,
  );
}

/**
 * Auto-launched flows are an ENFORCED capability class, exactly like the
 * hierarchy scopes above: the trigger that fires a `record_change` /
 * `schedule` / `time_relative` / `api` flow ships in `@objectstack/trigger-*`
 * and is installed by the PAIR `requires: ['automation', 'triggers']`.
 * `triggers` mounts the trigger plugins
 * (`PLATFORM_CAPABILITY_PROVIDERS.triggers`); each of them installs its
 * trigger INTO the automation service at `kernel:ready`, and without that
 * service installs nothing — `RecordChangeTriggerPlugin`,
 * `ScheduleTriggerPlugin`, `TimeRelativeTriggerPlugin` and `ApiTriggerPlugin`
 * each warn `automation service not available — … trigger NOT installed` and
 * return. `automation` mounts that service (`@objectstack/service-automation`,
 * the engine that runs the flow). Neither token implies the other on any
 * runtime's resolver: `os serve` expands neither, and cloud's
 * `resolveCapabilityDependencies` pulls `queue` / `job` / `messaging` for
 * `triggers`, never `automation`. So all four kinds need both tokens.
 *
 * A stack that declares such a flow while `requires` omits either token
 * registers the flow, validates, builds — and never fires it. The automation
 * engine's boot audit names the missing `triggers` after deploy (`declares a
 * '…' trigger but is NOT bound`); the missing `automation` is named only by
 * the trigger plugin's warn and the CLI banner's `the automation engine is
 * not enabled — they will never run`, and nothing before that. That is the
 * fail-SILENT half of the pair: a hierarchy scope without its capability fails
 * closed (a user notices the missing rows); an autolaunched flow without its
 * trigger fails silent (the automation simply does not happen). Refuse it
 * here, at authoring, in the boot audit's own words — one vocabulary, moved
 * from post-deploy to author time. ⛔ `triggers` never IMPLIES `automation`
 * here either: that would switch on a service the author did not name.
 *
 * One line per offending flow, and its prescription is the WHOLE fix for the
 * `requires` it was given, so following it once is enough:
 *
 *   `automation` present, `triggers` missing → add `'triggers'` (the message
 *                                              this refusal has always said);
 *   `triggers` present, `automation` missing → add `'automation'`;
 *   neither                                  → add both, `['automation', 'triggers']`
 *                                              — never `['triggers']` alone,
 *                                              which the arm above would refuse.
 *
 * An ABSENT `requires` counts as omitting both tokens: the CLI reads it as
 * `[]` and appends only the always-on slate (`PLATFORM_ALWAYS_ON_CAPABILITIES`),
 * which carries neither `automation` nor `triggers`, so a stack that declares
 * nothing gets no trigger either (measured on `serve`'s capability resolver).
 *
 * Flows whose `status` disables them (`obsolete` / `invalid`) are skipped —
 * the engine never binds those, its boot audit skips them for the same
 * reason, and a stack that deliberately retired a triggered flow owes no
 * capability for it. A stack with no auto-launched flow owes neither token.
 * The kind is `resolveFlowTriggerKind`, shared with `@objectstack/lint`, so the
 * two authoring surfaces cannot disagree on which flows auto-launch.
 */
function validateTriggerCapability(data: unknown): string[] {
  const errors: string[] = [];
  const d = data as { requires?: unknown; flows?: unknown };
  const requires = Array.isArray(d?.requires) ? (d.requires as string[]) : [];
  const hasTriggers = requires.includes('triggers');
  const hasAutomation = requires.includes('automation');
  if (hasTriggers && hasAutomation) return errors;
  const flows = Array.isArray(d?.flows) ? (d.flows as unknown[]) : [];
  for (const flow of flows) {
    const f = flow as { name?: unknown; status?: unknown } | null;
    if (f?.status === 'obsolete' || f?.status === 'invalid') continue;
    const kind = resolveFlowTriggerKind(flow);
    if (!kind) continue;
    const name = typeof f?.name === 'string' ? f.name : '?';
    const subject = `flow '${name}' declares a '${kind}' trigger but \`requires\` does not include`;
    if (!hasTriggers && hasAutomation) {
      errors.push(
        `${subject} 'triggers' — ` +
          `no '${kind}' trigger would be registered, so the flow would never auto-launch. ` +
          `Add requires: ['triggers'] (record_change/schedule/time_relative/api ship in @objectstack/trigger-*).`,
      );
    } else if (hasTriggers) {
      errors.push(
        `${subject} 'automation' — ` +
          `'triggers' installs the '${kind}' trigger into the automation service, and without it no '${kind}' ` +
          `trigger would be registered, so the flow would never auto-launch. ` +
          `Add 'automation' to requires: ['automation', 'triggers'] ` +
          `(@objectstack/service-automation runs the flow; @objectstack/trigger-* only fires it).`,
      );
    } else {
      errors.push(
        `${subject} 'automation' or 'triggers' — ` +
          `no '${kind}' trigger would be registered, so the flow would never auto-launch. ` +
          `Add requires: ['automation', 'triggers'] (record_change/schedule/time_relative/api ship in ` +
          `@objectstack/trigger-* and install into @objectstack/service-automation — 'triggers' alone installs nothing).`,
      );
    }
  }
  return errors;
}

/**
 * Declared webhooks are the THIRD declared-capability class (ruling A on
 * #24910), beside the hierarchy scopes and the auto-launched flows above, and
 * of the fail-SILENT kind, like the flows. A declared webhook is dispatched by
 * the PAIR `requires: ['webhooks', 'realtime']`:
 *
 *   · `webhooks` mounts `@objectstack/plugin-webhooks`
 *     (`PLATFORM_CAPABILITY_PROVIDERS.webhooks`), whose auto-enqueuer turns a
 *     record event into a `sys_http_delivery` row. Without it nothing reads
 *     the declaration at all: no reader is bound, and the activation door
 *     answers that it cannot verify the webhook.
 *   · `realtime` mounts `@objectstack/service-realtime`, the auto-enqueuer's
 *     ONLY source of record events. Without it the plugin boots, the
 *     activation door answers `enabled: true`, every record write answers
 *     200 — and no delivery is ever enqueued. The plugin's boot `error`
 *     (`[webhook-auto-enqueuer] disabled …`) is the only trace, after deploy,
 *     and it stays: it is what a host that wires a stack by hand, past this
 *     producer, still sees.
 *
 * Neither token implies the other on any runtime's resolver (`os serve`
 * expands neither), and the messaging outbox the auto-enqueuer writes to is on
 * the always-on slate (`PLATFORM_ALWAYS_ON_CAPABILITIES`), so it is owed by
 * nobody's `requires`. A stack that declares a webhook while `requires` omits
 * either token validates, builds, boots and never delivers. Refuse it here, at
 * authoring, so every door that loads the stack (`os validate`, `os build`,
 * `os serve` / `os dev`, an app's own `bootStack` tests) refuses it with the
 * same sentence. ⛔ Neither token is IMPLIED or added here: that would switch
 * on a service the author did not name.
 *
 * One line per declared webhook, and its prescription is the WHOLE fix for the
 * `requires` it was given, so following it once is enough:
 *
 *   `realtime` present, `webhooks` missing → add `'webhooks'`;
 *   `webhooks` present, `realtime` missing → add `'realtime'`;
 *   neither                                → add both, `['webhooks', 'realtime']`
 *                                            — never `['webhooks']` alone,
 *                                            which the arm above would refuse.
 *
 * An ABSENT `requires` counts as omitting both tokens, for the reason the
 * trigger rule gives: the CLI reads it as `[]` plus the always-on slate, which
 * carries neither token.
 *
 * Every declared webhook counts, `isActive: false` included — unlike a retired
 * flow, an inactive declaration is one activation-door write away from being
 * switched on (the ledger row overrides the declared `isActive`, ADR-0131 D6),
 * and the switch it would then flip delivers nothing. A stack with no webhook
 * owes neither token. Only the top-level `webhooks:` collection is read: it is
 * the one the declared-webhook reader dispatches (a connector's nested
 * `webhooks[]` is retired under ADR-0049 and never dispatched).
 */
function validateWebhookCapability(data: unknown): string[] {
  const errors: string[] = [];
  const d = data as { requires?: unknown; webhooks?: unknown };
  const requires = Array.isArray(d?.requires) ? (d.requires as string[]) : [];
  const hasWebhooks = requires.includes('webhooks');
  const hasRealtime = requires.includes('realtime');
  if (hasWebhooks && hasRealtime) return errors;
  const webhooks = Array.isArray(d?.webhooks) ? (d.webhooks as unknown[]) : [];
  for (const webhook of webhooks) {
    const w = webhook as { name?: unknown } | null;
    const name = typeof w?.name === 'string' ? w.name : '?';
    const subject = `webhook '${name}' is declared but \`requires\` does not include`;
    if (!hasWebhooks && hasRealtime) {
      errors.push(
        `${subject} 'webhooks' — ` +
          `no webhook dispatcher would be mounted, so a record write would never enqueue a delivery. ` +
          `Add 'webhooks' to requires: ['webhooks', 'realtime'] ` +
          `(@objectstack/plugin-webhooks dispatches the webhook).`,
      );
    } else if (hasWebhooks) {
      errors.push(
        `${subject} 'realtime' — ` +
          `the webhook dispatcher's only source of record events is the realtime service, and without it ` +
          `a record write would never enqueue a delivery. ` +
          `Add 'realtime' to requires: ['webhooks', 'realtime'] ` +
          `(@objectstack/service-realtime publishes the record events; @objectstack/plugin-webhooks only dispatches them).`,
      );
    } else {
      errors.push(
        `${subject} 'webhooks' or 'realtime' — ` +
          `no webhook dispatcher would be mounted, so a record write would never enqueue a delivery. ` +
          `Add requires: ['webhooks', 'realtime'] (@objectstack/plugin-webhooks dispatches the webhook from the ` +
          `record events @objectstack/service-realtime publishes — 'webhooks' alone enqueues nothing).`,
      );
    }
  }
  return errors;
}

/**
 * Reject `requires` tokens that are not part of the platform capability
 * vocabulary (framework#3265). An unknown token is a genuine typo or a stale
 * reference that NO runtime provides, so every runtime would otherwise SILENTLY
 * ignore it (declared ≠ enforced). Fail at the producer, loudly (Prime
 * Directive #12): the vocabulary is the union of every token the framework CLI
 * and cloud's objectos-runtime resolve, plus the enterprise plugin-provided ones
 * (`hierarchy-security` / `ai-seat` / `governance`). The legacy `aiStudio` /
 * `aiSeat` aliases were removed in #3308, so those now reject too. A RETIRED
 * capability (`RETIRED_PLATFORM_CAPABILITY_GUIDANCE`, e.g. `reports`) rejects
 * with its retirement prescription instead of the typo advice. Returns one
 * error per distinct unknown token.
 */
function validateKnownCapabilities(config: ObjectStackDefinition): string[] {
  const raw = config.requires;
  if (!raw || raw.length === 0) return [];
  const seen = new Set<string>();
  const errors: string[] = [];
  for (const token of raw) {
    if (PLATFORM_CAPABILITY_TOKENS.includes(token) || seen.has(token)) continue;
    seen.add(token);
    // A RETIRED token is not a typo — the word used to be right — so it gets
    // the retirement notice and its replacement instead of the typo advice.
    if (Object.prototype.hasOwnProperty.call(RETIRED_PLATFORM_CAPABILITY_GUIDANCE, token)) {
      errors.push(RETIRED_PLATFORM_CAPABILITY_GUIDANCE[token]);
      continue;
    }
    errors.push(
      `requires: '${token}' is not a known platform capability — check for a typo ` +
        `(known tokens are kebab-case, e.g. 'ai-studio', 'pinyin-search', 'automation'). ` +
        `No runtime provides it, so it would be silently ignored.`,
    );
  }
  return errors;
}

/** Conversion notices already reported this process — same warn-once reason. */
const warnedConversionNotices = new Set<string>();

/**
 * Surface the ADR-0087 D2 conversion notices raised while normalizing.
 *
 * A conversion is deliberately silent about *fixing* the shape — zero consumer
 * action is the point — but it is not supposed to be silent about having HAD to.
 * The notice is the one signal that says "this spelling retires in protocol N,
 * and your metadata stops loading then", and `defineStack` is where the author
 * who wrote the old shape actually is. Until now it passed no sink, so that
 * author heard nothing unless they happened to run `os validate` — the same gap
 * this change closes in `os build`.
 *
 * Advisory and warn-once: the conversion already produced a correct stack.
 */
function warnConversionNotice(notice: ConversionNotice): void {
  const key = `${notice.conversionId} ${notice.path} ${notice.from} ${notice.to}`;
  if (warnedConversionNotices.has(key)) return;
  warnedConversionNotices.add(key);
  console.warn(
    `defineStack: ${notice.path}: '${notice.from}' → '${notice.to}' (converted at load; ` +
    `conversion '${notice.conversionId}', retires in protocol ${notice.retiresIn}). ` +
    `Update the source to the canonical shape — the conversion stops running then.`,
  );
}

const warnedUnknownAuthoringKeys = new Set<string>();

/**
 * Surface every authored key `ObjectSchema` / `FieldSchema` is about to discard
 * (#3786).
 *
 * Same seam and same posture as {@link warnConversionNotice}: it runs pre-parse,
 * because the parse is what eats the key, and it only WARNS — these two schemas
 * are the most-authored surfaces in the protocol, so rejecting is a scheduled
 * migration (#4001's strict tiers), not something to slip in behind a lint.
 *
 * Runs in both strict and non-strict mode: the key is dropped either way, so the
 * author deserves to hear about it either way.
 */
function warnUnknownAuthoringKeys(raw: unknown): void {
  const findings = [
    // Top level first: an undeclared envelope key is the one that reads as
    // configuration that took effect (#4167).
    ...lintUnknownStackKeys(raw, ObjectStackDefinitionSchema),
    ...lintUnknownAuthoringKeys(raw, ObjectStackDefinitionSchema),
  ];
  for (const finding of findings) {
    if (warnedUnknownAuthoringKeys.has(finding.path)) continue;
    warnedUnknownAuthoringKeys.add(finding.path);
    console.warn(`defineStack: ${formatUnknownAuthoringKey(finding)}`);
  }
}

const warnedEmailTemplateFloors = new Set<string>();

/**
 * Report an `emailTemplates` bundle that carries rows for this stack's own
 * `i18n.supportedLocales` but none tagged {@link EMAIL_TEMPLATE_FLOOR_LOCALE}.
 *
 * ## What goes wrong without this
 *
 * `IEmailService.sendTemplate` reads one row at one tag exactly. For a call
 * that NAMES a locale, over the built-in registry template loader, it folds
 * that locale against the bundle's tags (`resolveBundleLocale`: exact,
 * case-insensitive, base language, variant expansion), then the stack's
 * declared fallback locale (`i18n.fallbackLocale`, else `defaultLocale`) the
 * same way, then the literal `en-US` (#28880); a replacement `TemplateLoader`
 * matches the named tag exactly and retries only `en-US`. So a bundle with no
 * `en-US` row is reachable from a recipient tag only when that tag or the
 * declared fallback folds to one of its rows, and behind a replacement loader
 * only from the tags it carries exactly. Every other delivery raises
 * `TEMPLATE_NOT_FOUND`, which classifies **permanent**, so it dead-letters
 * with no retry. `sys_user.locale`
 * is user-editable free-text BCP-47 and is NOT constrained to
 * `supportedLocales`, so the locales that can reach the lookup are not the ones
 * the author enumerated — a recipient can break their own mail by setting a
 * legal tag.
 *
 * ⛔ A call that names NO locale is the other case, and it does not fail: it
 * starts at `en-US` by name and, when the bundle carries no `en-US` row, drops
 * to that bundle's lowest locale tag and renders it silently. So one floorless
 * bundle dead-letters the recipients whose locale was named and quietly fills
 * for the ones whose was not. The full ladders are on
 * `SendTemplateInput.locale` in `packages/spec/src/contracts/email-service.ts`
 * and are not restated here.
 *
 * ⭐ The CONSISTENT thing an author writes, a stack declaring
 * `defaultLocale: 'en'` whose English row says `locale: 'en'`, validates,
 * builds and installs clean. Over the built-in loader, on a host whose i18n
 * service answers that declared fallback, it reaches every recipient; behind
 * a replacement loader, or on a host that declares no fallback, it still has
 * no floor. This report reads the bundle alone, so it fires for that shape
 * whichever host serves it: `en-US` is the one rung every loader retries.
 *
 * ## Posture — advisory, and deliberately so
 *
 * Same seam and same posture as {@link warnUnknownAuthoringKeys}: this only
 * WARNS. It moves no accept set — the parse above already succeeded and its
 * result is returned unchanged — because refusing an `emailTemplates` shape
 * that ships today would be a behaviour change on an authoring surface, which
 * is a scheduled migration rather than something to slip in behind a lint. The
 * resolver's ladder is fenced by a standing ruling and is NOT touched here: the
 * remedy this points at is the bundle.
 *
 * Runs post-parse, on the value the schema produced. `locale` defaults to
 * `en-US`, so a row that omits the key entirely already has the floor and must
 * not be reported — the reader below mirrors that default rather than relying
 * on the call site for it, so the two agree wherever this is called from.
 * Warn-once per bundle, keyed by name plus the tags it actually carries.
 *
 * ## What this deliberately does NOT examine
 *
 * Two shapes leave here silently and both can still ship a floorless bundle.
 * They are written down because the summary line above is the only place the
 * scope was ever stated, while the hazard section reads as a promise to catch
 * every floorless bundle — which this does not do:
 *
 *  1. **A stack whose `i18n.supportedLocales` is absent or empty.** Measured:
 *     `i18n` is optional but `supportedLocales` is REQUIRED inside it, so the
 *     absent arm is reached only by a stack carrying no `i18n` block at all,
 *     and the empty arm only by a literal `supportedLocales: []`. Either way
 *     there is nothing to measure "carries rows for this stack's own supported
 *     locales" against, so the function returns before building anything.
 *     ⚠️ This early return is not a second scope decision: with no supported
 *     set every bundle's `declared` list below is empty and shape 2 would skip
 *     it anyway, so what the return actually buys is not reading `.map` off
 *     `undefined`.
 *  2. **A bundle whose tags are ALL outside `supportedLocales`.** `declared` is
 *     empty, so the bundle is skipped one line after the floor check
 *     established that it carries no floor row. A stack supporting `en-US`
 *     whose bundle is tagged `en` alone is exactly that case: floorless, and
 *     silent here.
 *
 * ⚠️ Whether either shape SHOULD warn is the ADR-0049 enforce-or-remove
 * question, and it is deliberately not answered here: widening a `defineStack`
 * diagnostic is a behaviour change on an authoring surface, which the posture
 * note above puts on a scheduled migration rather than behind a lint. What is
 * closed is the silence being UNDECLARED — both shapes are pinned in
 * `stack-email-template-locale-floor.test.ts` against a warning control, so
 * neither can start or stop returning without a test saying so.
 */
function warnEmailTemplateLocaleFloor(data: ObjectStackDefinition): void {
  const supported = data.i18n?.supportedLocales;
  if (!Array.isArray(supported) || supported.length === 0) return;
  const templates = data.emailTemplates;
  if (!Array.isArray(templates) || templates.length === 0) return;

  const supportedSet = new Set(supported.map((l) => String(l)));

  /** name → the locale tags that bundle carries, in authored order. */
  const bundles = new Map<string, string[]>();
  for (const tpl of templates) {
    const name = typeof tpl?.name === 'string' ? tpl.name : '';
    if (!name) continue;
    const locale = typeof tpl?.locale === 'string' ? tpl.locale : EMAIL_TEMPLATE_FLOOR_LOCALE;
    const tags = bundles.get(name);
    if (tags) tags.push(locale);
    else bundles.set(name, [locale]);
  }

  for (const [name, tags] of bundles) {
    if (tags.includes(EMAIL_TEMPLATE_FLOOR_LOCALE)) continue;
    const declared = tags.filter((t) => supportedSet.has(t));
    if (declared.length === 0) continue;

    const key = `${name} ${tags.join(',')}`;
    if (warnedEmailTemplateFloors.has(key)) continue;
    warnedEmailTemplateFloors.add(key);
    console.warn(
      `defineStack: emailTemplates '${name}' carries rows for ${declared.map((t) => `'${t}'`).join(', ')} ` +
      `but none tagged '${EMAIL_TEMPLATE_FLOOR_LOCALE}', so this bundle has no fallback floor that ` +
      `holds for every send naming a locale. With the built-in template loader such a send folds its ` +
      `locale against these rows (exact, case-insensitive, base language, variant expansion), then ` +
      `tries the stack's declared fallback locale (i18n.fallbackLocale, else defaultLocale) folded ` +
      `the same way; a replacement TemplateLoader matches exactly and retries only ` +
      `'${EMAIL_TEMPLATE_FLOOR_LOCALE}'. When no rung lands on a row the send raises ` +
      `TEMPLATE_NOT_FOUND, which is permanent (dead-letter, no retry). A send naming NO locale does ` +
      `not fail: it drops to this bundle's lowest tag and renders that silently, so one gap is loud ` +
      `for some recipients and invisible for others. '${EMAIL_TEMPLATE_FLOOR_LOCALE}' is the one rung ` +
      `every loader retries: tag the English row '${EMAIL_TEMPLATE_FLOOR_LOCALE}' and keep the other ` +
      `tags beside it.`,
    );
  }
}

/**
 * [ADR-0087 D3 · #22256] The producer's one INTERNAL parameter: the
 * global-registry symbol under which a `defineStack` call's `options` asks for
 * the stack AS AUTHORED — map→array normalised and its bound actions merged,
 * as every non-strict call is, but with the load-time ADR-0087 D2 conversion
 * pass skipped. Honoured only together with `strict: false`.
 *
 * ## Who asks, and why the producer has to be the one that answers
 *
 * `os migrate meta` replays the conversions itself, as chain steps, against
 * the source the author wrote — that is how each rewrite is listed in
 * `applied` and traced back to a literal `--write` can edit. A conversion the
 * load already applied is invisible to it. On a one-package project the CLI
 * starts the chain from the argument the stack's `defineStack` call was given.
 * A composed project has no such argument to start from: `composeStacks`
 * assembles each `packages[i].manifest` body from the stack its input's
 * producer RETURNED, and that assembly is composition's rule, which lives here
 * and nowhere else. So the CLI's authored-source load (and only it) hands
 * `composeStacks` inputs produced again with this key: the composition then
 * runs its own rule over what the author wrote, and nothing outside this
 * package copies it.
 *
 * ## Why a symbol, and why it is not an option
 *
 * It is not authoring surface. An author never needs a stack whose old
 * spellings were left in place — the load converts them so the author does not
 * have to — and a declared `DefineStackOptions` key would advertise one. So it
 * is neither declared on {@link DefineStackOptions} nor exported: the key
 * crosses from the CLI to this producer the way the provenance mark crosses
 * back (`stack-provenance.ts`), by its `Symbol.for` name, which two copies of
 * this package resolve alike.
 *
 * ## What it cannot do
 *
 * - **Relax a strict call.** A strict call ignores it, so it can never let a
 *   spelling the conversion pass would have repaired reach the strict parse,
 *   and never skips a refusal: `strict: false` is what skips the judgement,
 *   exactly as before.
 * - **Hide what it skipped.** Nothing is converted, so the stack's conversion
 *   record is its input's, and no `converted at load` notice is printed for a
 *   conversion that did not happen.
 * - **Mint a stack a non-strict call could not already mint.** The output is
 *   marked, as every non-strict output is, and judged by nothing, as every
 *   non-strict output is. What differs is only that an old spelling is left
 *   where the author wrote it, which a door that reports conversions finds
 *   with its own pass over what it loads (`stackConversionsOf`'s caveat).
 */
const AUTHORED_INPUT_OPTION: symbol = Symbol.for('objectstack.stack.authoredInput');

/** Does this non-strict call ask for its input as authored ({@link AUTHORED_INPUT_OPTION})? */
function asksForAuthoredInput(options: DefineStackOptions | undefined): boolean {
  if (options === null || typeof options !== 'object') return false;
  return (options as Record<symbol, unknown>)[AUTHORED_INPUT_OPTION] === true;
}

export function defineStack(
  config: ObjectStackDefinitionInput,
  options?: DefineStackOptions,
): ObjectStackDefinition {
  // Every ADR-0087 D2 conversion this call applies is RECORDED, beside the
  // provenance mark on the stack it returns (`stackConversionsOf`,
  // `stack-provenance.ts`): the stack leaves here already canonical, so a door
  // that reports conversions — the `--json` `conversions` field,
  // `os validate --strict` — can learn what was converted only from this
  // producer. The record starts from the input's own record, so a built stack
  // handed straight back here keeps what its first build applied (the pass
  // finds nothing left to convert on it); it is not subject to the stderr
  // warn-once.
  //
  // A call that REFUSES returns no stack, so the record rides on the refusal
  // instead: every ADR-0112 refusal thrown below — the schema parse, the six
  // cross-field refusals, and the bound-action merge's shape refusal that ends
  // BOTH modes — carries the conversions applied so far, and
  // `stackConversionsOf(error)` reads them off the caught error. The same
  // array, as it stands at the throw: never a second conversion pass.
  const appliedConversions: ConversionNotice[] = [...stackConversionsOf(config)];
  try {
    return buildDefinedStack(config, options, appliedConversions);
  } catch (error) {
    throw withRefusalConversions(error, () => appliedConversions);
  }
}

/**
 * [ADR-0087 · ADR-0112] The one rule for which throw carries a producer's
 * conversion record, applied in each producer's `catch` before it rethrows: a
 * member of the {@link StackRefusalError} family — the producers' own answer
 * to authored input — is stamped with the record
 * (`markRefusalConversions`, `stack-provenance.ts`); anything else is returned
 * untouched. Either way it is the SAME object, rethrown, so its `code`,
 * `status`, `issues`, message and stack are exactly what the throw site built.
 * A non-refusal throw is not the producer's answer (a bare zod error from an
 * options parse, an internal invariant), so it is not given a record that
 * would read as one.
 *
 * `conversions` is lazy so a producer computes its record only when there is
 * a refusal to carry it.
 */
function withRefusalConversions(error: unknown, conversions: () => readonly ConversionNotice[]): unknown {
  if (error instanceof StackRefusalError) markRefusalConversions(error, conversions());
  return error;
}

/**
 * The body of {@link defineStack}. `appliedConversions` is the caller's
 * record, pushed to as the conversion pass runs, so the caller holds what was
 * applied so far whichever line below throws.
 */
function buildDefinedStack(
  config: ObjectStackDefinitionInput,
  options: DefineStackOptions | undefined,
  appliedConversions: ConversionNotice[],
): ObjectStackDefinition {
  // Default to strict=true for safety (validate by default)
  const strict = options?.strict !== false;

  // Normalize map-formatted collections to arrays (key → name injection), and
  // surface every ADR-0087 D2 conversion the pass had to apply. Unlike the alias
  // warning below this runs in BOTH modes: a conversion happens whether or not
  // we go on to parse, so `strict: false` does not make the old shape any less
  // retiring. Each notice is pushed to the caller's record (see
  // {@link defineStack}) as well as printed, warn-once, on stderr. The one
  // exception is a non-strict call carrying {@link AUTHORED_INPUT_OPTION}: the
  // migration chain's own load, which replays the conversions itself.
  const normalized = normalizeStackInput(config as Record<string, unknown>, {
    convert: strict || !asksForAuthoredInput(options),
    onConversionNotice: (notice) => {
      appliedConversions.push(notice);
      warnConversionNotice(notice);
    },
  });

  // Pre-parse: the parse below is what strips an undeclared key, so this is the
  // last point at which the author's own spelling still exists to report (#3786).
  warnUnknownAuthoringKeys(normalized);

  if (!strict) {
    // Non-strict mode: skip validation (advanced use cases only). The output is
    // still this producer's, so it carries the provenance mark — `strict: false`
    // is an explicit authoring choice made INSIDE the producer, which is what
    // the doors check for (`stack-provenance.ts`).
    return markStackProvenance(
      mergeActionsIntoObjects(normalized as ObjectStackDefinition),
      'defineStack',
      appliedConversions,
    );
  }


  // Strict mode (default): parse with custom error map, then cross-reference validate
  const result = ObjectStackDefinitionSchema.safeParse(normalized, {
    error: objectStackErrorMap,
  });

  if (!result.success) {
    // [ADR-0112 · #15963] The message is byte-for-byte what the bare `Error`
    // carried; the zod issues ride `issues` structurally. See
    // {@link StackSchemaInvalidError} for why this arm is its own code.
    throw new StackSchemaInvalidError(
      formatZodError(result.error, 'defineStack validation failed'),
      result.error.issues,
    );
  }

  // REJECT any unknown capability token (framework#3265/#3308): no runtime
  // provides it, so it would otherwise be silently ignored (declared ≠
  // enforced, Prime Directive #12). No alias canonicalization — the deprecated
  // `aiStudio`/`aiSeat` spellings were removed in #3308.
  const data = result.data;

  const capErrors = validateKnownCapabilities(data);
  if (capErrors.length > 0) {
    const header = `defineStack capability validation failed (${capErrors.length} issue${capErrors.length === 1 ? '' : 's'}):`;
    const lines = capErrors.map((e) => `  ✗ ${e}`);
    throw new StackCapabilityUnknownError(`${header}\n\n${lines.join('\n')}`, capErrors);
  }

  const flowClaims: ArtifactFlowClaim[] = [];
  const crossRefErrors = validateCrossReferences(
    data,
    options?.artifactObjects && options.artifactObjects.length > 0
      ? new Set(options.artifactObjects)
      : undefined,
    options?.artifactFlows && options.artifactFlows.length > 0
      ? new Set(options.artifactFlows)
      : undefined,
    flowClaims,
  );
  if (crossRefErrors.length > 0) {
    const header = `defineStack cross-reference validation failed (${crossRefErrors.length} issue${crossRefErrors.length === 1 ? '' : 's'}):`;
    const lines = crossRefErrors.map((e) => `  ✗ ${e}`);
    // [ADR-0112 · #14552] The message is byte-for-byte what the bare `Error`
    // carried — this adds the envelope's fields, it does not reword a
    // sentence. See {@link StackCrossReferenceError}.
    throw new StackCrossReferenceError(`${header}\n\n${lines.join('\n')}`, crossRefErrors);
  }

  const nsErrors = validateNamespacePrefix(data);
  if (nsErrors.length > 0) {
    const header = `defineStack namespace-prefix validation failed (${nsErrors.length} issue${nsErrors.length === 1 ? '' : 's'}):`;
    const lines = nsErrors.map((e) => `  ✗ ${e}`);
    const hint = `\n\nEvery object.name must be \`\${manifest.namespace}_\${shortName}\`. This is the only supported writing style — the platform does not provide ns() helpers or factory wrappers.`;
    // The hint stays in the message only; `issues` is the per-object findings.
    throw new StackNamespacePrefixInvalidError(`${header}\n\n${lines.join('\n')}${hint}`, nsErrors);
  }

  const appErrors = validateSingleApp(data);
  if (appErrors.length > 0) {
    const header = `defineStack single-app validation failed (${appErrors.length} issue${appErrors.length === 1 ? '' : 's'}):`;
    const lines = appErrors.map((e) => `  ✗ ${e}`);
    throw new StackSingleAppViolationError(`${header}\n\n${lines.join('\n')}`, appErrors);
  }

  const hierErrors = validateHierarchyScopeCapability(data);
  if (hierErrors.length > 0) {
    const header = `defineStack hierarchy-scope capability validation failed (${hierErrors.length} issue${hierErrors.length === 1 ? '' : 's'}):`;
    const lines = hierErrors.map((e) => `  ✗ ${e}`);
    throw new StackHierarchyScopeCapabilityRequiredError(`${header}\n\n${lines.join('\n')}`, hierErrors);
  }

  const triggerErrors = validateTriggerCapability(data);
  if (triggerErrors.length > 0) {
    const header = `defineStack trigger capability validation failed (${triggerErrors.length} issue${triggerErrors.length === 1 ? '' : 's'}):`;
    const lines = triggerErrors.map((e) => `  ✗ ${e}`);
    throw new StackTriggerCapabilityRequiredError(`${header}\n\n${lines.join('\n')}`, triggerErrors);
  }

  const webhookErrors = validateWebhookCapability(data);
  if (webhookErrors.length > 0) {
    const header = `defineStack webhook capability validation failed (${webhookErrors.length} issue${webhookErrors.length === 1 ? '' : 's'}):`;
    const lines = webhookErrors.map((e) => `  ✗ ${e}`);
    throw new StackWebhookCapabilityRequiredError(`${header}\n\n${lines.join('\n')}`, webhookErrors);
  }

  const unmanagedErrors = validateUnmanagedInstallMode(data);
  if (unmanagedErrors.length > 0) {
    const header = `defineStack unmanaged install-mode validation failed (${unmanagedErrors.length} issue${unmanagedErrors.length === 1 ? '' : 's'}):`;
    const lines = unmanagedErrors.map((e) => `  ✗ ${e}`);
    const hint = '\n\n`manifest.installModes` permits \'unmanaged\', which copies every item of this package into the '
      + 'environment ledger or copies nothing (ADR-0131 D6). Remove \'unmanaged\' from `manifest.installModes`, or move '
      + 'what cannot be copied out of this package.';
    throw new StackUnmanagedInstallUncopyableError(`${header}\n\n${lines.join('\n')}${hint}`, unmanagedErrors);
  }

  // Post-parse and advisory only: this call has no effect on what is
  // returned. `locale` carries a default, so this has to run AFTER the parse
  // or a row that omits the key would read as a missing floor it actually
  // has. [objectstack#17852] The stack is NOT "returned unchanged" — that
  // was true of neither half of this function: the parse itself can drop an
  // authored key a record's key schema never gets to see (the defect this
  // card fixes), and `mergeActionsIntoObjects` below rewrites `actions`
  // and/or `objects` (bound-action merge, `order` sort) before the result
  // reaches the caller.
  warnEmailTemplateLocaleFloor(data);

  // [#20367 ruling B] The mark the author-time doors and `composeStacks` check:
  // this value went through the judgement above. Non-enumerable, so it reaches
  // neither the schema nor the compiled artifact (`stack-provenance.ts`). The
  // conversion record rides beside it, stamped in the same act.
  return recordArtifactFlowClaims(
    markStackProvenance(mergeActionsIntoObjects(data), 'defineStack', appliedConversions),
    flowClaims,
  );
}

/**
 * [#20367 ruling B] The published halves of stack provenance — see
 * `stack-provenance.ts`. `os validate` / `os build` read the mark off the
 * config's default export and refuse an unmarked one
 * (`STACK_PROVENANCE_MISSING`), and fold the conversion record into their
 * `conversions` field and the `--strict` gate.
 */
export { hasStackProvenance, stackConversionsOf };


// ─── composeStacks ──────────────────────────────────────────────────

/**
 * Strategy for resolving conflicts when multiple stacks define the same named item.
 *
 * - `'error'`    — Throw an error when a duplicate name is detected (default).
 * - `'override'` — Last stack wins; later definitions replace earlier ones.
 * - `'merge'`    — Shallow-merge `fields` of same-name objects (later fields
 *                  win, earlier fields are kept). Every OTHER object-level
 *                  collection (`actions`, `indexes`, `listViews`,
 *                  `validations`, …) and every fixed-shape config object
 *                  (`enable`, `access`, `protection`, `tenancy`, …) is not
 *                  merged: when both objects declare one with different values
 *                  the composition is REFUSED, naming the object, the key and
 *                  both stacks (#14848; config objects #16075) — declare it in
 *                  one stack only, or use `'override'`. Identical declarations
 *                  pass through; a scalar the later object declares replaces
 *                  the earlier one.
 */
export const ConflictStrategySchema = lazySchema(() => z.enum(['error', 'override', 'merge']));
export type ConflictStrategy = z.input<typeof ConflictStrategySchema>;

/**
 * Options for {@link composeStacks}.
 */
export const ComposeStacksOptionsSchema = lazySchema(() => z.object({
  /**
   * How to handle same-name objects across stacks.
   * @default 'error'
   */
  objectConflict: ConflictStrategySchema.default('error'),

  /**
   * Which manifest to keep when multiple stacks provide one.
   *
   * - `'first'`    — Use the first manifest found.
   * - `'last'`     — Use the last manifest found (default).
   * - A number     — Use the manifest from the stack at the given index.
   * - `'preserve'` — Keep them ALL (ADR-0130 follow-up row 3). See below.
   *
   * ## `'preserve'` — the pick becomes additive instead of lossy
   *
   * The three values above are a deliberate **pick-one**: composition keeps one
   * manifest and the other N−1 package identities are gone from the output.
   * That is correct for the case they were written for (several stacks
   * assembled into ONE published package) and wrong for the case ADR-0130
   * introduces — a release artifact that **carries** N packages, each of which
   * keeps its own identity so a product can be split into modules without
   * renaming a single object.
   *
   * `'preserve'` composes the artifact's package list instead of discarding it:
   * every input stack contributes its packages to `packages` (ADR-0130 D4), in
   * stack order, each element the `{ manifest: … }` wrapper object
   * {@link ArtifactPackageSchema} declares — its body half being that stack
   * ASSEMBLED (manifest fields plus the collections that package owns), which
   * is the payload `ObjectQL.registerApp` iterates. Assembling here is not an
   * implementation detail of preserve: composition is the last moment at which
   * per-package attribution exists at all, since the composed stack flattens
   * every collection to the top level.
   *
   * Which entries a stack contributes is **D4's read-both rule applied to the
   * inputs**, not a second rule invented here:
   *
   * - stack declares `packages` → those entries;
   * - stack declares no `packages` → its singular `manifest` as a
   *   **single-element list**.
   *
   * So a stack that carries both does not contribute its manifest twice, and a
   * plain single-`manifest` stack — every stack written before ADR-0130 — folds
   * in as exactly one package.
   *
   * ⚠️ The singular `manifest` is **retained, not replaced**: it is still
   * selected by the same `'last'` rule as the default, so the artifact keeps an
   * artifact-level identity (ADR-0130 D6 — one artifact, one version) and no
   * consumer reading `composed.manifest` sees a key disappear.
   *
   * ## The COLLECTIONS are carried once, under their package (#14512)
   *
   * A multi-package `'preserve'` output does **not** also carry the flattened
   * collections: `objects`, `views`, `flows`, `permissions` and every other
   * package-owned key live in `packages[i].manifest` and nowhere else, so one
   * definition is serialized once. Until 2026-09-22 the output was both halves,
   * every definition twice — which doubled the payload the marketplace
   * transfers and startup parses, and left two copies of one definition that
   * nothing reconciled: they are measured to differ in content whenever the
   * composition merges or overrides an object, and a consumer saw whichever
   * copy its own reader happened to read. The maintainer ruled the copy out
   * (ADR-0130 D4's 2026-09-22 addendum, batch #23), READERS FIRST: every reader
   * resolves `packages[]` before this emitter stopped feeding the flat copy.
   *
   * THREE conditions hold it to a copy-removal, and a composition failing any
   * one of them keeps today's additive shape — which every reader still reads:
   *
   * 1. at least TWO package entries (ADR-0130 D7 — a single-package artifact is
   *    byte-identical to before);
   * 2. every input's collections attributed to a body
   *    ({@link packagesCarryEveryInputCollection}) — an input with no
   *    `manifest` has no package that could own its collections;
   * 3. the bodies REPRODUCE the flattened collections, item for item
   *    ({@link packagesReproduceComposedCollections}) — composition sometimes
   *    RECONCILES (`objectConflict: 'merge'` / `'override'` fold two packages'
   *    same-named objects into one; a standalone action binds onto a sibling
   *    package's object), and the reconciled copy lives in the flattened half
   *    alone. Condition 2 cannot see that: it reads the INPUT stacks, and what
   *    the strip deletes is the COMPOSED result.
   *
   * @default 'last'
   */
  manifest: z.union([z.enum(['first', 'last', 'preserve']), z.number().int().min(0)]).default('last'),

  /**
   * Optional namespace prefix (reserved for Phase 2 — Marketplace isolation).
   * When set, object names from this composition are prefixed for isolation.
   */
  namespace: z.string().optional(),
}));

export type ComposeStacksOptions = z.input<typeof ComposeStacksOptionsSchema>;
/** Post-parse shape of {@link ComposeStacksOptions} — defaults applied, transforms run (ADR-0122). */
export type ComposeStacksOptionsParsed = z.infer<typeof ComposeStacksOptionsSchema>;


/**
 * Name a stack the way its author would recognise it (#5005).
 *
 * A composition error is only actionable if it says WHICH stacks disagree, and
 * at compose time the only identity a stack carries is its manifest. Falls back
 * to the positional index for the manifest-less stacks that composition also
 * accepts.
 * @internal
 */
function stackLabel(stack: ObjectStackDefinition, index: number): string {
  const id = stack.manifest?.id ?? stack.manifest?.name;
  return id ? `'${id}' (stack #${index})` : `stack #${index}`;
}

/**
 * Compose a single-valued (non-array) top-level key across stacks (#5005,
 * #5051).
 *
 * Same value everywhere ⇒ that value. Any disagreement ⇒ throw, naming the key,
 * both source stacks and the two ways out. NOT last-wins: silently preferring
 * the later stack is a security downgrade — it is precisely how an earlier
 * stack's `enforceProjectMembership` 403 gate or a tighter rate-limit budget
 * would be switched off by an add-on package, and (since #5051) how an `i18n`
 * locale set would be swapped out from under the `translations` bundles written
 * against it. NOT a deep merge either: that invents a third value neither
 * author wrote.
 * @internal
 */
function composeSingleValue(
  stacks: ObjectStackDefinition[],
  key: string,
): { declared: boolean; value: unknown } {
  let holder = -1;

  for (let i = 0; i < stacks.length; i++) {
    const value = (stacks[i] as Record<string, unknown>)[key];
    if (value === undefined) continue;
    if (holder === -1) {
      holder = i;
      continue;
    }
    const held = (stacks[holder] as Record<string, unknown>)[key];
    if (deepEqualAuthored(held, value)) continue;

    const finding =
      `top-level key '${key}' is declared with different values by ` +
      `${stackLabel(stacks[holder], holder)} and ${stackLabel(stacks[i], i)}.`;
    throw new StackComposeKeyConflictError(
      `composeStacks conflict: ${finding}\n` +
        `composeStacks does not pick a winner for single-valued top-level configuration: ` +
        `overriding would silently drop whichever declaration lost — a stricter setting ` +
        `(an 'api.enforceProjectMembership' 403 gate, a 'server.security.rateLimit' budget), ` +
        `or an 'i18n' locale set the losing stack's own 'translations' bundles are written ` +
        `against — and deep-merging would produce a value neither stack declared.\n` +
        `Fix: make the two '${key}' declarations identical, or remove it from every stack ` +
        `except the one that should own it.`,
      [finding],
    );
  }

  return holder === -1
    ? { declared: false, value: undefined }
    : { declared: true, value: (stacks[holder] as Record<string, unknown>)[key] };
}

/**
 * Compose the `functions` handler collection across stacks (#5005).
 *
 * `functions` is a named collection, not an opaque config blob: composing CRM +
 * Todo must yield BOTH packages' handlers, or every declarative hook, action
 * and script node that resolves a handler by name breaks at boot. So it merges
 * by name — and a name declared twice throws rather than picking a winner,
 * matching `objectConflict: 'error'`.
 *
 * The two authored shapes (map and array) are merged in kind. They are NOT
 * converted into one another: an array entry carries a `packageId` that the map
 * entry has no place for, so a conversion would drop provenance. Mixing the two
 * shapes across composed stacks therefore throws with that instruction.
 * @internal
 */
function composeFunctions(
  stacks: ObjectStackDefinition[],
): { declared: boolean; value: unknown } {
  type ArrayEntry = { name: string };
  const declaring: { index: number; value: unknown }[] = [];

  for (let i = 0; i < stacks.length; i++) {
    const value = (stacks[i] as Record<string, unknown>).functions;
    if (value !== undefined) declaring.push({ index: i, value });
  }
  if (declaring.length === 0) return { declared: false, value: undefined };
  if (declaring.length === 1) return { declared: true, value: declaring[0].value };

  const arrayForm = declaring.filter((d) => Array.isArray(d.value));
  if (arrayForm.length !== 0 && arrayForm.length !== declaring.length) {
    const mapSide = declaring.find((d) => !Array.isArray(d.value))!;
    const finding =
      `top-level key 'functions' is declared in the map form by ` +
      `${stackLabel(stacks[mapSide.index], mapSide.index)} and in the array form by ` +
      `${stackLabel(stacks[arrayForm[0].index], arrayForm[0].index)}.`;
    throw new StackComposeFunctionsShapeConflictError(
      `composeStacks conflict: ${finding}\n` +
        `The two shapes cannot be merged without losing information (an array entry carries ` +
        `'packageId', the map entry does not).\n` +
        `Fix: author 'functions' in the same shape in both stacks — the map form ` +
        `({ my_handler: fn }) is preferred.`,
      [finding],
    );
  }

  const seen = new Map<string, number>();
  const claim = (name: string, index: number): void => {
    const first = seen.get(name);
    if (first !== undefined) {
      const finding =
        `function '${name}' is defined by both ` +
        `${stackLabel(stacks[first], first)} and ${stackLabel(stacks[index], index)}.`;
      throw new StackComposeFunctionConflictError(
        `composeStacks conflict: ${finding}\n` +
          `Handlers are resolved by name at boot, so one would silently shadow the other.\n` +
          `Fix: rename one of them (prefix it with its package, e.g. 'crm_${name}'), or ` +
          `declare it in exactly one stack.`,
        [finding],
      );
    }
    seen.set(name, index);
  };

  if (arrayForm.length === declaring.length) {
    const merged: ArrayEntry[] = [];
    for (const { index, value } of declaring) {
      for (const entry of value as ArrayEntry[]) {
        claim(entry.name, index);
        merged.push(entry);
      }
    }
    return { declared: true, value: merged };
  }

  const merged: Record<string, unknown> = {};
  for (const { index, value } of declaring) {
    for (const [name, handler] of Object.entries(value as Record<string, unknown>)) {
      claim(name, index);
      merged[name] = handler;
    }
  }
  return { declared: true, value: merged };
}

/**
 * The shared half of every non-array collection refusal in {@link composeStacks}
 * (#18239 for `objects`, #19784 for the concatenated collections): what the
 * value IS, in words the message can name, and the zod issue the strict parse
 * would raise for it, re-rooted at the key's path — so a refusal raised here
 * carries the same `issues` shape {@link StackSchemaInvalidError} carries from
 * `defineStack`'s own door.
 * @internal
 */
function describeNonArrayCollection(
  key: string,
  declared: unknown,
): { kind: string; issues: z.core.$ZodIssue[] } {
  const parsed = z.array(z.unknown()).safeParse(declared);
  const issues = parsed.success
    ? []
    : parsed.error.issues.map((issue) => ({ ...issue, path: [key, ...issue.path] }));
  const kind =
    declared === null
      ? 'null'
      : typeof declared !== 'object'
        ? `a ${typeof declared}`
        : Object.getPrototypeOf(declared) === Object.prototype
          ? 'an object'
          : `a ${(declared as object).constructor?.name ?? 'non-plain'} object`;
  return { kind, issues: issues as z.core.$ZodIssue[] };
}

const warnedMalformedCollectionEntries = new Set<string>();

/**
 * Report a collection whose array carries an entry that is not an object
 * (#18239 — `mergeObjects`).
 *
 * The collection itself is well-formed, so composition goes on; the entry
 * carries nothing to merge and is skipped, and skipping it silently would be
 * the #5005 defect in miniature. Deduplicated per key. A non-array VALUE is no
 * longer this helper's case at all: {@link composeStacks} refuses it (steps 2
 * and 3), because skipping a whole collection composes an artifact that
 * silently lacks a stack's content (#19784).
 * @internal
 */
function warnMalformedCollectionEntry(key: string): void {
  if (warnedMalformedCollectionEntries.has(key)) return;
  warnedMalformedCollectionEntries.add(key);
  console.warn(
    `composeStacks: top-level key '${key}' is a collection but at least one stack carries an ` +
      `entry in it that is not an object — that entry cannot be composed and was skipped. Author ` +
      `every entry as an object, or run the stack through strict \`defineStack\` to have the ` +
      `shape rejected where it is written.`,
  );
}

const warnedUncomposedStackKeys = new Set<string>();

/**
 * Report a top-level key that reached composition with no declared rule (#5005).
 *
 * The invariant this restores: composition is never silent about a key it did
 * not know what to do with. It still composes the key by the default rule
 * (arrays concatenate, everything else follows the single-value rule) so
 * nothing is lost — but the NEXT top-level key someone adds without teaching
 * `composeStacks` about it announces itself here, instead of being discovered
 * by accident during unrelated work the way `server:` was.
 *
 * Warn-once per key, like the other authoring-time notices in this module.
 * @internal
 */
function warnUncomposedStackKey(key: string, rule: ComposeDisposition): void {
  if (warnedUncomposedStackKeys.has(key)) return;
  warnedUncomposedStackKeys.add(key);
  console.warn(
    `composeStacks: top-level key '${key}' has no declared composition rule — composed with ` +
      `the default (${rule === 'concat' ? 'arrays are concatenated' : 'single value; conflicting declarations throw'}). ` +
      `Declare what composing it means in COMPOSE_KEY_DISPOSITIONS (packages/spec/src/stack.zod.ts) ` +
      `in the same change that declares the key.`,
  );
}

/** As much of a zod node's `def` as the collection walk below reads. */
interface CollectionWalkDef {
  type?: string;
  innerType?: unknown;
  in?: unknown;
  out?: unknown;
  options?: unknown[];
  getter?: () => unknown;
}

/**
 * The `def` of a zod node, or `undefined` when the value is not one.
 *
 * `typeof === 'function'` is load-bearing, not padding: the canonical schemas
 * on this shape arrive as the `lazySchema` proxy, which is CALLABLE, and an
 * object-only guard answers "not a schema" for every one of them.
 * @internal
 */
function collectionWalkDef(schema: unknown): CollectionWalkDef | undefined {
  if (schema === null || (typeof schema !== 'object' && typeof schema !== 'function')) return undefined;
  return (schema as { _zod?: { def?: CollectionWalkDef } })._zod?.def;
}

/**
 * The wrappers the collection walk peels, as a set — the same labels the
 * `switch` in {@link declaresCollection} peels by `case`. Used to look THROUGH
 * a pipe's IN side before asking whether it is a transform stage: a transform
 * one level down is still a transform — and by {@link declaresConfigObject},
 * which peels exactly these and no others, so the two questions asked of one
 * key never disagree about what counts as a wrapper.
 * @internal
 */
const COLLECTION_WALK_WRAPPERS: ReadonlySet<string> = new Set([
  'optional',
  'nullable',
  'default',
  'prefault',
  'readonly',
  'nonoptional',
  'catch',
]);

/**
 * The side of a `pipe` node an author actually writes.
 *
 * Two constructs compile to the same `pipe` node and their authorable sides
 * are OPPOSITE: `a.transform(fn)` keeps the accepted input shape in `in` and
 * puts the transform stage in `out`, while `z.preprocess(fn, schema)` puts the
 * TRANSFORM in `in` and the real, validated schema in `out`. Reading `in`
 * unconditionally therefore hands back a transform node for every preprocess
 * node, and a transform declares no shape at all — so {@link declaresCollection}
 * falls through to `false` and a preprocess-wrapped collection key silently
 * leaves the refusal set {@link objectUnmergeableKeys} derives. Silently is the
 * whole point: that derivation exists precisely so a collection key added to
 * the object shape tomorrow cannot fall back to the wholesale replacement
 * `objectConflict: 'merge'` refuses. {@link declaresConfigObject} reads a pipe
 * through this same side, for the same reason.
 *
 * ⛔ Deliberately NOT `in || out`. For a genuine `a.transform(fn).pipe(b)` the
 * author writes `a`; taking either side would pull a key whose AUTHORED value
 * is a scalar into a refusal set that then names it a collection — a refusal
 * nobody earned, printed in the vocabulary of entries that were never written.
 * Reading OUT only when IN is a transform stage is the rule four sibling
 * walkers already run — `pipeAuthorableSide` in `scripts/lib/zod-graph.ts`,
 * `kernel/metadata-authoring-lint.ts`,
 * `system/metadata-form-zod-reconciliation.test.ts` and `packages/lint`'s
 * `validate-predicate-path-refs.ts` — so this is one rule with a fifth site,
 * not a fifth dialect.
 * @internal
 */
function pipeAuthorableSide(def: CollectionWalkDef): unknown {
  let node = def.in;
  for (let hops = 0; hops < 8; hops++) {
    const inner = collectionWalkDef(node);
    if (!inner?.type) break;
    if (inner.type === 'transform') return def.out;
    if (COLLECTION_WALK_WRAPPERS.has(inner.type)) {
      node = inner.innerType;
      continue;
    }
    if (inner.type === 'lazy') {
      node = inner.getter?.();
      continue;
    }
    break;
  }
  return def.in;
}

/**
 * Does this schema declare a COLLECTION — an array, or a record of named
 * members — once the optional/default/nullable wrappers are stripped, reading
 * through a `lazy` or a `pipe` and into a union's members? (#14848)
 *
 * The first structural question {@link objectUnmergeableKeys} asks of each
 * key on the object shape. A union counts when ANY member is a collection
 * (`requiredPermissions` admits a `string[]` beside its object form): the
 * author may have written the array form, and the loss the caller refuses is
 * the same. A fixed-shape config object (`enable`, `access`, `protection`, …)
 * is not a collection — its members are declared keys, not authored entries —
 * and is the second question's ({@link declaresConfigObject}), refused under
 * its own name.
 *
 * A `pipe` is read on the side the AUTHOR writes, never on `in` alone — see
 * {@link pipeAuthorableSide} for the two opposite conventions that compile to
 * that one node.
 * @internal
 */
function declaresCollection(schema: unknown, depth = 0): boolean {
  if (depth > 8) return false;
  const def = collectionWalkDef(schema);
  if (!def?.type) return false;
  switch (def.type) {
    case 'array':
    case 'record':
      return true;
    case 'optional':
    case 'nullable':
    case 'default':
    case 'prefault':
    case 'readonly':
    case 'nonoptional':
    case 'catch':
      return declaresCollection(def.innerType, depth + 1);
    case 'lazy':
      return declaresCollection(def.getter?.(), depth + 1);
    case 'pipe':
      return declaresCollection(pipeAuthorableSide(def), depth + 1);
    case 'union':
      return (def.options ?? []).some((option) => declaresCollection(option, depth + 1));
    default:
      return false;
  }
}

/**
 * Does this schema declare a FIXED-SHAPE CONFIG OBJECT — a `z.object` whose
 * members are keys the schema names — once the wrappers in
 * {@link COLLECTION_WALK_WRAPPERS} are stripped, reading through a `lazy` or
 * a `pipe`'s authorable side? (#16075)
 *
 * The second structural question {@link objectUnmergeableKeys} asks, of a key
 * that is not a collection. `enable`, `access`, `protection`, `tenancy`, … are
 * ONE declaration each, and the `'merge'` spread replaces the earlier object's
 * declaration wholesale exactly as it replaces a collection's entries: every
 * member the earlier stack set is gone, and an add-on package that declares
 * its own `access` or `protection` switches off the core package's posture in
 * silence — the downgrade {@link composeSingleValue} already refuses for the
 * top-level `api` / `server`. Ruling 5563452716 on #16075 (option 1): refused,
 * in #14848's shape, with #14848's identical-passes reading.
 *
 * ⛔ Deliberately NOT read into a union, where {@link declaresCollection} is.
 * A union admitting an object beside a non-object form (`systemFields`'s
 * `false` or options object, `titleFormat`'s template string or object) is
 * not a FIXED shape, and the ruling names the fixed-shape keys only — such a
 * key stays on the scalar rule. Moving it is a decision about that key, not a
 * derivation this walk may make for it.
 * @internal
 */
function declaresConfigObject(schema: unknown, depth = 0): boolean {
  if (depth > 8) return false;
  const def = collectionWalkDef(schema);
  if (!def?.type) return false;
  if (COLLECTION_WALK_WRAPPERS.has(def.type)) return declaresConfigObject(def.innerType, depth + 1);
  switch (def.type) {
    case 'object':
      return true;
    case 'lazy':
      return declaresConfigObject(def.getter?.(), depth + 1);
    case 'pipe':
      return declaresConfigObject(pipeAuthorableSide(def), depth + 1);
    default:
      return false;
  }
}

/**
 * What a key {@link objectUnmergeableKeys} refuses IS: the word its refusal
 * lists it under, and the noun for what a wholesale replacement drops (a
 * collection's entries, a config object's members).
 * @internal
 */
type UnmergeableKind = 'collection' | 'config object';

let objectUnmergeableKeysCache: ReadonlyMap<string, UnmergeableKind> | undefined;

/**
 * The object-level keys `objectConflict: 'merge'` refuses to combine, each
 * mapped to its kind — the collections (#14848) and the fixed-shape config
 * objects (#16075) — in the object shape's declaration order.
 *
 * DERIVED from `ObjectSchema`'s shape at first use, never transcribed: every
 * key whose declared type is a collection ({@link declaresCollection}) or,
 * failing that, a fixed-shape config object ({@link declaresConfigObject}) is
 * a member, except `fields` — the one collection `'merge'` merges, by its
 * documented shallow spread. A hand-written list would be a second statement
 * of the object shape (the drift ADR-0116 exists about) and would fail in the
 * silent direction: a collection or config-object key added to the object
 * schema tomorrow would fall back to the wholesale replacement this rule
 * exists to refuse. Derived, it joins the refusal set the moment the shape
 * declares it. A key the shape does not declare at all is no member either —
 * the strict parse refuses it on every authored object before composition
 * sees one.
 *
 * Resolved lazily rather than at module init: `ObjectSchema` is a lazy schema
 * whose factory must not run while `stack.zod.ts` is still loading.
 * @internal
 */
function objectUnmergeableKeys(): ReadonlyMap<string, UnmergeableKind> {
  if (objectUnmergeableKeysCache === undefined) {
    const keys = new Map<string, UnmergeableKind>();
    for (const [key, schema] of Object.entries(ObjectSchema.shape)) {
      if (key === 'fields') continue;
      if (declaresCollection(schema)) keys.set(key, 'collection');
      else if (declaresConfigObject(schema)) keys.set(key, 'config object');
    }
    objectUnmergeableKeysCache = keys;
  }
  return objectUnmergeableKeysCache;
}

/**
 * The refused keys of one kind, in shape order — one of the two lists the
 * `'merge'` refusal prints.
 * @internal
 */
function unmergeableKeysOfKind(kind: UnmergeableKind): string[] {
  return [...objectUnmergeableKeys()].filter(([, of]) => of === kind).map(([key]) => key);
}

/**
 * The refused keys `obj` declares — own, non-`undefined`, the reading
 * {@link composeSingleValue} takes of a top-level declaration — each mapped
 * to the declaring stack. Seeds {@link mergeObjects}' per-object ownership on
 * a first sighting and on `'override'`.
 * @internal
 */
function declaredUnmergeableKeys(obj: object, index: number): Map<string, number> {
  const owners = new Map<string, number>();
  const record = obj as Record<string, unknown>;
  for (const key of objectUnmergeableKeys().keys()) {
    if (record[key] !== undefined) owners.set(key, index);
  }
  return owners;
}

/**
 * The `'merge'` refusal (#14848; config objects #16075): the later object
 * declares a collection or a fixed-shape config object the composed object
 * already carries, with a DIFFERENT value. Records the later stack as owner of
 * every such key it is the first to declare, so a third stack disagreeing with
 * it is named against it. Identical declarations pass, the way
 * {@link composeSingleValue} passes identical top-level values. The name is
 * #14848's, kept for both kinds: one raise site, one code.
 * @internal
 */
function refuseUnmergeableCollections(
  stacks: ObjectStackDefinition[],
  existing: object,
  later: object,
  owners: Map<string, number>,
  index: number,
): void {
  const held = existing as Record<string, unknown>;
  const incoming = later as Record<string, unknown>;
  const name = (later as { name: string }).name;
  for (const [key, kind] of objectUnmergeableKeys()) {
    const value = incoming[key];
    if (value === undefined) continue;
    const holder = owners.get(key);
    if (holder === undefined || held[key] === undefined) {
      owners.set(key, index);
      continue;
    }
    if (deepEqualAuthored(held[key], value)) continue;

    const finding =
      `object '${name}' is defined in multiple stacks and its '${key}' ` +
      `is declared with different values by ${stackLabel(stacks[holder], holder)} and ` +
      `${stackLabel(stacks[index], index)}.`;
    const dropped = kind === 'collection' ? 'entry' : 'member';
    const dropVerb = kind === 'collection' ? 'wrote' : 'set';
    throw new StackComposeCollectionConflictError(
      `composeStacks conflict: ${finding}\n` +
        `objectConflict: 'merge' shallow-merges 'fields' only. Any other object-level collection ` +
        `(${unmergeableKeysOfKind('collection').join(', ')}) is not merged, and neither is a ` +
        `fixed-shape config object (${unmergeableKeysOfKind('config object').join(', ')}): the later ` +
        `declaration would replace the earlier one wholesale, silently dropping every ${dropped} ` +
        `${stackLabel(stacks[holder], holder)} ${dropVerb}.\n` +
        `Fix: declare '${key}' on '${name}' in exactly one of the two stacks, make the two ` +
        `declarations identical, or use { objectConflict: 'override' } to hand the whole object ` +
        `to the later stack.`,
      [finding],
    );
  }
}

/**
 * Merge objects from multiple stacks according to the chosen conflict strategy.
 *
 * Under `'merge'` only `fields` is merged — the documented shallow spread,
 * later fields winning, earlier fields kept. Every other object-level
 * COLLECTION (`actions`, `indexes`, `listViews`, `validations`, …) and every
 * fixed-shape CONFIG OBJECT (`enable`, `access`, `protection`, `tenancy`, …)
 * — together {@link objectUnmergeableKeys} — is carried from exactly one
 * stack: a later object that declares one the composed object already
 * carries, with a different value, is refused (#14848; config objects #16075;
 * {@link refuseUnmergeableCollections}) — the refusal `'error'` uses, naming
 * the object, the key and both stacks — instead of the spread replacing the
 * earlier stack's entries or members wholesale and in silence (the top-level
 * key loss #5005 closed, one level down). Identical declarations pass
 * through: two built stacks that each bind one standalone action to the same
 * object carry the same copy of it, and nothing is dropped. A scalar
 * (`label`, `sharingModel`, …) the later object declares still replaces the
 * earlier one — the two rulings narrow collections and config objects only,
 * and that half is stated here so the difference reads as the rule rather
 * than as an oversight. An explicit
 * `undefined` is not a declaration anywhere in this composer, and the spread
 * agrees: it is dropped from the later object before spreading, so it neither
 * counts as a differing value nor erases what the earlier stack declared.
 *
 * Besides the merged list it reports, per composed object name, WHICH input
 * stack's `actions` array the composed object carries (`actionsOwner`, a stack
 * index) — the provenance {@link collectComposedActionKeyCollisions} needs to
 * tell a cross-stack collision from one stack's own declarations. It is
 * recorded here, beside the spread that decides it, rather than re-derived
 * from the strategy elsewhere (a second statement of one rule is the drift
 * ADR-0116 exists about): a first sighting and `'override'` hand the whole
 * object to stack `i`; under `'merge'` the shallow spread hands `actions` to
 * the LATER object only when that object declares the key itself — an absent
 * (or explicitly `undefined`) key leaves the earlier stack's array in place —
 * which is exactly what a defined-value check reads. The owner model stays
 * per-object: a differing `actions` pair is refused before ownership could
 * matter, and an identical pair is one declaration whichever stack it is
 * attributed to.
 * @internal
 */
function mergeObjects(
  stacks: ObjectStackDefinition[],
  strategy: ConflictStrategy,
): { objects: ObjectStackDefinition['objects']; actionsOwner: Map<string, number> } {
  type Obj = NonNullable<ObjectStackDefinition['objects']>[number];
  const map = new Map<string, Obj>();
  const result: Obj[] = [];
  const actionsOwner = new Map<string, number>();
  // Per composed object, the stack that FIRST declared each refused key — the
  // one a `'merge'` refusal names beside the disagreeing later stack.
  const unmergeableOwner = new Map<string, Map<string, number>>();

  for (const [i, stack] of stacks.entries()) {
    // [ADR-0112 · #18239] Shape guard, because composition accepts inputs the
    // strict parse never saw (a hand-built stack, `strict: false`). A non-array
    // `objects` is REFUSED, never skipped: skipping it composes an artifact that
    // silently lacks this stack's objects — a composed artifact is complete or
    // it is refused. `undefined` is the one non-array that is not malformed: the
    // key is simply absent. The code is the strict parse's own
    // (`STACK_SCHEMA_INVALID`) because the defect is the same authored mistake
    // that door refuses; the header names this pass, the split
    // {@link StackCrossReferenceError} makes across its two raise sites.
    const declared: unknown = (stack as { objects?: unknown }).objects;
    if (declared === undefined) continue;
    if (!Array.isArray(declared)) {
      const { kind, issues } = describeNonArrayCollection('objects', declared);
      throw new StackSchemaInvalidError(
        `composeStacks validation failed: ${stackLabel(stack, i)} declares 'objects' as ${kind}, ` +
          `not an array. Its objects cannot be composed, and skipping them would compose an artifact ` +
          `that silently lacks them. Author 'objects' as an array (\`defineStack\` normalizes the map ` +
          `form into one), or run the stack through strict \`defineStack\` to have the shape rejected ` +
          `where it is written.`,
        issues,
      );
    }
    for (const obj of declared as Obj[]) {
      // A non-object ENTRY carries no object to merge — step 3's shape: skip it
      // and say so once, never dereference it into a bare `TypeError`.
      if (!isRecord(obj)) {
        warnMalformedCollectionEntry('objects');
        continue;
      }
      const existing = map.get(obj.name);
      if (!existing) {
        map.set(obj.name, obj);
        result.push(obj);
        actionsOwner.set(obj.name, i);
        unmergeableOwner.set(obj.name, declaredUnmergeableKeys(obj, i));
        continue;
      }

      switch (strategy) {
        case 'error': {
          const finding = `object '${obj.name}' is defined in multiple stacks.`;
          throw new StackComposeObjectConflictError(
            `composeStacks conflict: ${finding} ` +
              `Use { objectConflict: 'override' } or { objectConflict: 'merge' } to resolve.`,
            [finding],
          );
        }
        case 'override': {
          // Replace in-place in the result array
          const idx = result.indexOf(existing);
          result[idx] = obj;
          map.set(obj.name, obj);
          actionsOwner.set(obj.name, i);
          unmergeableOwner.set(obj.name, declaredUnmergeableKeys(obj, i));
          break;
        }
        case 'merge': {
          refuseUnmergeableCollections(stacks, existing, obj, unmergeableOwner.get(obj.name)!, i);
          const declared = Object.fromEntries(
            Object.entries(obj).filter(([, value]) => value !== undefined),
          ) as Partial<Obj>;
          const merged = { ...existing, ...declared, fields: { ...existing.fields, ...obj.fields } } as Obj;
          const idx = result.indexOf(existing);
          result[idx] = merged;
          map.set(obj.name, merged);
          if (obj.actions !== undefined) actionsOwner.set(obj.name, i);
          break;
        }
      }
    }
  }

  return { objects: result.length > 0 ? result : undefined, actionsOwner };
}

/**
 * Cross-stack duplicate action keys over the COMPOSED action set (commit 35dffeace).
 *
 * `defineStack` refuses two declarations that resolve to one scope-qualified
 * runtime key within ONE stack ({@link collectDuplicateActionKeyErrors}), and
 * the runtime keys a composed artifact exactly the same way — so two input
 * stacks, each legal on its own, each declaring `global:shared_refresh`,
 * composed into one collapsed handler key: the same dead button, arriving one
 * composition step later. This is that walk over the composed set, with every
 * declaration attributed to the stack it came from.
 *
 * Judged on what composition CARRIES, not on what each input declared:
 *
 * - A standalone action reaches the output from every stack (`actions` is a
 *   `'concat'` collection), attributed to the stack that wrote it.
 * - An embedded action reaches the output through exactly ONE stack's object —
 *   the one `mergeObjects` handed the object's `actions` to (`actionsOwner`).
 *   Under `objectConflict: 'override'` the other stacks' embedded declarations
 *   on that object are not in the artifact at all, so they cannot collide with
 *   anything; that loss is the object strategy's own semantics, not an action
 *   collision. Under `'merge'` two objects declaring DIFFERENT `actions` are
 *   refused at `mergeObjects` before this walk runs (#14848), and identical
 *   ones are one declaration carried once — so the array attributed here never
 *   displaced another stack's entries.
 * - Only a key declared by TWO OR MORE DISTINCT stacks is reported. A key an
 *   input repeats within itself is `defineStack`'s door (which `strict: false`
 *   opts out of by choice) — and every input BUILT by `defineStack` repeats
 *   each bound standalone action legitimately, as the copy
 *   `mergeActionsIntoObjects` appended to its object on the way out. Counting
 *   sites instead of stacks would refuse every composition of built stacks that
 *   binds an action to an object.
 *
 * Deliberately NOT refused, as in `defineStack`: the cross-scope pair (a global
 * and an object-bound action sharing a name — two keys) and one name bound to
 * two different objects.
 *
 * Runs BEFORE `mergeActionsIntoObjects` so the composed output's own echo is
 * not counted either. Returns one line per colliding key, in first-seen order.
 *
 * [ADR-0112 · #19816] Reads only what is shaped like an action. A non-object
 * entry (`null`, `undefined`, a string, …) and an object's non-array `actions`
 * declare no key, so they are SKIPPED here, never dereferenced into a bare
 * `TypeError` and never keyed `global:undefined` (two such entries used to be
 * reported as a cross-stack collision). Skipping loses nothing: the entry is
 * still in the composed `actions` step 3 concatenated, and the object is the
 * same composed object, so step 7's guard in `mergeActionsIntoObjects` refuses
 * every one of them with its `STACK_SCHEMA_INVALID` / 422 envelope. That guard
 * holds the one refusal for this condition; this pass does not word a second.
 * @internal
 */
function collectComposedActionKeyCollisions(
  stacks: ObjectStackDefinition[],
  composedObjects: ObjectStackDefinition['objects'],
  actionsOwner: ReadonlyMap<string, number>,
): string[] {
  type Action = NonNullable<ObjectStackDefinition['actions']>[number];
  // key → stack index → where that stack declares it
  const sitesByKey = new Map<string, Map<number, string[]>>();
  const note = (scope: string, name: string, stackIndex: number, site: string): void => {
    const key = `${scope}:${name}`;
    const byStack = sitesByKey.get(key) ?? new Map<number, string[]>();
    const sites = byStack.get(stackIndex) ?? [];
    sites.push(site);
    byStack.set(stackIndex, sites);
    sitesByKey.set(key, byStack);
  };

  for (const [i, stack] of stacks.entries()) {
    // An absent `actions` declares nothing. A present non-array one never
    // reaches this pass: step 3 refuses it (`STACK_SCHEMA_INVALID`).
    const declared = (stack as Record<string, unknown>).actions;
    if (!Array.isArray(declared)) continue;
    for (const [j, action] of (declared as Action[]).entries()) {
      // A non-object entry declares no key; step 7 refuses it (see above).
      if (!isRecord(action)) continue;
      // Truthiness, not nullish: an empty-string `objectName` (type-legal;
      // refused by ActionSchema's regex only under strict parse) keys as
      // global here exactly as `collectDuplicateActionKeyErrors`,
      // `mergeActionsIntoObjects` and objectql's `standaloneActionOwnerKey`
      // resolve it.
      note(action.objectName || GLOBAL_ACTION_SCOPE, action.name, i, `stack.actions[${j}]`);
    }
  }
  for (const obj of composedObjects ?? []) {
    const owner = actionsOwner.get(obj.name);
    if (owner === undefined) {
      // Every composed object is recorded by `mergeObjects` the moment it is
      // first seen; a miss is an edit to that function that forgot the map,
      // and skipping would hide exactly the collisions this walk exists for.
      throw new Error(`composeStacks internal error: no source stack recorded for composed object '${obj.name}'.`);
    }
    // An absent `actions` declares nothing; a non-array one and a non-object
    // entry declare no key either, and step 7 refuses both (see above).
    const embedded: unknown = obj.actions;
    if (!Array.isArray(embedded)) continue;
    for (const [j, action] of (embedded as Action[]).entries()) {
      if (!isRecord(action)) continue;
      note(obj.name, action.name, owner, `objects['${obj.name}'].actions[${j}]`);
    }
  }

  const errors: string[] = [];
  for (const [key, byStack] of sitesByKey) {
    if (byStack.size < 2) continue;
    // Stack order, not note order — standalone declarations are walked before
    // embedded ones, so a later stack's standalone would otherwise be named
    // ahead of an earlier stack's embedded action.
    const parties = [...byStack.entries()]
      .sort(([a], [b]) => a - b)
      .map(([index, sites]) => `${stackLabel(stacks[index], index)} at ${sites.join(' + ')}`);
    errors.push(`Action key '${key}' is declared by ${byStack.size} stacks: ${joinDeclarationOrigins(parties)}.`);
  }
  return errors;
}

/**
 * The refusal `composeStacks` throws for {@link collectComposedActionKeyCollisions}
 * findings — `defineStack`'s envelope shape (a count, one `✗` line per key)
 * under the `composeStacks conflict:` prefix every other composition refusal
 * carries. Names no strategy option: there is none for actions by ruling.
 * @internal
 */
function formatComposedActionKeyCollisions(lines: readonly string[]): string {
  const header =
    `composeStacks conflict: cross-stack action key collision ` +
    `(${lines.length} issue${lines.length === 1 ? '' : 's'}):`;
  const body = lines.map((line) => `  ✗ ${line}`).join('\n');
  const why =
    `The runtime registers and dispatches every action under one exact-string key — the owning ` +
    `object's name (or '${GLOBAL_ACTION_SCOPE}' for an object-less action), a colon, then the action ` +
    `name — so only one of these handlers would be reachable in the composed artifact and the ` +
    `other declaration is a dead button: the collision defineStack refuses within one stack, ` +
    `arriving one composition step later. Each stack is legal on its own; the collision is between them.`;
  const fix =
    `Fix: rename one of the colliding actions within its scope, bind one of them to a different ` +
    `object, or remove the duplicate from one of the stacks. composeStacks does not pick a winner for actions.`;
  return `${header}\n\n${body}\n\n${why}\n${fix}`;
}

/**
 * Select the manifest to use from multiple stacks.
 * @internal
 */
function selectManifest(
  stacks: ObjectStackDefinition[],
  strategy: 'first' | 'last' | number,
): ObjectStackDefinition['manifest'] {
  if (typeof strategy === 'number') {
    return stacks[strategy]?.manifest;
  }
  if (strategy === 'first') {
    for (const s of stacks) {
      if (s.manifest) return s.manifest;
    }
    return undefined;
  }
  // 'last' (default)
  for (let i = stacks.length - 1; i >= 0; i--) {
    if (stacks[i].manifest) return stacks[i].manifest;
  }
  return undefined;
}

/**
 * The artifact package list for `manifest: 'preserve'` (ADR-0130 D4, follow-up
 * row 3).
 *
 * Every input stack contributes, in stack order, by **D4's read-both rule** —
 * the same rule the load path applies to an artifact, applied here to each
 * composition input, so composition and loading cannot disagree about what "the
 * packages of this stack" means:
 *
 * - `packages` present → its entries;
 * - `packages` absent  → the singular `manifest` as a single-element list.
 *
 * A stack carrying both therefore contributes its list once, not its list plus
 * its manifest — no de-duplication pass is needed, because nothing is emitted
 * twice in the first place.
 *
 * Entries are emitted as the `{ manifest: … }` wrapper object
 * {@link ArtifactPackageSchema} declares, never a flat inlined body: that
 * wrapper is the structural position ADR-0130 D4 reserves so a future
 * `{ ref, integrity }` external segment stays an ADDITIVE key. ⛔ The shape is
 * not re-derived here — a second declaration of one shape is the drift ADR-0116
 * exists about. A stack that ALREADY carries `packages` contributes those
 * entries untouched: they are assembled bodies already, and re-assembling one
 * would fold the composed stack's flattened collections onto a package that
 * does not own them.
 *
 * A `packages` value that is present but is not an array never reaches this
 * function. `composeStacks`' concat pass runs first and REFUSES it as
 * `STACK_SCHEMA_INVALID`, because such a value is malformed, not absent. The
 * rule is stated once, beside {@link AssembledPackageBodySchema}. So the
 * `Array.isArray` test below does not decide what a malformed value means: it
 * only separates a carried list from an ABSENT key, which takes the `manifest`
 * branch.
 *
 * @internal
 */
function preservePackageEntries(stacks: ObjectStackDefinition[]): ArtifactPackage[] {
  const entries: ArtifactPackage[] = [];
  for (const stack of stacks) {
    const declared = (stack as Record<string, unknown>).packages;
    if (Array.isArray(declared)) {
      entries.push(...(declared as ArtifactPackage[]));
      continue;
    }
    if (stack.manifest) entries.push({ manifest: assemblePackageBody(stack) });
  }
  return entries;
}

/**
 * The package-owned collection keys — every key an assembled package body
 * carries beyond its manifest fields, which is exactly the set option B moves
 * off the artifact's top level.
 *
 * DERIVED from {@link assembledPackageBodyShape}, never transcribed, so a
 * metadata family added to the stack schema is carried by a package body and
 * dropped from the flattened copy in the same change. Memoized because the
 * emitter reads it on every preserve composition, and computed lazily because
 * the shape it reads is built from the lazily-declared collection schemas.
 * @internal
 */
let cachedPackageOwnedKeys: readonly string[] | undefined;
function packageOwnedCollectionKeys(): readonly string[] {
  return (cachedPackageOwnedKeys ??= Object.freeze(Object.keys(assembledPackageBodyShape())));
}

/**
 * Does `packages` carry EVERY input's collections, so the flattened top level
 * can be dropped without losing one? (ADR-0130 D4 option B, #14512.)
 *
 * The emitter half of option B removes a COPY. It is only ever a copy when the
 * package list already carries what it removes, and two legal preserve inputs
 * make it something else:
 *
 * - **An input with no `manifest`.** {@link preservePackageEntries} contributes
 *   a body only for a stack that HAS a manifest, because a body is a manifest
 *   with collections written over it — there is no package to own a
 *   manifest-less stack's objects. Its collections reach the composed top level
 *   and nowhere else, so stripping would delete them outright. `manifest` is
 *   optional on {@link ObjectStackDefinitionSchema}, so this is not a
 *   hypothetical shape.
 * - **An input that already carries `packages` AND its own collections.** Such
 *   a stack contributes its entries untouched (re-assembling one would fold the
 *   composition's collections onto a package that does not own them), so its
 *   OWN top-level collections are attributed to no body either.
 *
 * Both cases keep today's additive output, which every reader still reads
 * (D4's read-both rule is unchanged, and `resolveArtifactCollections` in
 * `@objectstack/runtime` merges the two halves). ⛔ They are NOT refused here:
 * a composition that was legal before this change stays legal, and narrowing
 * the accept set is not what the ruling asked the emitter to do.
 *
 * The `< 2` floor is ADR-0130 D7 stated as a condition rather than trusted: a
 * single-package artifact keeps today's shape byte for byte, so an artifact
 * that reaches one package entry by any route — including a second input that
 * carried an empty `packages` array — is left flattened.
 * @internal
 */
function packagesCarryEveryInputCollection(
  stacks: readonly ObjectStackDefinition[],
  entries: readonly ArtifactPackage[],
): boolean {
  if (entries.length < 2) return false;
  const owned = packageOwnedCollectionKeys();
  for (const stack of stacks) {
    const source = stack as Record<string, unknown>;
    if (Array.isArray(source.packages)) {
      // Its entries are carried; its own collections are assembled into none.
      if (owned.some((key) => source[key] !== undefined)) return false;
      continue;
    }
    if (!stack.manifest) return false;
  }
  return true;
}

/**
 * A deterministic serialization with object keys sorted, so two copies of one
 * definition that differ only in key order compare equal.
 *
 * Mirrors `stableIdentity` in `@objectstack/runtime`'s `artifact-collections.ts`
 * — the reader that resolves these same collections back out of an artifact —
 * for the reason the two must not disagree: this function decides whether a
 * copy may be dropped, and that one decides what the dropped copy would have
 * contributed. ⛔ Never throws: a cycle encodes as `[circular]` and a callable
 * as `[function]`, because composition runs on the boot path of an `os dev`
 * config as well as over parsed JSON, and the alternative to a wrong answer
 * here is a build that dies inside a de-duplication helper. A callable
 * collapses to one token, so two DIFFERENT handlers compare equal — that is
 * safe in this direction only: `functions` is compared as a whole record and a
 * disagreement there is answered by KEEPING the flattened copy.
 * @internal
 */
function stableCollectionIdentity(value: unknown): string {
  const seen = new WeakSet<object>();
  const encode = (v: unknown): unknown => {
    if (typeof v === 'function') return '[function]';
    if (typeof v === 'bigint') return `${v}n`;
    if (v === null || typeof v !== 'object') return v;
    if (seen.has(v as object)) return '[circular]';
    seen.add(v as object);
    if (Array.isArray(v)) return v.map(encode);
    const out: Record<string, unknown> = {};
    for (const key of Object.keys(v as Record<string, unknown>).sort()) {
      out[key] = encode((v as Record<string, unknown>)[key]);
    }
    return out;
  };
  try {
    return JSON.stringify(encode(value)) ?? 'undefined';
  } catch {
    return '[unserializable]';
  }
}

/**
 * Does `packages` REPRODUCE the flattened collections this composition would
 * otherwise carry — every item, unaltered? (ADR-0130 D4 option B, #14512.)
 *
 * ## Why attribution is not enough, measured
 *
 * {@link packagesCarryEveryInputCollection} proves every INPUT's collections
 * reached a body. That is a different claim from the one the strip needs,
 * because {@link assemblePackageBody} folds the **input** stack while the
 * flattened top level holds the **composed** result, and composition is not
 * always a concatenation:
 *
 * - `objectConflict: 'merge'` / `'override'` RECONCILE two packages'
 *   same-named objects into one. The copy this strip would delete is the
 *   reconciled one; the bodies hold the two unreconciled halves. Measured on a
 *   two-package `merge` composition: the artifact's registration-path reader
 *   answers ONE object carrying both packages' fields with the flattened copy
 *   present, and TWO conflicting partial objects with it gone.
 * - {@link mergeActionsIntoObjects} binds a standalone action onto the object
 *   it names, INCLUDING an object a sibling package owns. The composed object
 *   carries that echo; the owning package's body does not.
 *
 * Neither is a shape difference — the collections' declarations are identical
 * on both sides — and neither is refused: both compose legally today. So the
 * emitter asks the question it actually depends on, per collection, and keeps
 * the additive shape whenever the answer is no.
 *
 * ## The comparison, and its granularity
 *
 * Multiset equality over {@link stableCollectionIdentity}, per key: every item
 * the flattened half carries must be carried by exactly one body, and no body
 * may carry an item the flattened half does not. ⛔ Not array-ORDER equality:
 * a `packages`-carrying artifact registers in dependency-topological order
 * (ADR-0130 D5), and a resolved collection's order is package order rather
 * than the flattened array's, so requiring order here would keep the copy in
 * cases where nothing at all is lost. What it does refuse is content: an item
 * altered, added or reconciled in the flattened half fails the test.
 *
 * A collection key carried as a RECORD (`functions`, `datasources` in its
 * record spelling) is compared whole, against the bodies merged in package
 * order with the first declaration winning. A key the bodies carry and the
 * flattened half does not fails too — the conservative direction, since the
 * strip may only ever remove a copy of something.
 * @internal
 */
function packagesReproduceComposedCollections(
  artifact: Record<string, unknown>,
  entries: readonly ArtifactPackage[],
): boolean {
  const bodies = entries.map((entry) => (entry as { manifest?: unknown }).manifest)
    .filter((body): body is Record<string, unknown> => body !== null && typeof body === 'object');
  if (bodies.length !== entries.length) return false;

  for (const key of packageOwnedCollectionKeys()) {
    const top = artifact[key];
    const declared = bodies.map((body) => body[key]).filter((value) => value !== undefined);
    if (top === undefined && declared.length === 0) continue;
    if (top === undefined) return false;

    if (Array.isArray(top) || declared.some((value) => Array.isArray(value))) {
      if (!Array.isArray(top)) return false;
      const fromBodies = declared.flatMap((value) => (Array.isArray(value) ? value : [value]));
      if (fromBodies.length !== top.length) return false;
      const left = top.map(stableCollectionIdentity).sort();
      const right = fromBodies.map(stableCollectionIdentity).sort();
      for (let i = 0; i < left.length; i += 1) if (left[i] !== right[i]) return false;
      continue;
    }

    if (top !== null && typeof top === 'object') {
      const merged: Record<string, unknown> = {};
      for (const value of declared) {
        if (value === null || typeof value !== 'object' || Array.isArray(value)) return false;
        for (const [entryKey, entryValue] of Object.entries(value as Record<string, unknown>)) {
          if (!(entryKey in merged)) merged[entryKey] = entryValue;
        }
      }
      if (stableCollectionIdentity(merged) !== stableCollectionIdentity(top)) return false;
      continue;
    }

    // A scalar is not a shape any collection key declares; nothing here can
    // establish that a body reproduces it, so the copy stays.
    return false;
  }
  return true;
}

/**
 * Fold ONE input stack into the assembled package body the artifact carries
 * (ADR-0130 D4; #14242 B).
 *
 * ## Why this is composition's job and nowhere else's
 *
 * Composition is the last moment at which per-package attribution EXISTS. The
 * composed stack flattens every collection to the top level — that is what
 * makes it one loadable stack — and a flattened `objects` array says nothing
 * about which package each object came from. Reconstructing the split
 * downstream (in `os build`, or at load) is not a harder version of this
 * function; it is impossible, because the information is gone. So the assembly
 * happens here, while both halves are still in hand.
 *
 * ## The shape, and why it is this one
 *
 * `{ ...manifest, ...collections }` — manifest fields flattened, then the
 * stack's own collections written over them. That is not a choice made here: it
 * is `AppPlugin`'s flatten (`{ ...bundle.manifest, ...bundle }`) and what
 * `ObjectQL.registerApp` reads, stated as data instead of re-derived at three
 * seams. {@link AssembledPackageBodySchema} is its declaration and
 * {@link ObjectStackDefinitionSchema}'s `packages` key parses against it, so a
 * body this function builds and a body the load path accepts cannot drift.
 *
 * ⚠️ This body is the artifact's ONLY copy of the collections it carries,
 * whenever the bodies reproduce what the flattened half would have held
 * (#14512, ADR-0130 D4 addendum 2026-09-22): the flattened top level is then
 * not emitted beside it, and a consumer reads the definitions here or not at
 * all. Where composition RECONCILED something the bodies do not carry — a
 * merged or overridden object, an action bound onto a sibling package's object
 * — the flattened half stays and this body is one of two copies, exactly as
 * before {@link composeStacks} learned to drop it. Every reader in the platform resolves
 * `packages[]` — the reader half of the same ruling — and D4's read-both rule
 * still reads an artifact already on disk that carries both halves. What
 * `packages` gives is per-package OWNERSHIP at registration, which is the whole
 * of ADR-0130 D1: without it, a composed multi-package artifact registers N
 * package records owning nothing at all.
 *
 * @internal
 */
function assemblePackageBody(stack: ObjectStackDefinition): AssembledPackageBody {
  const source = stack as Record<string, unknown>;
  const body: Record<string, unknown> = { ...(stack.manifest as Record<string, unknown> | undefined) };
  for (const key of Object.keys(assembledPackageBodyShape())) {
    if (source[key] !== undefined) body[key] = source[key];
  }
  return body as AssembledPackageBody;
}

/**
 * One `type: 'flow'` action target that resolved ONLY through
 * {@link DefineStackOptions.artifactFlows} (#25514): `subject` is the action
 * as the per-stack refusal names it, `target` the flow it launches.
 */
interface ArtifactFlowClaim {
  readonly subject: string;
  readonly target: string;
}

/**
 * The per-finding line for a flow target no scope resolves — ONE spelling for
 * the per-stack pass and the artifact pass, so a reader greps one string
 * whichever pass refused it.
 */
function flowTargetMessage(subject: string, target: string): string {
  return `${subject} references flow '${target}' which is not defined in flows.`;
}

/**
 * The symbol key the `artifactFlows` claims of a built stack live under.
 * `Symbol.for` for the provenance mark's reason (`stack-provenance.ts`): a CLI
 * and the config it loads may resolve two copies of this package.
 */
const ARTIFACT_FLOW_CLAIMS: symbol = Symbol.for('objectstack.stack.artifact-flow-claims');

/**
 * Stamp the claims `defineStack` let past the per-stack pass on the stack it
 * returns, and return that stack — the PROMISE half of
 * {@link DefineStackOptions.artifactFlows}, which
 * {@link collectArtifactFlowClaimErrors} redeems.
 *
 * Why a record and not a re-run (the shape {@link collectArtifactCrossReferenceErrors}
 * uses for objects): that pass re-runs its rules over every input, and for
 * flows a re-run judges more than the claim — it would newly refuse a dangling
 * target in an input built with `strict: false`, which never reached the
 * per-stack pass. The record holds exactly what the option let through, so
 * the composition checks the promise and nothing else.
 *
 * Non-enumerable, non-writable, non-configurable, like the mark it sits
 * beside: invisible to `ObjectStackDefinitionSchema`, to the compiled
 * `dist/objectstack.json` and to every `Object.keys` walk, and dropped by any
 * copy that drops the mark — which `composeStacks` refuses anyway. A stack
 * with no claim is returned untouched.
 */
function recordArtifactFlowClaims<T>(stack: T, claims: readonly ArtifactFlowClaim[]): T {
  if (claims.length === 0 || stack === null || typeof stack !== 'object') return stack;
  if (!Object.isExtensible(stack)) return stack;
  Object.defineProperty(stack, ARTIFACT_FLOW_CLAIMS, {
    value: Object.freeze(claims.map((claim) => Object.freeze({ ...claim }))),
    enumerable: false,
    writable: false,
    configurable: false,
  });
  return stack;
}

/** The claims {@link recordArtifactFlowClaims} stamped on `stack`, or `[]`. */
function artifactFlowClaimsOf(stack: unknown): readonly ArtifactFlowClaim[] {
  if (stack === null || typeof stack !== 'object') return [];
  const record = (stack as Record<symbol, unknown>)[ARTIFACT_FLOW_CLAIMS];
  return Array.isArray(record) ? (record as readonly ArtifactFlowClaim[]) : [];
}

/**
 * Every flow name `stack` provides: its own `flows`, plus each `packages[]`
 * body's when the input is itself a multi-package artifact — whose flows live
 * ONLY in those bodies (#14512), so reading the top level alone would refuse
 * a flow the input carries.
 */
function providedFlowNames(stack: unknown): string[] {
  const names: string[] = [];
  const collect = (flows: unknown): void => {
    if (!Array.isArray(flows)) return;
    for (const flow of flows) {
      if (isRecord(flow) && typeof flow.name === 'string') names.push(flow.name);
    }
  };
  if (!isRecord(stack)) return names;
  collect(stack.flows);
  if (Array.isArray(stack.packages)) {
    for (const entry of stack.packages) {
      if (isRecord(entry) && isRecord(entry.manifest)) collect(entry.manifest.flows);
    }
  }
  return names;
}

/**
 * The ARTIFACT pass for {@link DefineStackOptions.artifactFlows} (#25514): a
 * claimed flow target that NO input of the composition defines is refused,
 * with the per-stack pass's own message.
 *
 * Reads only the recorded claims (see {@link recordArtifactFlowClaims}), so an
 * input that never opted in cannot newly fail here — strict or not — and the
 * composition never judges a target the per-stack pass did not let through on
 * the artifact's credit.
 */
function collectArtifactFlowClaimErrors(stacks: readonly ObjectStackDefinition[]): string[] {
  const claims = stacks.flatMap((stack) => artifactFlowClaimsOf(stack));
  if (claims.length === 0) return [];
  const artifactFlowNames = new Set(stacks.flatMap((stack) => providedFlowNames(stack)));
  return claims
    .filter((claim) => !artifactFlowNames.has(claim.target))
    .map((claim) => flowTargetMessage(claim.subject, claim.target));
}

/**
 * The ARTIFACT pass of the cross-reference gate (#18202, ADR-0130 D1).
 *
 * ## What it discharges
 *
 * {@link DefineStackOptions.artifactObjects} lets a package's
 * `permissions[].objects` and `data[].object` name an object one of its SIBLING
 * packages owns — the shape ADR-0130's 2026-09-02 addendum (#14487) makes
 * mandatory once the `type: app` package, which keeps every permission set
 * whole, also owns objects of its own. That option is a PROMISE made at
 * `defineStack` time about a composition that has not happened yet. This
 * function is where the promise is redeemed: the composed object set is the
 * artifact, so a name no package in it defines is refused here, loudly, with
 * the same envelope and the same per-finding message the per-stack pass uses.
 *
 * ## Why it re-checks inputs that never opted in, and what that changes
 *
 * It does not read the option — the option is not recorded on the returned
 * stack, and deliberately so: recording it would put a composition-time concern
 * on `ObjectStackDefinitionSchema`, i.e. on every artifact already built. It
 * instead re-runs the two rules for every input. The invariant that buys is
 * narrower than "nothing can newly fail", and the narrower statement is the
 * true one:
 *
 * - **An input that passed the strict `defineStack` parse and did NOT opt in
 *   cannot newly fail here.** Its references already resolved against its own
 *   objects, and its own objects are a subset of the composed set — so
 *   re-running the two rules over a superset is a no-op. The qualifier is not
 *   decoration: an input that DID opt in also passed the strict parse, but its
 *   references resolved against its own objects PLUS the names it listed, and
 *   a listed name is exactly what this pass exists to check. Redeeming that
 *   claim against the real artifact is the whole point, so an opted-in input
 *   can and does fail here — that is the `ArtifactPass` fixture, not a gap.
 * - **An input that BYPASSED the strict parse is checked for these two rules
 *   here for the first time.** `defineStack(config, { strict: false })` returns
 *   before {@link validateCrossReferences} runs at all, and a hand-built stack
 *   object never enters it — so such an input has never had these two rules
 *   applied, and a dangling `permissions[].objects` key or `data[].object` in
 *   it is refused at composition where it previously composed.
 *
 * The second bullet is a real narrowing of what {@link composeStacks} accepts,
 * and it is DECLARED rather than incidental: it is the Prime Directive #12
 * direction (reject off-spec input at the producer, loudly), the changeset
 * states it, and `stack-artifact-crossref.test.ts` pins it as behaviour rather
 * than leaving it to be rediscovered as a regression. What it is NOT is a
 * licence to crash: the two collectors guard their own shapes, so an unparsed
 * input carrying a malformed `permissions` / `data` is warned about and skipped
 * — the same treatment {@link composeStacks}'s concat pass gives it — instead
 * of raising a bare `TypeError` outside the ADR-0112 envelope.
 *
 * ## The one leniency it inherits verbatim
 *
 * An input declaring NO objects is skipped, exactly as
 * {@link validateCrossReferences}'s `objectNames.size === 0` early return skips
 * it — that stack's references may be served by a plugin that is not in this
 * composition at all, and this pass is not the place to reopen that question.
 * It is also why hotcrm#1449's measurement (an app package declaring no
 * objects) never saw the defect #18202 reports.
 *
 * ## Known boundary — this pass runs only for TWO OR MORE packages
 *
 * {@link composeStacks} returns `stacks[0]` untouched for a single input, so a
 * one-package composition never reaches this pass. Together with a stack that
 * is never composed at all, that is the population whose `artifactObjects`
 * claim stands unverified — the same shape as `strict: false`, and for the same
 * reason: the author asserted something only a composition can confirm. So the
 * guarantee to state to authors is "a name no package in the artifact defines
 * is refused **in a composition of two or more packages**", never the
 * unqualified form. `os build` composes; a stack that does not is not a package
 * of an artifact.
 */
function collectArtifactCrossReferenceErrors(
  stacks: readonly ObjectStackDefinition[],
  composedObjects: readonly { name: string }[] | undefined,
): string[] {
  const artifactObjectNames = new Set<string>();
  for (const obj of composedObjects ?? []) artifactObjectNames.add(obj.name);
  if (artifactObjectNames.size === 0) return [];

  const errors: string[] = [];
  for (const stack of stacks) {
    if (collectObjectNames(stack).size === 0) continue;
    errors.push(...collectSeedDataObjectErrors(stack, artifactObjectNames));
    errors.push(...collectPermissionGrantObjectErrors(stack, artifactObjectNames));
  }
  return errors;
}

/**
 * Declaratively compose multiple stack definitions into a single unified stack.
 *
 * This eliminates the manual `...spread` merging pattern when combining
 * multiple applications (e.g., CRM + Todo + BI) into a single project.
 *
 * **Array fields** (apps, views, dashboards, etc.) are concatenated in order.
 * **Objects** are merged according to the `objectConflict` strategy.
 * **Manifest** is selected based on the `manifest` option — or, with
 * `manifest: 'preserve'`, every input's package identity is additionally folded
 * into `packages` (ADR-0130 D4) instead of N−1 of them being discarded, and a
 * multi-package artifact then carries its collections in those package bodies
 * ONLY, never also flattened at the top level (#14512).
 * **Single-valued configuration** (`i18n`, `api`, `server`, `runtimeModule`) is
 * neither overridden nor merged: identical declarations pass through, and two
 * stacks declaring *different* values throw an error naming both stacks
 * (#5005; `i18n` joined them in #5051).
 * **Actions** concatenate like every other collection, and the composed set is
 * then checked the way `defineStack` checks one stack (commit 35dffeace): two input
 * stacks whose declarations resolve to one scope-qualified runtime key
 * (`objectName:name`, or `global:name` for an object-less action) throw, and
 * the error names both stacks by manifest id and where each declaration sits.
 * There is no strategy option for actions — rename one, bind it to a different
 * object, or drop it from one stack. One global and one object-bound action
 * may still share a name (two keys); a key an input repeats within itself is
 * `defineStack`'s door rather than this one; and an embedded action that
 * `objectConflict: 'override'` did not carry into the composed object cannot
 * collide.
 * **`objectConflict: 'merge'`** shallow-merges `fields` only (#14848): two
 * objects that both declare any other object-level collection (`actions`,
 * `indexes`, `listViews`, `validations`, …) or fixed-shape config object
 * (`enable`, `access`, `protection`, `tenancy`, …; #16075) with different
 * values are refused, naming the object, the key and both stacks — nothing is
 * dropped in silence. Identical declarations pass; a scalar the later object
 * declares wins.
 *
 * @param stacks  - Stack definitions to compose (order matters for conflict resolution)
 * @param options - Composition options (conflict strategy, manifest selection, etc.)
 * @returns A single merged `ObjectStackDefinition`
 *
 * @example
 * ```ts
 * import { composeStacks, defineStack } from '@objectstack/spec';
 *
 * const crm = defineStack({ ... });
 * const todo = defineStack({ ... });
 *
 * // Simple composition — throws on duplicate objects, and on two stacks
 * // declaring one scope-qualified action key
 * const combined = composeStacks([crm, todo]);
 *
 * // Override strategy — later stacks win
 * const combined = composeStacks([crm, todo], { objectConflict: 'override' });
 *
 * // Merge strategy — `fields` shallow-merged; a collection or config object
 * // both objects declare differently (actions, indexes, enable, access, …)
 * // throws instead of being replaced
 * const combined = composeStacks([crm, todo], { objectConflict: 'merge' });
 *
 * // Preserve — one artifact carrying BOTH packages, each assembled (ADR-0130 D4)
 * const artifact = composeStacks([crm, cpq], { manifest: 'preserve' });
 * artifact.packages; // [{ manifest: { ...crmManifest, objects: [...] } }, …]
 * artifact.objects;  // undefined — each definition is carried ONCE, in its
 *                    // package body (#14512); `artifact.manifest` is retained
 * ```
 */
export function composeStacks(
  stacks: ObjectStackDefinition[],
  options?: ComposeStacksOptions,
): ObjectStackDefinition {
  // [ADR-0087 · ADR-0112] A composition that REFUSES carries the conversion
  // record the artifact would have carried — its inputs' records, by the rule
  // the return below uses ({@link composedConversions}) — so a door that
  // catches a composition conflict still reports what the inputs' own
  // `defineStack` calls converted. Composition converts nothing itself, so the
  // record is complete from the first line; `stackConversionsOf(error)` reads
  // it off the caught refusal.
  try {
    return composeBuiltStacks(stacks, options);
  } catch (error) {
    throw withRefusalConversions(error, () => composedConversions(stacks));
  }
}

/**
 * The conversion record of a composition: its inputs' records, concatenated
 * in input order, one application once — a `Set` over the (frozen,
 * identity-kept) notices counts the same built stack passed twice once. Each
 * notice's `path` stays relative to the `defineStack` call that applied it.
 * One formula for the artifact {@link composeStacks} returns and for the
 * refusal it throws.
 */
function composedConversions(stacks: readonly unknown[]): readonly ConversionNotice[] {
  return [...new Set(stacks.flatMap((stack) => stackConversionsOf(stack)))];
}

/** The body of {@link composeStacks}. */
function composeBuiltStacks(
  stacks: ObjectStackDefinition[],
  options?: ComposeStacksOptions,
): ObjectStackDefinition {
  // 0. [#20367 ruling B] Every input must be a stack a producer built. The
  //    per-stack refusals run only inside `defineStack`, so an input that never
  //    passed through it is unjudged, and nothing below re-judges it (the
  //    artifact pass in step 3b re-runs the artifact-scoped rules, not the
  //    family). FIRST, and before the single-input early return, so a lone
  //    plain object is refused as well rather than handed straight back.
  const unbuilt = stacks.flatMap((stack, i) => {
    if (hasStackProvenance(stack)) return [];
    return [stack !== null && typeof stack === 'object' ? stackLabel(stack, i) : `stack #${i}`];
  });
  if (unbuilt.length > 0) {
    const count = unbuilt.length;
    throw new StackProvenanceMissingError(
      `composeStacks provenance check failed (${count} input${count === 1 ? '' : 's'}): ` +
        `${unbuilt.join(', ')} ${count === 1 ? 'was' : 'were'} not built by \`defineStack\`. ` +
        `composeStacks composes only stacks \`defineStack\` (or a nested \`composeStacks\`) returned — ` +
        `the cross-field refusals run inside \`defineStack\`, so a plain object here would reach the ` +
        `artifact unjudged. Wrap each input: \`composeStacks([defineStack({ … }), …])\`. A spread ` +
        `(\`{ ...stack }\`) or JSON copy of a built stack drops the mark too: pass the built stack itself.`,
      unbuilt,
    );
  }

  if (stacks.length === 0) return markStackProvenance({}, 'composeStacks') as ObjectStackDefinition;
  if (stacks.length === 1) return stacks[0];

  const opts = ComposeStacksOptionsSchema.parse(options ?? {});

  const composed: Record<string, unknown> = {};

  // 1. Manifest — pick based on strategy.
  //
  //    `'preserve'` is not a fourth pick: the singular `manifest` is still
  //    selected by `'last'`, so the artifact keeps an artifact-level identity
  //    (ADR-0130 D6) and no consumer reading `composed.manifest` loses a key.
  //    What preserve adds is the package list built in step 3a; what step 7
  //    then removes, for a multi-package artifact, is the flattened copy of the
  //    collections those bodies carry (#14512).
  composed.manifest = selectManifest(stacks, opts.manifest === 'preserve' ? 'last' : opts.manifest);

  // 2. Objects — use conflict strategy (and remember, per composed object,
  //    which stack's `actions` array it carries — step 6 reads that).
  const { objects, actionsOwner } = mergeObjects(stacks, opts.objectConflict);
  if (objects) {
    composed.objects = objects;
  }

  // 3. Array collections — simple concatenation, in stack order.
  //
  //    [ADR-0112 · #19784] A collection key holding something that is not an
  //    array cannot be concatenated, and it is REFUSED, never skipped — step 2's
  //    rule for `objects`, applied to every concatenated key: skipping the value
  //    composes an artifact that silently lacks that stack's grants, seed rows,
  //    views, … (measured per key for every `CONCAT_ARRAY_FIELDS` entry: the
  //    skipped value's content was absent from the composed top level, and under
  //    `manifest: 'preserve'` survived only inside that stack's package body, so
  //    the artifact disagreed with itself). A composed artifact is complete or it
  //    is refused. `defineStack` rejects the shape at its own door, so this is
  //    reachable only via `strict: false` or a hand-built stack object; the code
  //    is the strict parse's own (`STACK_SCHEMA_INVALID`), as in step 2.
  //    `undefined` is the one non-array that is not malformed: the key is absent.
  //    A non-object ENTRY inside an array is concatenated as-is — the entry is
  //    carried, not lost, so the composed content is unchanged.
  for (const field of CONCAT_ARRAY_FIELDS) {
    const arrays: unknown[][] = [];
    for (const [i, stack] of stacks.entries()) {
      const declared: unknown = (stack as Record<string, unknown>)[field];
      if (declared === undefined) continue;
      if (!Array.isArray(declared)) {
        const { kind, issues } = describeNonArrayCollection(field, declared);
        throw new StackSchemaInvalidError(
          `composeStacks validation failed: ${stackLabel(stack, i)} declares '${field}' as ${kind}, ` +
            `not an array. Its '${field}' entries cannot be concatenated, and skipping them would ` +
            `compose an artifact that silently lacks them. Author '${field}' as an array` +
            ((MAP_SUPPORTED_FIELDS as readonly string[]).includes(field)
              ? ` (\`defineStack\` normalizes the map form into one)`
              : '') +
            `, or run the stack through strict \`defineStack\` to have the shape rejected where it ` +
            `is written.`,
          issues,
        );
      }
      arrays.push(declared);
    }
    if (arrays.length > 0) {
      composed[field] = arrays.flat();
    }
  }

  // 3a. `manifest: 'preserve'` — fold every input's package identity into the
  //     artifact package list (ADR-0130 D4, follow-up row 3).
  //
  //     Deliberately AFTER the concat pass, which owns `packages`' declared
  //     disposition and its malformed-value refusal. For stacks that already
  //     carry `packages`, preserve emits the same concatenation the pass just
  //     computed; what it adds is the single-`manifest` stacks the pass has
  //     nothing to concatenate for. Left undefined when there is nothing to
  //     preserve, so composing manifest-less stacks does not mint an empty
  //     array where today there is no key at all.
  if (opts.manifest === 'preserve') {
    const preserved = preservePackageEntries(stacks);
    if (preserved.length > 0) composed.packages = preserved;
  }

  // 3b. The ARTIFACT pass of the cross-reference gate (#18202). AFTER the
  //     collections are concatenated, because it reads the composed
  //     `permissions` / `data` of each INPUT against the composed `objects`;
  //     BEFORE anything else can throw on a stack whose references do not
  //     resolve in the first place. Never reached for a single input — the
  //     `stacks.length === 1` early return above is the declared boundary. See
  //     {@link collectArtifactCrossReferenceErrors} for which inputs this can
  //     and cannot newly refuse: an input that passed the strict parse cannot
  //     newly fail, an input that bypassed it is checked here for the first
  //     time.
  //     [#23015] …and two default record pages for one object across the
  //     inputs, each legal on its own: one deployment holds them both. It needs
  //     no object to resolve against, so it is not behind that pass's
  //     object-count early return.
  //     [ADR-0015 §4.2 · #25211] …and an `external` object of one input bound
  //     to a datasource another input declares managed: see
  //     {@link collectComposedExternalBindingDatasourceErrors}.
  //     [ADR-0015 amendment D7] …and a datasource's `external.connector`
  //     against the connectors of every input: see
  //     {@link collectComposedDatasourceConnectorErrors}.
  //     [#25234] …and one membership key declared on two objects of the
  //     composed artifact: see {@link collectComposedMembershipKeyErrors}.
  //     [#25514] …and every flow target an input resolved only through
  //     `artifactFlows`: see {@link collectArtifactFlowClaimErrors}.
  const artifactCrossRefErrors = [
    ...collectArtifactCrossReferenceErrors(
      stacks,
      objects as readonly { name: string }[] | undefined,
    ),
    ...collectComposedDefaultRecordPageErrors(stacks, opts.manifest === 'preserve'),
    ...collectComposedMembershipKeyErrors(stacks, objects as readonly unknown[] | undefined),
    ...collectComposedExternalBindingDatasourceErrors(stacks, objects),
    ...collectComposedDatasourceConnectorErrors(stacks, opts.manifest === 'preserve'),
    ...collectArtifactFlowClaimErrors(stacks),
  ];
  if (artifactCrossRefErrors.length > 0) {
    const count = artifactCrossRefErrors.length;
    const header = `composeStacks artifact cross-reference validation failed (${count} issue${count === 1 ? '' : 's'}):`;
    const lines = artifactCrossRefErrors.map((e) => `  ✗ ${e}`);
    throw new StackCrossReferenceError(`${header}\n\n${lines.join('\n')}`, artifactCrossRefErrors);
  }

  // 4. Named handler functions — merged by name (#5005).
  const functions = composeFunctions(stacks);
  if (functions.declared) {
    composed.functions = functions.value;
  }

  // 5. Every remaining top-level key (#5005) — `api`, `server`,
  //    `runtimeModule` and, since #5051, `i18n`.
  //
  //    This loop is the reason composition can no longer eat a key. It walks
  //    what the STACKS actually carry rather than a whitelist, so a key with a
  //    declared rule gets it, and a key without one is composed by the default
  //    AND reported — instead of being deleted in silence the way `api:` and
  //    `server:` were.
  const remainingKeys: string[] = [];
  for (const stack of stacks) {
    for (const key of Object.keys(stack as Record<string, unknown>)) {
      if ((stack as Record<string, unknown>)[key] === undefined) continue;
      if (key in composed) continue;
      const rule = COMPOSE_KEY_DISPOSITIONS[key as keyof ObjectStackDefinition];
      // Handled above (a declared key whose value happened to be absent from
      // every stack lands here too — nothing to compose, so skip it).
      if (rule !== undefined && rule !== 'single') continue;
      if (!remainingKeys.includes(key)) remainingKeys.push(key);
    }
  }

  for (const key of remainingKeys) {
    const rule = COMPOSE_KEY_DISPOSITIONS[key as keyof ObjectStackDefinition];
    if (rule === undefined) {
      // Not declared on ObjectStackDefinitionSchema at all — reachable via
      // `defineStack(..., { strict: false })` or a hand-built stack object.
      const isArray = stacks.some((s) => Array.isArray((s as Record<string, unknown>)[key]));
      warnUncomposedStackKey(key, isArray ? 'concat' : 'single');
      if (isArray) {
        composed[key] = stacks
          .map((s) => (s as Record<string, unknown>)[key])
          .filter((v): v is unknown[] => Array.isArray(v))
          .flat();
        continue;
      }
    }
    const single = composeSingleValue(stacks, key);
    if (single.declared) composed[key] = single.value;
  }

  // 6. Cross-stack action key collisions (commit 35dffeace) — the check `defineStack`
  //    runs within one stack, over what composition actually carries. AFTER
  //    every collection is composed, and BEFORE `mergeActionsIntoObjects`
  //    copies each bound standalone action into its object: that copy is the
  //    echo an input built by `defineStack` already carries, and counting it
  //    would make every bound action collide with itself.
  const actionCollisions = collectComposedActionKeyCollisions(stacks, objects, actionsOwner);
  if (actionCollisions.length > 0) {
    throw new StackComposeActionKeyCollisionError(
      formatComposedActionKeyCollisions(actionCollisions),
      actionCollisions,
    );
  }

  // 7. Bind every standalone action to its object — ONCE. Each input built by
  //    `defineStack` already carries its own bound actions on its objects (the
  //    echo step 6 steps around), and the surviving objects reach here as-is,
  //    so the merge appends only what an object does not already carry by
  //    identity (#14847): the other inputs' actions bound to it.
  const artifact = mergeActionsIntoObjects(composed as ObjectStackDefinition) as Record<string, unknown>;

  // 8. `manifest: 'preserve'` — a MULTI-package artifact carries each
  //    definition ONCE, under the package that owns it, so the flattened copy
  //    is not emitted at all (ADR-0130 D4 addendum 2026-09-22, maintainer
  //    ruling batch #23).
  //
  //    LAST, and that position is load-bearing: what may be deleted is what
  //    step 7 actually produced, so the reproduction test below reads the
  //    FINAL composed collections rather than an earlier draft of them. Steps
  //    3b and 6 keep reading the flattened collections before this point —
  //    the emitted shape narrows, the refusals do not.
  if (opts.manifest === 'preserve') {
    const entries = Array.isArray(artifact.packages) ? (artifact.packages as ArtifactPackage[]) : [];
    if (packagesCarryEveryInputCollection(stacks, entries)
      && packagesReproduceComposedCollections(artifact, entries)) {
      for (const key of packageOwnedCollectionKeys()) delete artifact[key];
    }
  }

  // [#20367 ruling B] Built from built inputs only (step 0), so the artifact is
  // a producer's output too: a nested `composeStacks` or an author-time door
  // accepts it.
  //
  // Its conversion record is its inputs' records ({@link composedConversions}).
  // Composition converts nothing itself — every input arrived canonical from
  // its own `defineStack` — so this is the whole of what was applied to build
  // the artifact.
  return markStackProvenance(artifact, 'composeStacks', composedConversions(stacks)) as ObjectStackDefinition;
}