object.zod.ts

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

import { z } from 'zod';
import { FieldSchema, type FieldType } from './field.zod';
import { ValidationRuleSchema } from './validation.zod';
import { ActionSchema, type ActionParam } from '../ui/action.zod';
import { ObjectListViewSchema } from '../ui/view.zod';

/**
 * API Operations Enum
 */
import { EvaluatedExpressionInputSchema, TemplateExpressionInputSchema, type EvaluatedExpression, type EvaluatedExpressionInput } from '../shared/expression.zod';
import { lazySchema } from '../shared/lazy-schema';
import { MetadataProtectionFields } from '../kernel/metadata-protection.zod';
import { closedObject, strictObject } from '../shared/strict-object';
import { ProtectionSchema } from '../shared/protection.zod';
import { retiredKey } from '../shared/retired-key';
import { refuseRecordProtoKey } from '../shared/record-proto-key-guard';
import { bannedKeys } from '../shared/refinement-projection';
import { FIELD_GROUP_KEY_PATTERN } from './field-group-layout';
// The masked-on-read declaration (#20141); `warnGenericPasswordFields` reads its
// `password` exemption rather than restating it. No runtime cycle: that module's
// only imports are type-only.
import { isMaskedOnReadFieldType } from './masked-field-types';
export const ApiMethod = z.enum([
  'get', 'list',                // Read
  'create', 'update', 'delete', // Write
  'bulk',                       // Batch operations
]);
export type ApiMethod = z.input<typeof ApiMethod>;

/**
 * The eight RETIRED legacy `apiMethods` values (#3543, P2 of #3391). Each is
 * DERIVED from the six primitives by the spec's single derivation table
 * (`API_METHOD_DERIVATION` in `api-derivation.ts`) — an author never declares
 * them. A stored/authored legacy value is stripped at parse by
 * {@link stripLegacyApiMethods} (canonicalize-and-warn, never a hard parse
 * failure): real metadata does not upgrade in lockstep with the spec, so this
 * tolerance is a PERMANENT compatibility layer, not a one-release transition.
 */
export const LEGACY_API_METHODS = [
  'upsert', 'aggregate', 'history', 'search', 'restore', 'purge', 'import', 'export',
] as const;
export type LegacyApiMethod = (typeof LEGACY_API_METHODS)[number];

/**
 * Tombstones for the retired legacy values — same doctrine as
 * `CAPABILITIES_RETIRED_KEY_GUIDANCE` below: the strip warning must carry the
 * FROM → TO prescription, because it is the one channel a consumer whose
 * metadata still declares a legacy value is guaranteed to hit.
 */
export const LEGACY_API_METHOD_GUIDANCE: Record<LegacyApiMethod, string> = {
  upsert: "declare ['create','update'] — `upsert` derives from create ∧ update",
  aggregate: "declare ['list'] — `aggregate` derives from list",
  history: "declare ['get'] with `enable.trackHistory: true` — `history` derives from get ∧ trackHistory",
  search: "declare ['list'] (with `searchable` not false) — `search` derives from list ∧ searchable",
  restore: "delete the value — `restore` never derives (`enable.trash` was retired because no runtime ever read it); it returns only with a real recycle bin, and that soft-delete work is parked",
  purge: "delete the value — `purge` never derives (`enable.trash` was retired because no runtime ever read it)",
  import: "declare ['create'] and/or ['update'] — `import` derives from create ∨ update (writeMode-precise at the gate)",
  export: "declare ['list'] — `export` derives from list",
};

/**
 * The canonical serialization order of the EFFECTIVE operation vocabulary —
 * the declaration order of the pre-#3543 fourteen-value enum, preserved
 * verbatim so the wire contract (405 `allowed` array, `/me/permissions`
 * `apiOperations`) is byte-stable across the shrink.
 */
export const API_OPERATION_ORDER = [
  'get', 'list', 'create', 'update', 'delete', 'upsert', 'bulk',
  'aggregate', 'history', 'search', 'restore', 'purge', 'import', 'export',
] as const;

/**
 * An effective API operation — the vocabulary of gates and wire serialization:
 * the six authored primitives plus the eight derived verbs. Authors declare
 * {@link ApiMethod}; servers derive and speak THIS (see `api-derivation.ts`).
 */
export type ApiOperation = (typeof API_OPERATION_ORDER)[number];

/**
 * Zod schema for {@link ApiOperation} — response-side surfaces that carry an
 * effective operation set (e.g. `EffectiveObjectPermissionSchema.apiOperations`)
 * validate against THIS, never against the authored {@link ApiMethod} enum.
 */
export const ApiOperationSchema = z.enum(API_OPERATION_ORDER);

const LEGACY_API_METHOD_SET: ReadonlySet<string> = new Set(LEGACY_API_METHODS);

/** Distinct legacy combinations already warned about (bounded; parse is hot). */
const warnedLegacyApiMethods = new Set<string>();

/**
 * Strip retired legacy values from an `apiMethods` whitelist before enum
 * validation (#3543). Non-arrays pass through untouched (the schema reports
 * them). Emits a single warning per distinct legacy combination — parse runs
 * on hot paths and carries no object-name context; the registration-time
 * diagnostic in objectql `registry.ts` adds the per-object view.
 *
 * The one behavioral cliff is called out loudly: a whitelist that becomes
 * EMPTY after stripping is `[]` = deny-all under the three-state contract,
 * so a pure-legacy whitelist (e.g. `['upsert']`) now closes the object's API
 * entirely instead of widening it.
 */
export function stripLegacyApiMethods(
  raw: unknown,
  opts?: { warn?: (msg: string) => void },
): unknown {
  if (!Array.isArray(raw)) return raw;
  const legacy = [...new Set(raw.filter(
    (v): v is LegacyApiMethod => typeof v === 'string' && LEGACY_API_METHOD_SET.has(v),
  ))];
  if (legacy.length === 0) return raw;
  const kept = raw.filter((v) => !(typeof v === 'string' && LEGACY_API_METHOD_SET.has(v)));
  const key = `${[...legacy].sort().join(',')}${kept.length === 0 ? '|deny-all' : ''}`;
  if (!warnedLegacyApiMethods.has(key)) {
    warnedLegacyApiMethods.add(key);
    const warn = opts?.warn ?? ((msg: string) => console.warn(msg));
    warn(
      `[spec] enable.apiMethods declares retired legacy value(s) [${legacy.join(', ')}] — ` +
        `the ApiMethod enum is the six primitives get/list/create/update/delete/bulk. ` +
        `Legacy values are stripped at parse; their semantics are DERIVED from the primitives:\n` +
        legacy.map((v) => `  • \`${v}\`: ${LEGACY_API_METHOD_GUIDANCE[v]}`).join('\n') +
        (kept.length === 0
          ? `\n  ⚠ After stripping, this whitelist is EMPTY — \`[]\` means DENY-ALL (fully closed ` +
            `API). Declare the underlying primitives if the object should stay reachable.`
          : '') +
        `\nCodemod: node scripts/codemod/apimethods-legacy-to-primitives.mjs`,
    );
  }
  return kept;
}

/**
 * Tombstones for RETIRED capability flags — same doctrine as the tenancy
 * block and the top-level `UNKNOWN_KEY_GUIDANCE` map below: a retired
 * key's rejection must carry the upgrade prescription, because the parse
 * error is the one channel every consumer bumping `@objectstack/spec` is
 * guaranteed to hit. Removed in the 16.x line (#2377, ADR-0049
 * enforce-or-remove).
 */
const CAPABILITIES_RETIRED_KEY_GUIDANCE: Record<string, string> = {
  trash:
    '`enable.trash` was removed from @objectstack/spec in the 16.x line (' +
    'ADR-0049) — it never had a runtime consumer: every delete has always been a ' +
    'hard delete, and a default-true flag promising a recycle bin was a false ' +
    'affordance (authors wrote `trash: false` believing they were opting out of a ' +
    'soft-delete that never ran). Delete the key. For recoverability use per-field ' +
    '`trackHistory` (audit trail) or a `lifecycle` policy; soft delete is parked, ' +
    'and if built returns as a live enforced flag (ADR-0049 prune-or-build). ' +
    'Run `os migrate meta --from 16` to list the mechanical edits for existing sources; `--write` applies the ones it can prove, and you apply the rest by hand.',
  mru:
    '`enable.mru` was removed from @objectstack/spec in the 16.x line (' +
    'ADR-0049) — Most-Recently-Used tracking was never implemented; no reader ' +
    'existed, so the flag changed nothing. Delete the key. If MRU tracking is ' +
    'built it returns as a live enforced flag (ADR-0049 prune-or-build). ' +
    'Run `os migrate meta --from 16` to list the mechanical edits for existing sources; `--write` applies the ones it can prove, and you apply the rest by hand.',
};

/**
 * The standing history sentence for the `enable` block, emitted LAST on every
 * rejection — the shared template's `history` slot.
 *
 * ## Why the slot, and why the fold waited for it (#6805)
 *
 * This block was the LAST hand-written `unrecognized_keys` map in this file.
 * #6619 folded its sibling `strictTenancyError` into the shared `strictObject`
 * template and left this one out for a reason it stated precisely: the map
 * emitted NO trailing sentence while `strictUnknownKeyError` appends its
 * `history` unconditionally (`${message} ${history}`). Measured again at #6805,
 * that is a statement about the TEXT and not about the template — `enable` has
 * a real history, it had simply never been written down. Writing it is the
 * whole of what the fold needed.
 *
 * The reading of the slot is #6619's, unchanged: what it encodes is *position*
 * — the one standing sentence that follows both fix channels (#5955 / #6416) —
 * so the surface decides what belongs there, and background is as legitimate as
 * literal history.
 *
 * The rejection itself is unchanged in kind: an unknown key — a retired
 * `trash`/`mru` or a typo like `feedEnabled` — is a loud, *fixable* parse error
 * instead of a silent strip (#1535), a retired key's error carries its upgrade
 * prescription, and every other issue code defers to zod's default. What the
 * fold changes is the *other* key: `searchible` now resolves to `searchable`
 * through the template's rename channel instead of being told only that it "is
 * not an `enable` capability flag", which named the problem and never the fix.
 * And it is what puts this table under `alias-integrity.test.ts`, which no
 * hand-rolled map has ever been judged by.
 *
 * ⚠️ `scripts/strictness-ledger.test.ts` used the `ObjectCapabilities` site
 * below as its `z.object(…).strict()` fixture. #6805 moved it to
 * `PerOperationRequiredPermissionsSchema` in this same file rather than
 * deleting the assertion, exactly as that test's own note instructs.
 */
const CAPABILITIES_HISTORY =
  'Until this shape was closed an unknown flag was dropped without a word — the object '
  + 'shipped as if the author had never written it; `enable` is a closed vocabulary '
  + 'in which every flag carries an enforcement contract.';

/**
 * Capability Flags
 * Defines what system features are enabled for this object.
 *
 * Modeled on industry standards (Salesforce "Allow Activities"/"Track Field
 * History"/"Enable Feed Tracking", Dataverse table options). Each flag has a
 * defined enforcement contract (#2707); a flag with no runtime consumer is a
 * bug, not a reservation — see `@objectstack/spec/liveness/object.json`.
 *
 * Opt-out flags (`feeds`, `activities`, `clone`, `searchable`, `apiEnabled`)
 * default to `true`: absent block/flag = enabled, and consumers gate on
 * explicit `false` only. Opt-in flags (`trackHistory`, `files`) default to
 * `false`.
 *
 * `.strict()`: unknown keys (incl. the retired `trash` / `mru`, #2377) are
 * rejected with guidance, not stripped (#1535).
 *
 * Closed with the shared `strictObject` template since #6805 — see
 * {@link CAPABILITIES_HISTORY} for why the fold waited on one sentence, and
 * what changes (and does not) about the message.
 *
 * ⚠️ ORDER IS LOAD-BEARING here for the same reason it is at
 * `ObjectSchemaBase` (#5593, ~1000 lines below): `strictObject` evaluates its
 * options object at CONSTRUCTION — that is what lets `alias-integrity.test.ts`
 * judge the table against the real `.shape` — so both
 * `CAPABILITIES_RETIRED_KEY_GUIDANCE` and `CAPABILITIES_HISTORY` must be
 * declared ABOVE this site. Moving either below it reintroduces the temporal
 * dead zone as a module-init crash under `OS_EAGER_SCHEMAS=1` (how
 * `build-schemas.ts` runs), which the test suite does not reach because tests
 * import lazily.
 *
 * @example
 * {
 *   trackHistory: true,
 *   searchable: true,
 *   apiEnabled: true,
 *   activities: false
 * }
 */
export const ObjectCapabilities = strictObject({
  surface: '`enable`',
  history: CAPABILITIES_HISTORY,
  guidance: CAPABILITIES_RETIRED_KEY_GUIDANCE,
}, {
  /**
   * History tracking (Audit Trail) master switch — opt-in.
   *
   * Contract: `true` surfaces the record History tab (audit-trail UI) in the
   * console. Pair with per-field `trackHistory: true` to select which field
   * diffs render as human-readable timeline summaries (ADR-0052 §5b). Audit
   * *capture* into `sys_audit_log` is a compliance ledger and stays on
   * regardless of this flag; retention is governed by data lifecycle
   * (ADR-0057), not by hiding the UI.
   */
  trackHistory: z.boolean().default(false).describe('Show the record History tab (audit-trail UI). Pair with per-field trackHistory to pick which field diffs are summarized; audit capture itself is always on for compliance'),

  /** Enable global search indexing */
  searchable: z.boolean().default(true).describe('Index records for global search'),

  /** Enable REST/MCP API access */
  apiEnabled: z.boolean().default(true).describe('Expose object via automatic APIs'),

  /**
   * API Supported Operations
   * Granular control over API exposure — a whitelist over the SIX PRIMITIVES
   * (#3391/#3543): `undefined` = unrestricted, `[]` = deny-all, a subset = the
   * derived closure (see `api-derivation.ts`). Retired legacy values are
   * stripped at parse by {@link stripLegacyApiMethods} (permanent tolerance
   * for stored metadata); the cast below keeps the AUTHORING type at the six
   * primitives so TS authors get the compile-time migration signal instead of
   * the `unknown` input a raw `z.preprocess` would infer.
   */
  apiMethods: (z.preprocess((raw) => stripLegacyApiMethods(raw), z.array(ApiMethod))
    .optional() as unknown as z.ZodOptional<z.ZodType<ApiMethod[], ApiMethod[]>>)
    .describe('Whitelist of allowed API operations (six primitives; undefined = all, [] = none)'),

  /**
   * Generic Attachments panel (Salesforce "Notes & Attachments" parity) —
   * opt-in.
   *
   * Contract (#2727): `true` surfaces the record Attachments panel in the
   * console (upload/list/download/delete over `sys_attachment` join rows)
   * and permits `sys_attachment` rows to target this object; anything else
   * rejects new attachments server-side (403 FILES_DISABLED, enforced at
   * the engine hook seam by plugin-audit — opt-in means explicit).
   * `Field.file` / `Field.image` column attachments are independent of
   * this flag.
   */
  files: z.boolean().default(false).describe('Generic record Attachments panel (sys_attachment). Opt-in: true surfaces the panel and permits attachments to target this object; otherwise any write that makes an attachment target it is rejected (403 FILES_DISABLED) — a create and an update that re-points an existing attachment alike. Field.file/Field.image are independent'),

  /**
   * Social collaboration (Comments, Mentions, Feeds) — opt-out.
   *
   * Contract: default on. An explicit `false` hides the record feed UI and
   * rejects new `sys_comment` rows targeting this object (403
   * FEEDS_DISABLED, enforced at the engine hook seam by plugin-audit).
   */
  feeds: z.boolean().default(true).describe('Record comments/collaboration feed. Default on; explicit false hides the feed UI and rejects any write that makes a comment target this object (403 FEEDS_DISABLED) — a new comment and an update that re-threads an existing one alike'),

  /**
   * Activity timeline (sys_activity mirror of create/update/delete) — opt-out.
   *
   * Contract: default on. An explicit `false` stops plugin-audit from
   * mirroring this object's CRUD into `sys_activity` (the record timeline)
   * and hides the timeline merge in the console. The off-switch is also the
   * per-object lever for activity-row growth (ADR-0057).
   */
  activities: z.boolean().default(true).describe('Record activity timeline (sys_activity mirror of CRUD). Default on; explicit false stops mirroring and hides the timeline'),

  /** Allow cloning records */
  clone: z.boolean().default(true).describe('Allow record deep cloning'),
});

/**
 * Schema for database indexes.
 *
 * The declaration surface is exactly what the driver materializes:
 * `name` / `fields` / `unique` (ADR-0120 scope). Nothing else — see the
 * retirement note below.
 *
 * @example
 * {
 *   name: "idx_account_name",
 *   fields: ["name"],
 *   unique: true
 * }
 *
 * ## `type` / `partial` were RETIRED at protocol 17 (#5248, #4943, ADR-0049)
 *
 * Both were authorable and had **zero** DDL consumers.
 * `SqlDriver.syncDeclaredIndexes` builds every declared index through knex's
 * `table.unique(fields, { indexName })` / `table.index(fields, name)`, and the
 * differ's `DeclaredIndexInput` (`driver-sql/src/schema-drift.ts`) carries
 * `name` / `fields` / `unique` / `nullSafeColumns` — neither key ever reached
 * a `CREATE INDEX`. `type` was the louder of the two because it also carried
 * `.default('btree')`, so it appeared in *every* parse output: a knob that had
 * never influenced a single statement, rendered as live configuration. That is
 * the exact shape ADR-0078 (no-silently-inert-metadata) and ADR-0049
 * (enforce-or-remove) exist to delete.
 *
 * The maintainer chose **remove** over **enforce** (2026-08-06, #5248):
 * enforcing would mean per-dialect algorithm mapping (`gin`/`gist` Postgres-only,
 * `fulltext` MySQL-only), raw-SQL `CREATE INDEX … WHERE` (MySQL has no partial
 * index at all), and a redesign of how `isSyncReproducibleIndex` excludes
 * partial indexes from incremental sync — real design cost for a capability
 * nothing has asked for. If a genuine need appears, it comes back enforce-first.
 *
 * Replacements: an index **method** is the driver/dialect's choice, not a
 * declaration-surface concern. A **partial** index is built at the database
 * layer (a runtime migration issuing `CREATE UNIQUE INDEX … WHERE`, the way
 * `metadata-protocol`'s `ensureOverlayIndex` does for `sys_metadata`); drift
 * detection's exemption for DB-authored partial indexes is unaffected —
 * `isSyncReproducibleIndex` reads a boolean parsed out of the database's OWN
 * DDL (`parseIndexDdl`), which never had anything to do with this string.
 *
 * ⚠️ The tombstones sit at the BOTTOM of the shape deliberately (#5606): the
 * docs renderer prints only the first `INLINE_KEY_LIMIT` keys of an inline
 * shape and has no `z.never()` branch, so a tombstone high in the shape prints
 * as `any` and reads as a free-form slot.
 *
 * ## Closed at #4001 批 20 site 14 — the batch's held site, after its producer converged
 *
 * This shape was 批 20's ONE deliberately-open site. The console's embedded
 * index editor (`objectui` → `metadata-admin/EmbeddedItemEditor.tsx`,
 * `FALLBACK_SCHEMAS.index`) ships its own hand-copied JSON-Schema for this
 * shape — the framework publishes none, because `index` is an embedded-only
 * sub-type with no metadata type of its own — and that copy had drifted: it
 * offered **`where`** for the partial predicate and **`brin`** in the
 * algorithm enum, spliced its form output into `object.indexes[]`, and PUT
 * the WHOLE object. Closing the shape while those controls rendered would
 * have turned an admin's clean save into a 422 on a control the console
 * itself drew (the #5114 class), so the strip was held until the producer
 * was fixed (contract-first: the drift was in the copy, not here).
 *
 * objectui#4772 (#5247's fix) deleted both drifted controls — the fallback
 * now offers exactly `name` / `fields` / `unique`, converged to this schema —
 * so the hold's evidence is spent and the shape is `strictObject` like its
 * thirteen siblings. `where` keeps a curated `guidance` entry rather than a
 * rename suggestion: the predicate never reached any DDL under EITHER
 * spelling (`syncDeclaredIndexes` consumes `name`/`fields`/`unique` only),
 * and the replacement is a database-layer migration, not another key — a
 * rename onto the retired `partial` tombstone would be the campaign's
 * finding 7 (a suggestion pointing into a second rejection).
 */
/**
 * The refusal of a bare `unique: true` on a DECLARED INDEX (ADR-0120 D1 / D5a,
 * retired at protocol 18 per D7).
 *
 * Bare `true` was the one spelling on this key whose scope was encoded by
 * POSITION: on a declared index it set neither driver flag and materialized
 * over exactly `fields` — installation-wide — while reading like "unique per
 * organization" to anyone who knew the field-level meaning (the #4986 trap).
 * 17.x warned (lint `unique/unscoped-declared-index`); protocol 18 refuses it,
 * so the scope is always STATED. Field-level `unique: true` is untouched — it
 * has one documented meaning there and stays valid (D1).
 *
 * Stored and built metadata never meets this refusal: the protocol-18 ADR-0087
 * conversion `declared-index-unique-scope` rewrites a declared index's bare
 * `true` to `'global'` — byte-identical physical index, zero drift — on every
 * data-at-rest seam (`applyConversionsToStoredItem`, the artifact door inside
 * its declared-floor window, `os migrate meta`). It is retired from the
 * authoring funnel, so a live author is refused here and taught the explicit
 * spelling instead of being converted silently.
 *
 * ⛔ Runtime text — no tracker numbers (`check:doc-authoring`).
 */
const DECLARED_INDEX_BARE_TRUE_RETIRED =
  '`indexes[].unique: true` was retired at protocol 18 (ADR-0120 D1) — on a declared index '
  + 'bare `true` never stated a scope: it built the index over exactly `fields`, one holder '
  + 'across the whole installation, while reading like "unique per organization". State the '
  + "scope: `unique: 'global'` (installation-wide — the exact index bare `true` built, so "
  + "nothing on disk changes) or `unique: 'organization'` (one holder per organization — the "
  + 'driver prepends the NULL-safe organization key part to `fields` at registration). '
  + 'Field-level `unique: true` is unaffected. '
  + 'Run `os migrate meta --from 17` to list the mechanical edits for existing sources; `--write` applies the ones it can prove, and you apply the rest by hand.';

/**
 * Prescriptive rejection for a mis-spelled `unique` scope **on a DECLARED
 * INDEX** — the sibling of `field.zod.ts`'s `uniqueScopeError`, and the reason
 * the two are not one map.
 *
 * Same near-miss table, same `invalid_union` channel. The two surfaces differ
 * on exactly one member, and it is the one an author acts on: **bare `true`.**
 * At field level `true` resolves per-organization, so naming `'organization'`
 * "the explicit spelling of true" is a true and useful hint. On this surface
 * `true` used to set neither driver flag and materialize over exactly
 * `fields` — i.e. `'global'` is what it spelled — and since protocol 18 it is
 * REFUSED here with {@link DECLARED_INDEX_BARE_TRUE_RETIRED}, which names both
 * replacements and which one keeps the index it built. Telling an author who
 * had just been refused on this key to write `'organization'` for what they
 * already had would ask the driver to prepend the NULL-safe organization key
 * part at registration — a materialization change, silently, on an index that
 * may already exist on deployed databases: the unannounced index
 * reinterpretation the #8323 ruling (maintainer, 2026-08-13) rejects.
 *
 * ⛔ The accepted set is `UniqueScopeSchema`'s MINUS bare `true`, and nothing
 * else may differ — `unique-scope-message.test.ts` pins both surfaces against
 * one value table whose only split row is `true`, so a member added or dropped
 * on either side fails there rather than diverging quietly.
 *
 * Declared before `IndexSchema` because `OS_EAGER_SCHEMAS=1` evaluates the
 * factory at module load (TDZ) — same constraint as the field-surface map.
 */
const declaredIndexUniqueScopeError: z.core.$ZodErrorMap = (issue) => {
  if (issue.code !== 'invalid_union') return undefined;
  const input = (issue as { input?: unknown }).input;
  if (input === true) return DECLARED_INDEX_BARE_TRUE_RETIRED;
  const spelled = typeof input === 'string' ? `'${input}'` : String(input);
  const nearMiss =
    input === 'tenant' || input === 'org'
      ? ` ${spelled} is not accepted and is not an alias — the per-organization scope is spelled 'organization' (ADR-0120: "tenant" is overloaded across deployment topologies, and the platform spells the word out).`
      : '';
  return (
    `Invalid unique scope ${spelled}. Allowed: false, 'organization' ` +
    `(one holder per organization — the driver prepends the NULL-safe ` +
    `organization key part to \`fields\` at registration), or 'global' ` +
    `(one holder across the whole installation — materialized over exactly ` +
    `\`fields\`). Bare true is not accepted on a declared index: state the ` +
    `scope.${nearMiss}`
  );
};

/**
 * `UniqueScopeSchema`'s declared-index twin: the same vocabulary minus bare
 * `true` (retired at protocol 18 — see {@link DECLARED_INDEX_BARE_TRUE_RETIRED}),
 * refused in the index surface's own words. See `declaredIndexUniqueScopeError`
 * above for why the message cannot be shared, and `field.zod.ts`'s
 * `UniqueScopeSchema` for the scope vocabulary itself (ADR-0120 D1) — the
 * member list is written out deliberately and pinned against the field's,
 * never re-derived.
 *
 * `false` stays a member: "not unique" states no scope and needs none, and it
 * is the key's default.
 */
const DeclaredIndexUniqueScopeSchema = lazySchema(() =>
  z.union([z.literal(false), z.literal('global'), z.literal('organization')], {
    error: declaredIndexUniqueScopeError,
  }),
);

export const IndexSchema = lazySchema(() => strictObject({
  surface: 'this index',
  history:
    'Until this site was closed (held back until the console\'s drifted index ' +
    'editor converged), an unknown key here was dropped ' +
    'silently: the index still parsed and registered, minus whatever the author ' +
    'believed the key did.',
  guidance: {
    where:
      '`where` has never been an index key in this protocol — it was the console ' +
      "fallback editor's drifted spelling for a partial-index predicate (since " +
      'removed), and no driver ever emitted a predicate under either ' +
      'spelling. Delete the key. A partial index is built at the database layer, not ' +
      'the declaration surface: issue `CREATE [UNIQUE] INDEX … WHERE <predicate>` from ' +
      "a runtime migration (what `metadata-protocol`'s `ensureOverlayIndex` already " +
      'does for `sys_metadata`).',
  },
}, {
  name: z.string().optional().describe('Index name (auto-generated if not provided)').meta({ title: 'Name' }),
  fields: z.array(z.string()).describe('Fields included in the index').meta({ title: 'Fields' }),
  // Unique scope on a DECLARED index (ADR-0120 D1, amending #3696):
  //
  //   - `'global'` — the VERBATIM contract: materialized over exactly the
  //     columns listed in `fields`, no organization column injected. Correct
  //     for genuinely installation-wide reservations (a DNS hostname, a
  //     reserved slug, an external provider id, every engine dedup key).
  //   - `'organization'` — one holder per organization: the driver prepends
  //     the organization key part to the listed columns at REGISTRATION,
  //     where tenancy is known (authoring-time inference is impossible —
  //     `organization_id` is kernel-injected, not authored). The key part is
  //     NULL-safe — `COALESCE(organization_id, '__global__')` (ADR-0120 D3,
  //     #5030): NULL-organization rows form one platform bucket instead of
  //     escaping the constraint under SQL's NULL-distinct semantics.
  //     Materialization lands with #5030's driver PR. On an object with no
  //     organization column it degrades to the listed columns alone,
  //     mirroring field-level behavior.
  //   - bare `true` — REFUSED since protocol 18 (#5082, ADR-0120 D7). It
  //     was the positional spelling of `'global'`, the one spelling whose
  //     meaning was encoded by position (the #4986 trap): 17.x warned
  //     through lint `unique/unscoped-declared-index`, and the parse now
  //     refuses it with a prescription naming both words. Stored and built
  //     metadata converts to `'global'` instead (the ADR-0087 conversion
  //     `declared-index-unique-scope`, byte-identical physical index). State
  //     the scope.
  //   - `false` (or omitted) — not unique; states no scope and needs none.
  //
  // The old advice "spell a per-tenant index as
  // `fields: ['organization_id', 'code']`" survives as valid legacy input,
  // but new code says `unique: 'organization'` — the hand-written composite
  // is NOT NULL-safe (#5030).
  unique: DeclaredIndexUniqueScopeSchema.optional().default(false).describe("Whether the index enforces uniqueness, and at which scope (ADR-0120). 'global' = materialized over exactly `fields`, no organization column injected — one holder across the whole installation; 'organization' = the driver prepends the NULL-safe organization key part (COALESCE(organization_id, '__global__')) at registration — one holder per organization; false/omitted = not unique. Bare true is refused (retired at protocol 18 — it was the positional spelling of 'global'): state the scope. 'tenant'/'org' are rejected — the word is 'organization'").meta({ title: 'Unique' }),

  // ── Tombstones (ADR-0049 / ADR-0087) ─────────────────────────────────
  // Kept LAST in the shape on purpose — see the #5606 note in the block
  // comment above. `IndexSchema` is not `.strict()`, so a plain delete would
  // make Zod strip an authored value silently, which is the same no-op these
  // keys already were (#3726 / #3733, the ADR-0104 class). The tombstone
  // makes the removal audible in the two channels an upgrading author
  // actually reads: `tsc` (input type `never`) and the parse itself.
  // `object-index-type-partial-removed` strips both from stored/authored
  // sources on the protocol-17 migration.
  type: retiredKey(
    '`indexes[].type` was removed in @objectstack/spec 17.0.0 (ADR-0049) — no driver ever ' +
    'read it. `SqlDriver.syncDeclaredIndexes` creates every declared index through knex\'s ' +
    '`table.index()` / `table.unique()`, which cannot express an access method, so the value ' +
    'changed no DDL; its `.default(\'btree\')` merely made an inert knob show up in every parse ' +
    'output. Delete the key. The index method is the driver/dialect\'s decision (Postgres ' +
    'defaults to B-tree; `gin`/`gist`/`fulltext` are dialect-specific and are chosen by a ' +
    'database-layer migration when a workload actually needs one). ' +
    'Run `os migrate meta --from 16` to list the mechanical edits for existing sources; `--write` applies the ones it can prove, and you apply the rest by hand.',
  ),
  partial: retiredKey(
    '`indexes[].partial` was removed in @objectstack/spec 17.0.0 (ADR-0049) — no ' +
    'driver ever emitted the `WHERE` clause, so a declared partial index was materialized as a ' +
    'FULL index and the predicate silently did nothing. Delete the key. Partial indexes are ' +
    'built at the database layer, not the declaration surface: issue `CREATE [UNIQUE] INDEX … ' +
    'WHERE <predicate>` from a runtime migration (this is what `metadata-protocol`\'s ' +
    '`ensureOverlayIndex` already does for `sys_metadata`). Drift detection is unaffected — it ' +
    'reads partiality back from the database\'s own DDL, never from this key. ' +
    'Run `os migrate meta --from 16` to list the mechanical edits for existing sources; `--write` applies the ones it can prove, and you apply the rest by hand.',
  ),
}));

/**
 * Tombstones for RETIRED tenancy keys — same doctrine as the top-level
 * `UNKNOWN_KEY_GUIDANCE` map below: a retired key's rejection must carry the
 * upgrade prescription, because the parse error is the one channel every
 * consumer bumping `@objectstack/spec` is guaranteed to hit. Removed after
 * spec 15.0 by owner decision #2763 (enforce-or-remove, ADR-0049; precedent
 * ADR-0056 D8 — compliance-grade config must never merely look live).
 */
const TENANCY_RETIRED_KEY_GUIDANCE: Record<string, string> = {
  strategy:
    '`tenancy.strategy` was removed from @objectstack/spec after v15.0 — it ' +
    'never had a consumer. The platform has exactly two tenancy modes and neither is ' +
    'object-level config: database-per-tenant isolation is an environment/deployment ' +
    'choice (each environment carries its own database URL), and row-level isolation ' +
    'is `tenancy.enabled` + `tenancy.tenantField`. Delete the key.',
  crossTenantAccess:
    '`tenancy.crossTenantAccess` was removed from @objectstack/spec after v15.0 — it ' +
    'never had a consumer; setting it granted nothing. Cross-tenant visibility is ' +
    'governed by sharing rules / OWD (ADR-0056), `externalSharingModel` (ADR-0090 ' +
    'D11), and the object access posture. Delete the key.',
  organizationField:
    '`tenancy.organizationField` was removed in @objectstack/spec 17 (ADR-0049) — it ' +
    'named the column a platform row is stamped from, and exactly one table in the ' +
    'whole protocol ever needed one: the better-auth credential table, whose rows are ' +
    'about the organization a key authenticates into while the table itself must stay ' +
    'unwalled. That is a fact about a platform table, not a knob an application ' +
    'declares, and on an ordinary object the stamp column and the tenant column are ' +
    'the same column — so every declaration outside the platform either restated the ' +
    'default or asked for a divergence no sanctioned consumer would honour. Delete ' +
    'the key. Stamping now reads a platform-internal table in ' +
    '`@objectstack/metadata-core`; an object whose tenant column genuinely is not ' +
    '`organization_id` declares `tenancy.tenantField`, which both walls it and stamps ' +
    'its platform rows. ' +
    'Run `os migrate meta --from 17` to list the mechanical edits for existing sources; `--write` applies the ones it can prove, and you apply the rest by hand.',
};

/**
 * The standing two-modes explainer, emitted LAST on every `tenancy` rejection.
 *
 * It occupies the template's `history` slot, which is the slot for exactly this
 * — the one sentence of standing background that follows both fix channels
 * (#5955 / #6416). It is background rather than history in the literal sense,
 * and that is fine: the contract the slot encodes is *position*, and this
 * sentence is the thing that must not sit in front of a key's own prescription.
 * On the single-line renders several consumers use (`os validate`'s
 * `• where: message`, CI logs) it used to bury each bullet behind ~160
 * characters.
 */
const TENANCY_MODES_EXPLAINER =
  'The two supported tenancy modes are: database-per-tenant = environment-level '
  + 'deployment (no object config); row-level isolation = `tenancy.enabled` + '
  + '`tenancy.tenantField`.';

/**
 * Multi-Tenancy Configuration Schema
 * Row-level tenant isolation for shared-database SaaS applications: the
 * tenant field is injected on write and enforced on read (RLS predicate).
 * Platform objects declare `enabled: false` to opt out of org row-scoping
 * (environment-level objects). Database-per-tenant isolation is NOT object
 * metadata — it is an environment/deployment choice.
 *
 * `.strict()`: unknown keys (incl. the retired `strategy` /
 * `crossTenantAccess`, #2763) are rejected with guidance, not stripped (#1535).
 *
 * Closed with the shared `strictObject` template since #6619. The tombstone
 * bullets and the trailing explainer are byte-for-byte what the hand-written
 * `strictTenancyError` emitted; what the fold changes is the *other* key — a
 * near-miss like `tenantfield` now resolves to `tenantField` through the
 * template's rename channel instead of being told only that it "is not a
 * `tenancy` key", which named the problem and never the fix. Folding it in is
 * also what puts this table under `alias-integrity.test.ts`, which no
 * hand-rolled map has ever been judged by.
 *
 * `tenantField` carries **no default** (#5315). It used to default to
 * `'tenant_id'`, which no consumer could act on: the platform's tenant column
 * is `organization_id` (kernel-injected; the same column `tenantPolicy()` in
 * `security/rls.zod.ts` and the RLS predicates assume), and the SQL driver's
 * `computeTenantField` honours a declared name only when the object actually
 * has that field — so the materialized `'tenant_id'` merely sent it looking for
 * a column that did not exist before falling back to `organization_id` anyway.
 * A declaration nobody reads is exactly what ADR-0078 prohibits, and `tenant`
 * is a word ADR-0120 §Terminology refuses for the authorable vocabulary
 * (`organization` is the product's noun). Undeclared now stays `undefined` and
 * the driver's fallback is the single source of truth.
 *
 * `organizationField` is RETIRED from this shape (protocol 18, ADR-0049;
 * maintainer ruling 2026-09-18, verbatim and untranslated:
 * 「organizationField 撤出可授权面 同意你的建议」). It answered "which column says
 * who this row is ABOUT" while `tenantField` answers "what is this object
 * WALLED by", and on an ordinary object the two are the same column — the
 * former prose in this docblock said so in as many words ("for ordinary
 * objects the two coincide and `organizationField` is never needed"). Exactly
 * ONE table in the protocol ever diverged, and it is a table the platform
 * itself ships: `sys_api_key` records the organization a key authenticates
 * into under `active_organization_id` precisely so the credential table does
 * NOT become org-walled (#8287). A fact about one platform table is not a knob
 * an application declares — an authorable key here made every future piece of
 * organization logic ask "what if somebody set this?" for a divergence no
 * sanctioned consumer would have honoured anyway.
 *
 * The divergence itself is unchanged and still shipped: stamping resolves it
 * from a platform-internal table in `@objectstack/metadata-core`
 * (`PLATFORM_STAMP_ORGANIZATION_COLUMNS`, read by the STAMP face alone), so
 * the three sanctioned platform-row writers — audit stamping, the
 * approval-row writer in `plugin-approvals`, and the automation-run recorder
 * in `service-automation` — keep the behaviour they had, byte for byte, with
 * no authorable input. The WALL face
 * (`resolveRecordWallOrganizationField`, #18378) never read the key and is
 * untouched.
 *
 * ⛔ What does NOT come back with a new spelling: an application-declared
 * "stamp column" of any name. The retirement is the ADR-0049 answer to a key
 * whose only real declaration was ours; re-opening it needs its own maintainer
 * ruling, exactly as the original scope-pin required of a fourth consumer.
 *
 * @example Shared database, platform-default tenant column (organization_id)
 * {
 *   enabled: true
 * }
 *
 * @example An object whose tenant column is genuinely not organization_id
 * {
 *   enabled: true,
 *   tenantField: 'workspace_id'
 * }
 *
 * @example An object that opts out of org row-scoping entirely (ADR-0066)
 * {
 *   enabled: false
 * }
 */
export const TenancyConfigSchema = lazySchema(() => strictObject({
  surface: '`tenancy`',
  history: TENANCY_MODES_EXPLAINER,
  guidance: TENANCY_RETIRED_KEY_GUIDANCE,
}, {
  enabled: z.boolean().describe('Enable multi-tenancy for this object'),
  tenantField: z.string().optional().describe(
    'Column this object is tenant-scoped by. Omit it unless the tenant column ' +
    "genuinely is not the platform's: when undeclared the driver falls back to " +
    '`organization_id`, the kernel-injected column the RLS predicates and ' +
    '`tenantPolicy()` also assume. A declared name is honoured only when the ' +
    'object really has that field — otherwise the same `organization_id` ' +
    'fallback applies. No default is materialized here on purpose.',
  ),
  // `organizationField` was REMOVED here in protocol 18 (ADR-0049) — see the
  // docblock above. This shape is `.strict()`, so the key is rejected with its
  // prescription from `TENANCY_RETIRED_KEY_GUIDANCE` rather than stripped, and
  // the D2 conversion `object-tenancy-organization-field-removed` deletes it
  // from older sources and stored rows. The `sys_api_key` divergence it used to
  // carry now lives in `@objectstack/metadata-core`'s
  // `PLATFORM_STAMP_ORGANIZATION_COLUMNS`, which no author writes.
}));

/**
 * [ADR-0066] Platform-global posture: `tenancy.enabled === false` explicitly
 * opts the object out of row-level org scoping, even when it carries an
 * `organization_id` column (e.g. `sys_license` keeps an optional owner FK).
 * Single source of truth for the registry (tenant-column injection), the
 * ObjectQL engine (tenantId propagation into driver options), and drivers
 * (native scoping) — previously each re-derived `tenancy?.enabled === false`
 * independently and could drift (#3249).
 */
export function isTenancyDisabled(schema: unknown): boolean {
  return (schema as { tenancy?: { enabled?: boolean } } | null | undefined)?.tenancy?.enabled === false;
}

/**
 * [ADR-0066 D2] Secure-by-default object posture.
 *
 * Declares whether the object participates in blanket wildcard permission
 * grants — a data-model posture like {@link TenancyConfigSchema}, NOT an
 * assignment (it names no principal).
 *
 * - `public` (default) — covered by a permission set's `'*'` wildcard object
 *   grant; today's allow-by-default behaviour.
 * - `private` — NOT covered by the `'*'` wildcard grant; access requires an
 *   EXPLICIT per-object grant (Salesforce "new object = no access until
 *   granted"). A `private` object is ALSO exempt from wildcard RLS
 *   (`tenant_isolation`, owner scoping): the posture-gated superuser bypass
 *   (`viewAllRecords`/`modifyAllRecords`) short-circuits RLS, so a platform
 *   admin — incl. one who is also an org admin whose `tenant_isolation` would
 *   otherwise narrow the result — sees all rows, while non-admins without an
 *   explicit grant see none.
 *
 * Pair with the object's `requiredPermissions` (D3) to additionally gate access
 * on holding a capability.
 */
export const ObjectAccessConfigSchema = lazySchema(() => strictObject({
  surface: "this object's `access` block",
  history:
    'Until this shape was closed, these were dropped silently — the block still parsed, so an object the ' +
    'author declared `private` shipped `public`: covered by every `\'*\'` wildcard grant, ' +
    'with no signal that the posture had been discarded.',
  aliases: {
    visibility: 'default',
    posture: 'default',
    defaultAccess: 'default',
  },
  guidance: {
    // Wrong-layer, not typos: both are real TOP-LEVEL object keys, and both
    // are the neighbouring half of the same access story — so edit distance
    // would never reach them and a bare rejection would read as "no such
    // concept" when the concept exists one level up.
    sharingModel:
      '`sharingModel` is the object-wide default record visibility (OWD) and is a ' +
      'TOP-LEVEL object key, not an `access` key — write it beside `access`, not inside ' +
      'it. `access.default` decides wildcard-GRANT coverage; `sharingModel` decides ' +
      'record visibility between users (ADR-0090).',
    requiredPermissions:
      '`requiredPermissions` is a TOP-LEVEL object key (ADR-0066 D3) — it gates access on ' +
      'the caller HOLDING a capability, which is a different axis from `access.default` ' +
      '(whether a wildcard grant covers this object at all). Pair them, side by side.',
  },
}, {
  default: z.enum(['public', 'private']).default('public')
    .describe('Default exposure posture: public (covered by wildcard grants) | private (needs explicit grant; exempt from wildcard RLS).'),
}));

/**
 * [ADR-0066 ⑤] Per-operation capability requirements for an object. Each key
 * lists the capabilities a caller must hold for that operation CLASS; an absent
 * key means that operation carries no capability gate. Lets an object be
 * "read-open / write-gated" (Salesforce & Dataverse separate capability by
 * operation) instead of the flat all-CRUD gate the `string[]` form applies.
 * Operation→class mapping mirrors the CRUD permission bits: `transfer`/`restore`
 * fold into `update`, `purge` into `delete`. `.strict()` so a mistyped key
 * (e.g. `reads`) is rejected at author time rather than silently ignored.
 *
 * ⚠️ This site is `scripts/strictness-ledger.test.ts`'s fixture for the OLDER
 * `z.object(…).strict()` spelling — the reading the ledger's AST walker has to
 * keep making, and `packages/spec` is not the only tree it reads. The fixture
 * has moved twice as the campaign converted its predecessors
 * (`security/permission.zod.ts` → `TenancyConfigSchema` at #5593 →
 * `ObjectCapabilities` at #6619 → here at #6805). If THIS one is ever
 * converted, move the fixture again rather than deleting the assertion.
 */
export const PerOperationRequiredPermissionsSchema = z.object({
  read: z.array(z.string()).optional().describe('Capabilities required to read (find/findOne/count/aggregate).'),
  create: z.array(z.string()).optional().describe('Capabilities required to create (insert).'),
  update: z.array(z.string()).optional().describe('Capabilities required to update (update/transfer/restore).'),
  delete: z.array(z.string()).optional().describe('Capabilities required to delete (delete/purge).'),
}).strict();

/**
 * [ADR-0066 D3/⑤] Object capability contract — either capabilities required for
 * ALL operations (`string[]`, the original shape) or a per-operation map
 * (narrows the gate by operation). See the field doc on `Object.requiredPermissions`.
 */
export const ObjectRequiredPermissionsSchema = z.union([
  z.array(z.string()),
  PerOperationRequiredPermissionsSchema,
]);
export type PerOperationRequiredPermissions = z.input<typeof PerOperationRequiredPermissionsSchema>;
export type ObjectRequiredPermissions = z.input<typeof ObjectRequiredPermissionsSchema>;

/**
 * Data Lifecycle (ADR-0057)
 *
 * Declares how long an object's data lives and how its space is reclaimed —
 * the axis validation/permissions never covered. Enforced at runtime by the
 * platform-owned LifecycleService (`@objectstack/objectql`): Reaper (TTL/age
 * batch delete), Rotator (time-shard + DROP oldest on SQLite, an age-based
 * reap of the same window elsewhere), Archiver (cold-store
 * copy then delete). A declared policy with no runtime consumer is a spec
 * defect (ADR-0049 enforce-or-remove); the liveness gate requires every
 * non-`record` class to declare `retention`, `ttl`, or rotation `storage`.
 */

/**
 * Lifecycle class — what persistence contract the object's data carries.
 *
 * | class       | contract                                        |
 * |-------------|-------------------------------------------------|
 * | `record`    | business truth — permanent, recoverable          |
 * | `audit`     | compliance ledger — retain → archive → delete    |
 * | `telemetry` | high-frequency log — rotation, short retention   |
 * | `transient` | ephemeral state — TTL auto-expire                |
 * | `event`     | event-bus messages — very short TTL              |
 *
 * `record` is the back-compat default: an object with no `lifecycle` block
 * behaves exactly as today (immortal data).
 */
export const LifecycleClassSchema = z.enum(['record', 'audit', 'telemetry', 'transient', 'event']);

/**
 * Duration literal: `<n><unit>` where unit is h(ours), d(ays), w(eeks) or
 * y(ears) — e.g. `'6h'`, `'14d'`, `'12w'`, `'7y'`. Parsed by
 * `@objectstack/objectql` `parseLifecycleDuration`.
 */
export const LIFECYCLE_DURATION_REGEX = /^\d+(h|d|w|y)$/;
const lifecycleDuration = (what: string) =>
  z.string().regex(LIFECYCLE_DURATION_REGEX, `${what} must be a duration literal like '6h', '14d', '12w' or '7y'`);

/**
 * [commit 801296050] The `onlyWhen` row-filter value union, shared by
 * `retention.onlyWhen` and `ttl.onlyWhen` — ONE shape on purpose: the two
 * blocks are mirrors (maintainer ruling 2026-08-20, option A: give `ttl` an
 * `onlyWhen` mirroring `retention`'s), and the runtime enforces them through
 * one code path (`LifecycleService.reap` spreads the filter into the
 * candidate-read `where` identically for both policies), so two copied unions
 * here could only ever drift apart.
 *
 * Members: per-field equality (string/number/boolean), `{$in: [...]}`
 * (non-empty), and the platform's canonical null predicate `{$null: boolean}`
 * — `$null` is declared `z.boolean()` to match `FieldOperatorsSchema`'s
 * first-class query-layer declaration exactly, never a `true`-only literal
 * that would mint a third dialect of the predicate. The absence member exists
 * because interleaved terminal rows are often supersets of live rows (a
 * `sys_session` tombstone stamps `revoked_at` and clears nothing), so the
 * only property that distinguishes a live row is a value's ABSENCE.
 * Dialect compile coverage: `driver-sql`'s
 * `sql-driver-ttl-onlywhen-null-dialects.test.ts` (SQLite live, pg + mysql2
 * compiled SQL).
 */
const lifecycleOnlyWhenSchema = z.record(
  z.string(),
  z.union([
    z.string(),
    z.number(),
    z.boolean(),
    // [#19581] `closedObject` — not `strictObject` — because the curated
    // message these two arms render is pinned as written
    // (`union-author-message-pins.test.ts`, "class B: bare `.strict()`"), and
    // routing them through the `strictObject` error map would reword it. All
    // the wrapper does is make the unknown-key refusal terminal for the arm
    // that raised it, which is what keeps this union reporting `invalid_union`
    // instead of collapsing onto whichever arm zod judged closest.
    closedObject(z.object({ $in: z.array(z.union([z.string(), z.number()])).min(1) }).strict()),
    closedObject(z.object({ $null: z.boolean() }).strict()),
  ]),
);

export const LifecycleSchema = lazySchema(() => strictObject({
  surface: "this object's `lifecycle` block",
  history:
    'Until this shape was closed, these were dropped silently — the block still parsed, so a bounding ' +
    'policy written one level too high left the object with NO policy at all. ADR-0057 ' +
    "§3.5's own refine then passed, because the key it looks for was never there.",
  aliases: { rotation: 'storage' },
  guidance: {
    // The dominant failure on this block is FLATTENING: every one of these is a
    // real key of a real sub-block, written one level too high. Edit distance
    // cannot help — the key is spelled correctly, it is just in the wrong
    // object — and the §3.5 refine makes the mistake worse than inert: a
    // flattened `maxAge` leaves `retention` absent, so a non-`record` class is
    // then rejected as unbounded and the author is told about the wrong key.
    maxAge:
      '`maxAge` belongs to the retention block, one level down: ' +
      "`retention: { maxAge: '30d' }`. Written here it is not read, and a non-`record` " +
      'class with no `retention`/`ttl`/`storage` is rejected as unbounded (ADR-0057 §3.5).',
    expireAfter:
      '`expireAfter` belongs to the TTL block, one level down: ' +
      "`ttl: { field: 'expires_at', expireAfter: '1d' }`.",
    field:
      '`field` belongs to the TTL block, one level down — it names the timestamp the TTL ' +
      "is measured from: `ttl: { field: 'expires_at', expireAfter: '1d' }`.",
    after:
      '`after` belongs to the archive block, one level down: ' +
      "`archive: { after: '7y', to: 'cold_store' }` — and ADR-0057 requires it to EQUAL " +
      '`retention.maxAge`.',
    to:
      '`to` belongs to the archive block, one level down — it names the cold-storage ' +
      "datasource: `archive: { after: '7y', to: 'cold_store' }`.",
    keep:
      '`keep` belongs to the archive block, one level down — it is how long COLD rows are ' +
      'kept. The HOT window is `retention.maxAge`.',
    strategy:
      '`strategy` belongs to the storage block, one level down: ' +
      "`storage: { strategy: 'rotation', shards: 7, unit: 'day' }`.",
    shards:
      '`shards` belongs to the storage block, one level down: ' +
      "`storage: { strategy: 'rotation', shards: 7, unit: 'day' }`.",
    unit:
      '`unit` belongs to the storage block, one level down: ' +
      "`storage: { strategy: 'rotation', shards: 7, unit: 'day' }`.",
  },
}, {
  class: LifecycleClassSchema.describe(
    'Persistence contract: record (business truth, permanent) | audit (compliance ledger) | telemetry (high-freq log) | transient (ephemeral state) | event (bus messages).',
  ),
  retention: strictObject({
    surface: "this object's `lifecycle.retention` block",
    history:
      'Until this shape was closed, these were dropped silently — the retention window still parsed, so a ' +
      'row filter written under the wrong key reaped rows the author had meant to exempt.',
    aliases: { filter: 'onlyWhen', where: 'onlyWhen', when: 'onlyWhen', age: 'maxAge' },
    guidance: {
      expireAfter:
        '`expireAfter` is a `ttl` key, not a retention key. Retention reaps by AGE from ' +
        '`created_at` (`maxAge`); TTL expires each row relative to a timestamp field you ' +
        'name (`ttl.field`). Pick the one that matches how the rows die.',
      keep:
        '`keep` is an `archive` key — how long COLD rows survive. The hot window is ' +
        '`retention.maxAge`.',
    },
  }, {
    maxAge: lifecycleDuration('retention.maxAge').describe('Rows older than this (by created_at) are deleted by the Reaper — or archived first when `archive` is set.'),
    onlyWhen: lifecycleOnlyWhenSchema.optional().describe(
      'Row filter the retention applies to — per-field equality, {$in: [...]} or the null predicate {$null: true|false} (e.g. { status: { $in: ["completed", "failed"] } }). Rows OUTSIDE the filter are retained regardless of age: for tables that interleave live workflow state with terminal history (sys_automation_run). Incompatible with rotation storage and archive, which act on whole shards / age alone.',
    ),
  }).optional().describe('Age-based retention window enforced by the LifecycleService Reaper.'),
  ttl: strictObject({
    surface: "this object's `lifecycle.ttl` block",
    history:
      'Until this shape was closed, these were dropped silently — the TTL block still parsed, so rows the ' +
      'author expected to auto-expire lived forever.',
    aliases: { expiresAfter: 'expireAfter', after: 'expireAfter', timestampField: 'field', on: 'field', filter: 'onlyWhen', where: 'onlyWhen', when: 'onlyWhen' },
    guidance: {
      maxAge:
        '`maxAge` is a `retention` key, not a TTL key. TTL measures from the timestamp ' +
        'field named in `ttl.field`; retention measures AGE from `created_at`. For ' +
        "age-based reaping write `retention: { maxAge: '30d' }` instead.",
    },
  }, {
    field: z.string().describe('Timestamp field the TTL is measured from (e.g. created_at, expires_at).'),
    expireAfter: lifecycleDuration('ttl.expireAfter').describe('Rows expire this long after `field` and are deleted by the Reaper.'),
    onlyWhen: lifecycleOnlyWhenSchema.optional().describe(
      'Row filter the TTL reap applies to — per-field equality, {$in: [...]} or the null predicate {$null: true|false} (e.g. { revoked_at: { $null: true } }). Rows OUTSIDE the filter are retained regardless of expiry: for tables that interleave live rows with terminal history a TTL keyed on the same timestamp would otherwise destroy (a sys_session audit tombstone backdates expires_at, so a naive TTL reaps tombstones first). Incompatible with rotation storage, which DROPs whole shards, and with archive, which selects rows by the ttl cutoff alone and does not apply this filter.',
    ),
  }).optional().describe('Per-row TTL auto-expiry (transient/event classes).'),
  storage: strictObject({
    surface: "this object's `lifecycle.storage` block",
    history:
      'Until this shape was closed, these were dropped silently — the rotation block still parsed, so a ' +
      'telemetry table declared as rotating kept every shard it ever cut.',
    aliases: { count: 'shards', interval: 'unit', period: 'unit', granularity: 'unit' },
    guidance: {
      maxAge:
        '`maxAge` is a `retention` key. Rotation takes its window from `shards` × `unit`, ' +
        'not from an age you name — reclaimed by DROPping the oldest shard whole on SQLite, ' +
        'by an equivalent age-based reap elsewhere. Set the window ' +
        'with `shards`/`unit`, or use `retention` instead of rotation.',
    },
  }, {
    strategy: z.literal('rotation').describe(
      'Time-shard the table. The retained window (`shards` × `unit`) is the same on every ' +
      'dialect; the reclamation is not — SQLite DROPs the oldest shard whole (O(1) reclaim), ' +
      'other dialects reap that same window by age from `created_at`.',
    ),
    shards: z.number().int().min(2).describe('Number of shards retained; total window = shards × unit.'),
    unit: z.enum(['day', 'week', 'month']).describe('Time width of one shard.'),
  }).optional().describe('Physical storage strategy for high-frequency telemetry (LifecycleService Rotator).'),
  archive: strictObject({
    surface: "this object's `lifecycle.archive` block",
    history:
      'Until this shape was closed, these were dropped silently — the archive block still parsed, so audit ' +
      'rows were reaped hot with no cold copy ever written.',
    aliases: { datasource: 'to', target: 'to', destination: 'to', retain: 'keep' },
    guidance: {
      maxAge:
        '`maxAge` is a `retention` key. The archive boundary is `archive.after`, and ' +
        'ADR-0057 requires the two to be EQUAL — the hot window ends exactly where the ' +
        'archive begins, so declare `retention.maxAge` and `archive.after` with the same value.',
    },
  }, {
    after: lifecycleDuration('archive.after').describe('Rows older than this are copied to the archive datasource before hot deletion.'),
    to: z.string().describe('Target datasource name for cold storage. When it is not registered, the Archiver skips (audit rows are then retained, never dropped unarchived).'),
    keep: lifecycleDuration('archive.keep').optional().describe('How long archived rows are kept in cold storage (undefined = forever).'),
  }).optional().describe('Cold-store archival (LifecycleService Archiver) — audit-class hot→cold hand-off.'),
  reclaim: z.boolean().optional().describe('Run driver space reclamation (SQLite incremental_vacuum) after sweeping this object. Default true for non-record classes.'),
}).superRefine((lc, ctx) => {
  // ADR-0057 §3.5: a non-`record` lifecycle class with no bounding policy is a
  // false surface — the object would still grow forever. Enforce-or-remove.
  if (lc.class !== 'record' && !lc.retention && !lc.ttl && !lc.storage) {
    ctx.addIssue({
      code: z.ZodIssueCode.custom,
      message: `lifecycle.class '${lc.class}' requires at least one bounding policy: retention, ttl, or storage (rotation) — ADR-0057 §3.5`,
    });
  }
  if (lc.class === 'record' && (lc.retention || lc.ttl || lc.storage || lc.archive)) {
    ctx.addIssue({
      code: z.ZodIssueCode.custom,
      message: `lifecycle.class 'record' is permanent business truth — retention/ttl/storage/archive policies are not allowed on it (ADR-0057 §3.1)`,
    });
  }
  if (lc.archive && lc.retention && lc.archive.after !== lc.retention.maxAge) {
    ctx.addIssue({
      code: z.ZodIssueCode.custom,
      message: `lifecycle.archive.after ('${lc.archive.after}') must equal retention.maxAge ('${lc.retention.maxAge}') — the hot window ends where the archive begins`,
    });
  }
  // [commit 5649efbf9] The retention + ttl + archive triple — the alignment above, one
  // policy wider. Since [commit 530c1df65] the Archiver selects the rows it moves by the
  // ttl cutoff (`ttl.field` older than `ttl.expireAfter`) whenever `ttl` is
  // declared, and by `created_at`/`archive.after` only when it is not — so on
  // this triple the age bound (`retention.maxAge`, pinned equal to
  // `archive.after` above) no longer separately bounds the hot store: a row
  // whose `ttl.field` sits in the future stays hot past `retention.maxAge`,
  // silently. One declared bound nothing enforces is exactly the class this
  // block refuses loudly (ADR-0049 declared ≠ enforced), so the triple parses
  // only when the ttl restates the age bound — same clock (`created_at`), same
  // window — and any divergence is refused here, at authoring time, rather
  // than resolved by whichever column the sweep happens to read.
  if (lc.retention && lc.ttl && lc.archive
      && (lc.ttl.field !== 'created_at' || lc.ttl.expireAfter !== lc.retention.maxAge)) {
    ctx.addIssue({
      code: z.ZodIssueCode.custom,
      message: `lifecycle.ttl ('${lc.ttl.expireAfter}' after '${lc.ttl.field}') must restate retention.maxAge ('${lc.retention.maxAge}' after created_at) when retention, ttl and archive are all declared — the Archiver moves rows by the ttl cutoff when ttl is declared, so a diverging age bound no longer bounds the hot store; align ttl to { field: 'created_at', expireAfter: '${lc.retention.maxAge}' } or drop retention or ttl`,
    });
  }
  if (lc.retention?.onlyWhen && lc.storage?.strategy === 'rotation') {
    ctx.addIssue({
      code: z.ZodIssueCode.custom,
      message: 'lifecycle.retention.onlyWhen cannot be combined with rotation storage — the Rotator DROPs whole shards and would destroy rows the filter protects',
    });
  }
  if (lc.retention?.onlyWhen && lc.archive) {
    ctx.addIssue({
      code: z.ZodIssueCode.custom,
      message: 'lifecycle.retention.onlyWhen cannot be combined with archive — the Archiver moves rows by age alone and would archive rows the filter protects',
    });
  }
  // [commit 801296050] ttl.onlyWhen mirrors both of retention.onlyWhen's conflicts, from
  // the Reaper's actual semantics rather than by symmetry alone:
  // - rotation: the Rotator DROPs whole physical shards; a shard is dropped by
  //   age with no row read, so rows the filter protects go down with it.
  // - archive: `reapObject` returns into `archiveObject` before the ttl reap
  //   ever runs, so with `archive` declared the filter guards a code path that
  //   is never executed (declared ≠ enforced). Since [commit 530c1df65] the Archiver does
  //   apply the declared ttl window itself — it selects candidates by
  //   `ttl.field` past `ttl.expireAfter` instead of `created_at` past
  //   `archive.after` — but its candidate read is that cutoff and nothing else
  //   (`where: { [ttl.field]: { $lt: cutoff } }`, no `onlyWhen` spread the way
  //   `reap()` spreads it into its scope), so every due row is copied and
  //   hot-deleted whether or not the filter names it. That is the whole of what
  //   [commit 530c1df65] changed here: the WINDOW an author declares now carries over to
  //   the Archiver, the FILTER still does not — so the refusal stands, on a
  //   narrower reason than the "moves rows by age alone" this bullet used to
  //   give. Whether `onlyWhen` should become meaningful under `archive` (the
  //   Archiver would have to spread it into the `find` above) is a separate,
  //   un-taken decision — it widens the accept-set and is not this text's to
  //   make.
  if (lc.ttl?.onlyWhen && lc.storage?.strategy === 'rotation') {
    ctx.addIssue({
      code: z.ZodIssueCode.custom,
      message: 'lifecycle.ttl.onlyWhen cannot be combined with rotation storage — the Rotator DROPs whole shards and would destroy rows the filter protects',
    });
  }
  if (lc.ttl?.onlyWhen && lc.archive) {
    ctx.addIssue({
      code: z.ZodIssueCode.custom,
      message: 'lifecycle.ttl.onlyWhen cannot be combined with archive — archive takes over the whole reap (the ttl sweep never runs), and while the Archiver does move rows by the declared ttl cutoff it selects them by that cutoff alone and would archive rows the filter protects',
    });
  }
}));

/**
 * Object Field Group Schema — MVP (data-layer protocol)
 * 
 * Declares the set of logical field groups for an object. A group bundles
 * related fields together for presentation in forms, detail pages, and
 * editors (e.g., "Contact Info", "Billing", "System").
 * 
 * Design rules (MVP):
 * - Group **order** is the declaration order of this array — no `order` property.
 * - Field → group mapping is derived automatically from `Field.group`
 *   matching `ObjectFieldGroup.key`; the **in-group display order** equals
 *   the traversal order of `ObjectSchema.fields`.
 * - Fields whose `group` is unset (or references an undeclared key) are
 *   considered ungrouped and must be rendered by consumers in a default
 *   bucket after the declared groups, preserving their field declaration order.
 * - Extension packages and runtime code use `Field.group` to assign fields
 *   to an existing group — no per-field order property is introduced at this
 *   layer.
 * 
 * Migration operations supported by this MVP:
 *   - add / rename / delete / reorder groups (via the array)
 *   - assign an existing field to a group (via `Field.group`)
 * 
 * Deferred (not part of MVP):
 *   - explicit per-field in-group ordering
 *   - nested groups / sub-groups
 *
 * Group-level visibility (`visibleWhen`) closed the ADR-0049 enforce-or-remove
 * loop in BOTH directions: a predicate slot existed here briefly with no
 * consumer on any surface and was REMOVED per ADR-0085 / ADR-0049; it is
 * re-declared now that the form renderer's section-gating contract actually
 * evaluates a section predicate (the whole group — header included — hides
 * when it is FALSE), so declared = enforced held on day one both times.
 *
 * Derivation semantics (declared order, empty groups dropped, ungrouped
 * trailing bucket, collapse + visibleWhen passthrough) are single-sourced in
 * `deriveFieldGroupLayout` (field-group-layout.ts, ADR-0085 §5) — UI
 * renderers consume that helper instead of re-implementing the rules.
 *
 * @example
 * ```ts
 * fieldGroups: [
 *   { key: 'contact_info', label: 'Contact Information', icon: 'user' },
 *   { key: 'billing',      label: 'Billing',             collapse: 'collapsed' },
 *   { key: 'system',       label: 'System' },
 * ]
 * ```
 */
export const ObjectFieldGroupSchema = lazySchema(() => strictObject({
  surface: 'this field group',
  history:
    'Until this shape was closed, these were dropped silently — the group still parsed AND still rendered, ' +
    'which is the worst version of the failure: the section appeared, so the author had ' +
    'every reason to believe the setting they wrote had been applied.',
  aliases: {
    title: 'label',
    name: 'key',
    id: 'key',
    help: 'description',
    helpText: 'description',
  },
  guidance: {
    // Membership is declared the OTHER WAY ROUND, and this is the single most
    // likely thing an author reaches for here — a group that lists its fields
    // is what every other layout system in this space looks like.
    fields:
      '`fields` does not live on a group — membership is declared on the FIELD, pointing ' +
      "back: `fields: { email: { type: 'email', group: 'contact_info' } }`. The group " +
      'declares only its `key`, `label` and presentation; `deriveFieldGroupLayout` ' +
      '(ADR-0085 §5) does the assembly.',
    order:
      '`order` is not a group key — ARRAY ORDER is display order. `fieldGroups: [...]` ' +
      'renders top to bottom, so move the entry rather than numbering it.',
    expanded:
      '`expanded` is not a group key — use the `collapse` enum: ' +
      "`collapse: 'expanded'` (collapsible, starts open), `'collapsed'` (starts closed), " +
      "or `'none'` (always open, no toggle).",
    visibleOn:
      '`visibleOn` is not a field-group key — the section predicate slot is `visibleWhen` ' +
      '(ADR-0089 canonical spelling; re-added with its enforcement under ADR-0085 §5). ' +
      'Write `visibleWhen: <CEL>` — FALSE hides the whole group, header included.',
  },
}, {
  /**
   * Group key — referenced by `Field.group` to assign a field to this group,
   * and (since #13855) by a layout section's `group` to inherit the whole
   * group. Must be snake_case; the grammar is single-sourced as
   * `FIELD_GROUP_KEY_PATTERN` beside the derivation it belongs to, so the
   * declaring surface and the referencing surfaces cannot drift apart.
   */
  key: z.string().regex(FIELD_GROUP_KEY_PATTERN, {
    message: 'Field group key must be lowercase snake_case (e.g., "contact_info", "billing", "system")',
  }).describe('Group machine key (snake_case). Referenced by Field.group, and by a layout section\'s `group`.').meta({ title: 'Key' }),

  /** Human-readable label displayed as the group header. */
  label: z.string().describe('Group display label').meta({ title: 'Label' }),

  /** Optional Lucide/Material icon name for the group header. */
  icon: z.string().optional().describe('Icon name (Lucide/Material) for the group header').meta({ title: 'Icon' }),

  /** Optional description / help text shown under the group header. */
  description: z.string().optional().describe('Optional description shown under the group header').meta({ title: 'Description' }),

  /**
   * [ADR-0085 §5] Section visibility predicate — CEL, the ADR-0089 canonical
   * spelling shared with field/action predicates. Evaluated by the form
   * renderer's section-gating contract against the record in scope: FALSE (or
   * a faulting predicate — fail-closed) hides the WHOLE group, header
   * included; TRUE (or absent) shows it. `deriveFieldGroupLayout` passes it
   * through to the derived section verbatim.
   *
   * History (ADR-0049 enforce-or-remove, both directions): the slot was
   * removed while nothing on any surface evaluated it, and re-declared
   * together with its enforcement once the section-gating consumer shipped —
   * declared = enforced on day one, both times.
   */
  visibleWhen: EvaluatedExpressionInputSchema.optional().describe(
    "Section visibility predicate (CEL) — the whole group (header included) is shown only when TRUE, else hidden (fail-closed). e.g. P`record.type == 'invoice'`",
  ).meta({ title: 'Visible When' }),

  /**
   * [ADR-0085] Collapse behaviour of the group's rendered section, on every
   * surface (form, detail, drawer). One enum, three valid states — replaces
   * the old `defaultExpanded` flag AND the UI-dialect `collapsible`/`collapsed`
   * boolean pair, which could express contradictions and had drifted between
   * spec and renderer (spec declared a key no renderer read; renderers read
   * keys the spec rejected).
   */
  collapse: z.enum(['none', 'expanded', 'collapsed']).optional().default('none')
    .describe("[ADR-0085] Section collapse behaviour: 'none' (always open, no toggle), 'expanded' (collapsible, starts open), 'collapsed' (collapsible, starts closed).").meta({ title: 'Collapse' }),

  /**
   * @deprecated [ADR-0085 → `collapse`] Accepted as a parse-time alias:
   * `defaultExpanded: false` maps to `collapse: 'collapsed'`, `true` to
   * `'expanded'`, when `collapse` is absent. New metadata sets `collapse`.
   */
  defaultExpanded: z.boolean().optional().describe("[DEPRECATED → collapse] true → 'expanded', false → 'collapsed'.").meta({ title: 'Default Expanded' }),
  /** @deprecated [ADR-0085 → `collapse`] UI-dialect alias (pair with `collapsed`); mapped onto `collapse` at parse. */
  collapsible: z.boolean().optional().describe("[DEPRECATED → collapse] Boolean pair with `collapsed`; use the `collapse` enum.").meta({ title: 'Collapsible' }),
  /** @deprecated [ADR-0085 → `collapse`] UI-dialect alias (pair with `collapsible`); mapped onto `collapse` at parse. */
  collapsed: z.boolean().optional().describe("[DEPRECATED → collapse] true → 'collapsed' (collapsible, starts closed) on its own — it needs no `collapsible` and outranks `collapsible: false`; false → 'none', or 'expanded' beside `collapsible: true`. Use the `collapse` enum.").meta({ title: 'Collapsed' }),
}));

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

/**
 * Base Object Schema Definition
 * 
 * The Blueprint of a Business Object.
 * Represents a table, a collection, or a virtual entity.
 * 
 * @example
 * ```yaml
 * name: project_task
 * label: Project Task
 * icon: task
 * fields:
 *   project:
 *     type: lookup
 *     reference: project
 *   status:
 *     type: select
 *     options: [todo, in_progress, done]
 * enable:
 *   trackHistory: true
 *   files: true
 * ```
 */

/**
 * External Binding (ADR-0015)
 *
 * Optional per-object descriptor that binds this object to a remote table
 * on a federated datasource (one whose `schemaMode !== 'managed'`). When
 * present, the object is "external": DDL is forbidden, the table is
 * validated against the remote schema at boot, and writes require a double
 * opt-in (`datasource.external.allowWrites` **and** this `writable`).
 *
 * The cross-field invariant ("`external` only when the object's datasource
 * has `schemaMode !== 'managed'`") is enforced at metadata-load time, not
 * in this schema, because the datasource may live in another artefact.
 */
export const ObjectExternalBindingSchema = strictObject({
  surface: "this object's `external` binding (ADR-0015)",
  history:
    'Until this shape was closed, these were dropped silently — the binding still parsed, so a federated ' +
    'object bound to the wrong remote table, or shipped read-only after the author had ' +
    'explicitly asked for writes.',
  aliases: {
    table: 'remoteName',
    tableName: 'remoteName',
    remoteTable: 'remoteName',
    schema: 'remoteSchema',
    columns: 'columnMap',
    skipColumns: 'ignoreColumns',
    excludeColumns: 'ignoreColumns',
  },
  guidance: {
    // The mirror image of `datasource.zod.ts`'s own `writable → allowWrites`
    // alias. ADR-0015 makes writes a DOUBLE opt-in, so the two spellings are
    // both correct — each on the other layer — and an author who learned one
    // will write it here. Getting this wrong fails open-looking: the object
    // stays read-only and nothing says why.
    allowWrites:
      '`allowWrites` is the DATASOURCE-level gate (`datasource.external.allowWrites`). ' +
      'The per-object opt-in is spelled `writable: true`. ADR-0015 requires BOTH — set ' +
      '`writable` here and `allowWrites` on the datasource; either one alone leaves the ' +
      'object read-only.',
    schemaMode:
      '`schemaMode` is a DATASOURCE key, not an object key — an object becomes external ' +
      "by being routed to a datasource whose `schemaMode !== 'managed'`. This block only " +
      'describes the remote binding once that is true.',
  },
}, {
  remoteName: z.string().optional()
    .describe('Remote table/view name. Defaults to object.name.'),
  remoteSchema: z.string().optional()
    .describe('Remote schema/database qualifier.'),
  writable: z.boolean().default(false)
    .describe('Per-object write opt-in (also requires datasource.external.allowWrites).'),
  columnMap: z.record(z.string(), z.string()).optional()
    .describe('Remote column name → local field name.'),
  introspectedAt: z.string().datetime().optional()
    .describe('Set by `os datasource introspect`; informational.'),
  ignoreColumns: z.array(z.string()).optional()
    .describe('Remote columns to skip during validation (dev convenience).'),
}).describe('External datasource binding (ADR-0015)');

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

/**
 * Object form of a `userActions` CRUD override — extends the plain boolean
 * with CEL predicates so a built-in affordance can be hidden or disabled
 * against record state rather than only per object
 * (objectstack-ai/objectui#2614).
 *
 * Semantics (mirrors custom actions' `visible` / `disabled`):
 * - `enabled`      — object-level on/off, same meaning as the bare boolean.
 *                    Omitted → the `managedBy` bucket default.
 * - `visibleWhen`  — CEL over `record.*`; evaluates **false** → the button
 *                    is not rendered. Fail-closed (a faulting predicate
 *                    hides, and warns once).
 * - `disabledWhen` — CEL over `record.*`; evaluates **true** → the button
 *                    renders greyed / non-clickable. Fail-soft (a faulting
 *                    predicate leaves the button enabled).
 *
 * The predicates are advisory UI gating only — server-side enforcement
 * stays with permissions / hooks (e.g. `beforeUpdate` rejecting frozen
 * rows). Evaluation happens on the canonical CEL engine, with the record
 * bound as `record.*` (and bare fields) — the same machinery custom actions
 * already use, so authoring is identical.
 *
 * **What `record.*` binds to depends on where the affordance renders, and
 * the two cases are not the same fact** (#7692):
 * - Row affordances (`edit`, `delete`) evaluate **per row**, against that
 *   row's own record. This is the original #2614 case and the reason for
 *   the `RowCrud` name, kept for export compatibility.
 * - Toolbar affordances (`create`, `import`) have no row to bind — the
 *   record they gate does not exist yet. They evaluate **once per toolbar**
 *   against the record in scope where the toolbar renders: on a record
 *   page's related list that is the **host (parent) record**. On a
 *   standalone object list there is no record in scope, so a predicate
 *   reading `record.*` has nothing to bind and — per the fail-closed rule
 *   above — hides the button. Gate a toolbar action on parent state only
 *   where a parent is actually in scope; anything else the child row must
 *   carry itself (the denormalised parent-status snapshot pattern that
 *   `edit`/`delete` already use).
 */
export const RowCrudActionOverrideSchema = strictObject({
  surface: 'this row CRUD override',
  // Closed from birth (objectui#2614), so nothing was ever silently stripped
  // here — but the rejection was zod's own bare `Unrecognized key: "visible"`,
  // which names neither the surface nor a key to write instead. #7832.
  history:
    'This shape has been closed, so the key was never silently dropped — '
    + 'until this shape was closed, the rejection just could not tell you which key to write instead.',
  aliases: {
    // `showWhen` carries no boolean reading: whatever surface an author borrowed
    // it from, they meant a predicate, and the predicate slot here is
    // `visibleWhen`. The two keys that DO have both readings are answered by
    // `guidance` below rather than renamed, because a rename has to pick one.
    showWhen: 'visibleWhen',
  },
  guidance: {
    // The near-misses on this surface all arrive from custom row actions
    // (`actions[].visible` / `.disabled`), where ONE key takes either a boolean
    // or a CEL string. This shape splits that pair in two — `enabled` for the
    // object-level switch, `*When` for the per-record predicate — so a rename
    // cannot answer either key without guessing which form the author meant,
    // and guessing wrong just relocates the confusion (#7816's own note: point
    // the boolean reading at `enabled`, not at `visibleWhen`).
    visible:
      '`visible` is the CUSTOM row-action spelling (`actions[].visible`), where one key takes '
      + 'either form. This override splits them: write `enabled: false` for the object-level '
      + 'on/off, or `visibleWhen: <CEL over record.*>` for a per-record predicate (FALSE hides '
      + 'that row\'s button).',
    disabled:
      '`disabled` is the CUSTOM row-action spelling (`actions[].disabled`). The per-record form '
      + 'here is `disabledWhen: <CEL over record.*>` (TRUE renders that row\'s button disabled); '
      + 'there is no boolean `disabled` — switch the affordance off with `enabled: false`.',
  },
}, {
  enabled: z.boolean().optional().describe(
    'Object-level on/off for the generic affordance; same meaning as the bare boolean form. Omitted → managedBy bucket default.',
  ),
  visibleWhen: EvaluatedExpressionInputSchema.optional().describe(
    'CEL predicate over the record in scope (row record for edit/delete, host record for a related-list create/import toolbar); false → hide the button. Fail-closed.',
  ),
  disabledWhen: EvaluatedExpressionInputSchema.optional().describe(
    'CEL predicate over the record in scope (row record for edit/delete, host record for a related-list create/import toolbar); true → render the button disabled. Fail-soft.',
  ),
}).describe('Boolean-or-predicates override for a built-in CRUD affordance.');
export type RowCrudActionOverride = z.input<typeof RowCrudActionOverrideSchema>;
/** Post-parse shape of {@link RowCrudActionOverride} — defaults applied, transforms run (ADR-0122). */
export type RowCrudActionOverrideParsed = z.infer<typeof RowCrudActionOverrideSchema>;

/*
 * ── Unknown-key strictness (#4001 registered-types line) ────────────────────
 *
 * `.strict()` HERE, not only in `create()`. #1535 built the unknown-key guard
 * as a hand-rolled check inside the `create()` factory, on the reasoning that
 * "authored `*.object.ts` modules call `create()`". They do — but they are not
 * the only producer, and they are not the path most instances travel:
 * `defineStack({ objects })`, `/api/v1/meta/types/object` and the Studio form
 * all reach this schema through `parse()` / `safeParse()`, which stripped
 * unknown keys in silence for the whole time #1535 was considered fixed. The
 * founding example of #4001 — object-level `workflows: [...]` believed to wire
 * up automation, silently discarded — was still reproducible on `parse()`.
 *
 * `create()` is unaffected: its own check runs BEFORE parsing and throws a
 * richer located Error, so its message still wins where it applies.
 *
 * Safe on the read path for the same reason the other closed registered types
 * are: the ADR-0010 envelope is declared below, and `stripReadDecorations`
 * removes `_diagnostics` / `_draft` before any strict re-parse (cloud#971).
 * Verified empirically rather than assumed — every `ObjectSchema.create()` call
 * across `platform-objects` and the three example apps uses only declared
 * top-level keys.
 */
/**
 * Prescription for the retired `managedBy: 'system'` bucket (#3355, the v17
 * close-out of ADR-0103's v16 split).
 *
 * ADR-0103 split the overloaded `system` bucket ADDITIVELY: the 20 engine-owned
 * objects moved to the new explicit `engine-owned`, and the 8 admin/user-writable
 * ones stayed behind on `system`. That left the name pointing at the half it no
 * longer described — "system" on precisely the objects a user writes — which is
 * the kind of residual overload an author (especially a model author) resolves by
 * guessing. v17 finishes the split by renaming the residue to `system-data` and
 * retiring the bare value.
 *
 * Because v16 already drained the engine side, `system` → `system-data` is a
 * ONE-TO-ONE mechanical replacement: there is no judgement call in the upgrade,
 * which is why the message can prescribe a single answer.
 */
const MANAGED_BY_SYSTEM_RETIRED =
  "`object.managedBy: 'system'` was removed in @objectstack/spec 17 (ADR-0103 v17 "
  + 'addendum) — v16 moved every engine-owned object to `engine-owned`, leaving `system` '
  + 'labelling admin/user-writable platform DATA under a name that says the opposite. '
  + "Use `managedBy: 'system-data'` (platform-defined schema, admin/user-writable data; "
  + 'authz stays the DelegatedAdminGate / RLS / permission sets). Rename the value; nothing '
  + 'else about the object changes. Note `system-data` defaults to WRITABLE affordances — '
  + 'create, edit, delete and exportCsv (the old `system` default was locked) — so a '
  + '`userActions` block that existed only to re-open create/edit/delete is now redundant '
  + 'and can be deleted; keep it only to NARROW. CSV `import` is deliberately NOT in that '
  + 'default: it stays opt-in per object via `userActions: { import: true }`, which '
  + 'is what a v16 `system` object already resolved to. '
  + 'Run `os migrate meta --from 16` to list the mechanical edits for existing sources; `--write` applies the ones it can prove, and you apply the rest by hand.';

/**
 * Known-confusable schema keys → precise authoring guidance.
 *
 * ADR-0032's "no silent failure" principle applied to metadata *shape*: an
 * unknown top-level key on `ObjectSchema.create()` used to be discarded by
 * Zod's default `.strip()`, so a misauthored schema key vanished with no
 * error, no warning, and a green `tsc` — shipping dead metadata the author
 * believed they had wired up (issue #1535, object-level `workflows: [...]`).
 *
 * These entries turn the most likely mistakes into a fixable error that points
 * at the *supported* mechanism rather than a generic "unknown key".
 */
const UNKNOWN_KEY_GUIDANCE: Record<string, string> = {
  workflows:
    '`workflows` is not an ObjectSchema field. Object-level, record-triggered ' +
    'automation is authored as a lifecycle hook (`src/objects/<name>.hook.ts`, ' +
    'wrapped in `defineHook()` from `@objectstack/spec/data`) or as a top-level ' +
    '`record_change` flow — not as `workflows[]` on the object schema.',
  workflow:
    '`workflow` is not an ObjectSchema field. Record-triggered automation is ' +
    'authored as a lifecycle hook (`src/objects/<name>.hook.ts`) or a top-level ' +
    '`record_change` flow.',
  hooks:
    '`hooks` is not an ObjectSchema field. Lifecycle hooks live in their own ' +
    '`src/objects/<name>.hook.ts` module, wrapped in `defineHook()` from ' +
    '`@objectstack/spec/data`.',
  triggers:
    '`triggers` is not an ObjectSchema field. Use a lifecycle hook ' +
    '(`src/objects/<name>.hook.ts`) or a top-level `record_change` flow.',

  // ── Tombstones for RETIRED keys (upgrade prescriptions) ────────────────
  // A retired key's error must carry the fix: the compile/validation error is
  // the one upgrade channel every consumer is guaranteed to hit — an agent
  // bumping @objectstack/spec sees THIS message, not our docs site. Each entry
  // names what replaced the key and the version/decision that removed it.
  // Tombstones age out too: drop an entry ~two majors after the removal
  // (by then it's archaeology, not an upgrade; see CHANGELOG.md for history).
  namespace:
    '`namespace` was retired (ADR-0129 D3) — the object `name` IS the canonical id ' +
    'everywhere (API, ObjectQL, REST, SDK, DB table), so there is no separate namespace ' +
    'to declare. Embed the module prefix in the name instead: `namespace: "sys", ' +
    'name: "user"` becomes `name: "sys_user"`. Until this shape was closed on the ' +
    'parse path it was stripped in silence, so an object declaring one shipped under ' +
    'the unprefixed name its author did not intend.',
  compactLayout:
    '`compactLayout` was renamed to `highlightFields` in @objectstack/spec 11.7.0 ' +
    '(ADR-0085 semantic roles) and the alias was retired in 11.9.1. ' +
    'Rename the key — the value shape (ordered field-name list) is unchanged.',
  detail:
    'The `detail` UI-hints block was removed by ADR-0085 (spec 11.7.0). Its ' +
    'jobs moved to top-level semantic roles: `detail.stageField` → `stageField` ' +
    '(string | false), `detail.highlightFields` → `highlightFields`, section ' +
    'layout → `fieldGroups` + `Field.group`. Whole-page customization is done ' +
    'by assigning a custom Page schema instead of per-page hint keys.',
  views:
    '`views` is not an ObjectSchema field: the object-level `views.form/*` and ' +
    '`views.detail/*` UI-hint dialect was never part of the spec and its ' +
    'renderer support was removed (ADR-0085). Use the semantic roles ' +
    '(`highlightFields`, `stageField`, `fieldGroups`) for hints and `listViews` ' +
    'for named list views.',
  defaultDetailForm:
    '`defaultDetailForm` was never implemented and was removed from the spec' +
    '. Curate the record page by assigning a custom Page schema; form ' +
    'layout derives from `fieldGroups` + `Field.group`.',
  softDelete:
    '`softDelete` was removed from the spec in 16.0 (ADR-0049 ' +
    'enforce-or-remove) — there is no soft-delete/recycle-bin runtime, so it ' +
    'stored nothing and implied restore semantics that do not exist. Deletes ' +
    'are hard deletes; remove the key.',
  versioning:
    '`versioning` was removed from the spec in 16.0 (ADR-0049) — no ' +
    'record-versioning engine ever read it (it snapshotted no history). Use ' +
    'per-field `Field.trackHistory` for field-level history, or a data ' +
    'lifecycle policy (`lifecycle`) for retention.',
  search:
    '`search` (the SearchConfig block) was removed from the spec in 16.0 ' +
    '(ADR-0049) — no search-engine config was consumed. Declare the ' +
    'indexed fields with `searchableFields` (ADR-0061); records stay queryable ' +
    'via the normal data API regardless.',
  recordName:
    '`recordName` was removed from the spec in 16.0 (ADR-0049) — it was ' +
    'never read. Auto-naming is modelled as a `Field` of type \'autonumber\' ' +
    '(with `autonumberFormat`) designated as the object\'s `nameField`.',
  keyPrefix:
    '`keyPrefix` was removed from the spec in 16.0 (ADR-0049) — record ' +
    'ids are not prefixed from it (no Salesforce-style key-prefix runtime). ' +
    'Remove the key; it had no effect.',
  tags:
    '`tags` (object-level categorization) was removed from the spec (' +
    'ADR-0049) — it had no runtime reader. Remove the key; use `managedBy` for ' +
    'lifecycle bucketing or a real field for per-record tagging.',
  active:
    '`active` was removed from the spec (ADR-0049) — no runtime reader ' +
    'gated on it, so an "inactive" object was still fully queryable and usable. ' +
    'Remove the key; gate availability with permissions/sharing instead.',
  abstract:
    '`abstract` was removed from the spec (ADR-0049) — object ' +
    'inheritance/abstraction is not implemented, so an abstract object still ' +
    'got a table and was instantiable. Remove the key.',
};

/**
 * [#14892 — maintainer ruling 2026-09-05, option A] A `tree` field's
 * `reference`, when present, must name the object that declares it.
 *
 * A hierarchy is parent/child WITHIN one object, and that is what every reader
 * of the type assumes: the tree renderer's parent-pointer auto-detection takes
 * the first `type: 'tree'` field as this object's own parent column, and
 * `deleteBehavior` materialises on `tree` beside `lookup` because a
 * self-referential hierarchy is a relation whose cascade is exactly the
 * intended semantics. `reference` stays OPTIONAL on a `tree` — under this rule
 * it is a redundant self-annotation — so absence is accepted; a value naming
 * any OTHER object is refused here, where the declaring object's name is known
 * (`FieldSchema` never sees it), rather than parsing green and rendering as a
 * parent pointer into a table it does not point at. A link to a different
 * object is a `lookup`. Applied at both doors that carry a field map —
 * `ObjectSchema` (own name = `name`) and `ObjectExtensionSchema` (own name =
 * `extend`) — so an extension cannot merge the shape the object refuses.
 * Pinned in `tree-reference-self-only.test.ts`; the kernel predicate that
 * reads the same rule is `hasDetectableParentField`
 * (`kernel/functional-completeness.ts`).
 */
function refuseForeignTreeReference(ownName: unknown, fields: unknown, ctx: z.RefinementCtx): void {
  if (typeof ownName !== 'string' || fields === null || typeof fields !== 'object') return;
  for (const [fieldName, def] of Object.entries(fields as Record<string, unknown>)) {
    if (def === null || typeof def !== 'object') continue;
    const { type, reference } = def as { type?: unknown; reference?: unknown };
    if (type !== 'tree' || reference === undefined || reference === ownName) continue;
    ctx.addIssue({
      code: 'custom',
      path: ['fields', fieldName, 'reference'],
      message:
        `tree field \`${fieldName}\` on object \`${ownName}\` references \`${String(reference)}\`, `
        + 'but a `tree` field\'s `reference` must name the declaring object itself — a hierarchy is '
        + 'parent/child within one object. Drop `reference` (it is optional on a `tree`), set it to '
        + `'${ownName}', or declare a \`lookup\` if a link to a different object was meant.`,
    });
  }
}

/**
 * The field types an object's `imageField` may name: the two whose stored
 * value IS a picture. One list, read by the refusal below and spelled into its
 * prescription, so the accepted set and the text that names it cannot drift.
 */
const IMAGE_FIELD_TYPES: readonly FieldType[] = ['image', 'avatar'];

/**
 * [#21182 — ruling A on objectstack-ai/hotcrm#1199] `imageField`, when
 * present, must name a field THIS object declares whose type is `image` or
 * `avatar`.
 *
 * Judged here for the reason {@link refuseForeignTreeReference} is: only the
 * object holds the field map the pointer resolves against, and every authoring
 * door parses through this schema — `defineStack({ objects })` binds it
 * element-wise (`ObjectSchema.create()` runs the same parse), `os validate`
 * parses the stack through `ObjectStackDefinitionSchema`, and the metadata
 * save door resolves the `object` type to this schema
 * (`getMetadataTypeSchema('object')`). So a bad pointer is refused loudly at
 * authoring and at publish alike, and no reader of the key ever needs a
 * tolerance for one (Prime Directive #12).
 *
 * Two refusals, each one located issue at `['imageField']`:
 *
 *  - the name is not a key of `fields` — a pointer into nothing;
 *  - the name resolves, and the field is any type but `image` / `avatar` — a
 *    `text` URL column or a `file` attachment is not a declared picture, and a
 *    renderer that guessed it was would be the consumer-side tolerance this
 *    rule exists to make unnecessary.
 *
 * Judged against the AUTHORED field map only. No registry-injected system
 * column is an `image` or `avatar` field, so widening the existence half to
 * the injected set (the #5378 move the semantic-role lints make) could only
 * turn "not declared" into "wrong type" for the same refused value. Not judged
 * on `ObjectExtensionSchema`: an extension cannot declare `imageField` (its
 * strict shape refuses the key), so the pointer is only ever the owning
 * object's own. Pinned in `object-image-field.test.ts`.
 */
function refuseNonPictureImageField(
  ownName: unknown,
  imageField: unknown,
  fields: unknown,
  ctx: z.RefinementCtx,
): void {
  if (typeof imageField !== 'string') return;
  const objectName = typeof ownName === 'string' ? ownName : '<unnamed>';
  const accepted = IMAGE_FIELD_TYPES.map((t) => `\`${t}\``).join(' or ');
  const prescription =
    `\`imageField\` must name a field of this object whose type is ${accepted} — point it at one `
    + '(declare one with `Field.image()` or `Field.avatar()` if the object has none), or remove `imageField`.';
  const declared = fields !== null && typeof fields === 'object'
    && Object.prototype.hasOwnProperty.call(fields, imageField);
  if (!declared) {
    ctx.addIssue({
      code: 'custom',
      path: ['imageField'],
      message:
        `\`imageField\` names \`${imageField}\`, but object \`${objectName}\` declares no field `
        + `\`${imageField}\`. ${prescription}`,
    });
    return;
  }
  const type = ((fields as Record<string, unknown>)[imageField] as { type?: unknown } | null)?.type;
  if (typeof type === 'string' && (IMAGE_FIELD_TYPES as readonly string[]).includes(type)) return;
  ctx.addIssue({
    code: 'custom',
    path: ['imageField'],
    message:
      `\`imageField\` names \`${imageField}\`, a \`${String(type)}\` field on object \`${objectName}\`, `
      + `which is not a picture. ${prescription}`,
  });
}

// ⚠️ ORDER IS LOAD-BEARING (#5593). This map used to live ~700 lines BELOW
// `ObjectSchemaBase`, and the error map that reads it was built lazily
// (`objectUnknownKeyErrorImpl ??= …`) purely to step around the temporal dead
// zone that created. `strictObject` evaluates its options object at
// CONSTRUCTION — that is what lets the audit in `alias-integrity.test.ts` judge
// the table against the real `.shape` — so the deferral had to go, and the
// declaration order is what replaces it. Keep this block above
// `ObjectSchemaBase`; moving it back reintroduces the TDZ as a module-init
// crash under `OS_EAGER_SCHEMAS=1` (how `build-schemas.ts` runs), which the
// test suite does not reach because tests import lazily.
const ObjectSchemaBase = strictObject(
  {
    surface: 'this object',
    // The same semantic renames the WARNING layer already knew
    // (`OBJECT_KEY_GUIDANCE`). Graduating a surface from warn to reject must
    // not cost the author a prescription: `capabilities` → `enable` is a
    // different word for the same intent, so edit distance cannot reach it and
    // only an explicit entry can.
    aliases: { capabilities: 'enable', features: 'enable' },
    guidance: UNKNOWN_KEY_GUIDANCE,
    history:
      'Until this shape was closed these were dropped silently on the PARSE path — '
      + '`ObjectSchema.create()` has rejected them, but `defineStack({ objects })`, '
      + '`/api/v1/meta/types/object` and the Studio form all go through `parse()`, which did not.',
  },
  {
  /**
   * Identity & Metadata
   */
  name: z.string().regex(/^[a-z_][a-z0-9_]*$/).describe('Machine unique key (snake_case). Immutable.'),
  label: z.string().optional().describe('Human readable singular label (e.g. "Account")'),
  pluralLabel: z.string().optional().describe('Human readable plural label (e.g. "Accounts")'),
  description: z.string().optional().describe('Developer documentation / description'),
  icon: z.string().optional().describe('Icon name (Lucide/Material) for UI representation'),

  /**
   * Taxonomy & Organization
   */
  // `tags`, `active`, `abstract` removed in the 16.x line (#2377, ADR-0049):
  // no runtime reader (an "inactive"/"abstract" object still got a table and was
  // fully usable; tags were never consumed). `isSystem` STAYS — it is live:
  // plugin-sharing effectiveSharingModel defaults a no-sharingModel isSystem
  // object to public, and the security-posture lint exempts system objects.
  isSystem: z.boolean().optional().default(false).describe('Is system object (protected from deletion; defaults its org-wide sharing to public when no sharingModel is set — plugin-sharing)'),

  /**
   * Managed-by hint — declares which lifecycle bucket the object belongs
   * to so UI clients render the appropriate set of CRUD affordances and
   * the security layer can enforce matching defaults. Modelled after the
   * way Salesforce / ServiceNow / Workday segregate user-owned business
   * data from admin-authored configuration, system-driven runtime rows,
   * and append-only audit trails.
   *
   * - `platform`     — **Default.** User-owned business data. Generic
   *   New / Import / Edit / Delete affordances are all shown. Example:
   *   the user's own `sys_attachment`, `sys_comment`.
   * - `config`       — Admin-authored metadata / configuration. Generic
   *   New / Edit / Delete shown (admins author via wizard or form), but
   *   CSV Import is suppressed (config rows have nested JSON envelopes
   *   that don't round-trip through a flat sheet; clients should offer a
   *   purpose-built "Import definition (JSON)" action instead). Example:
   *   `sys_sharing_rule`, `sys_position`, `sys_permission_set`, `sys_view`,
   *   `sys_app`.
   * - `system-data`  — Platform-defined schema that holds **admin/user-writable
   *   DATA**: the RBAC link tables (`sys_user_position`,
   *   `sys_user_permission_set`, `sys_position_permission_set`, governed by
   *   the `DelegatedAdminGate`), `sys_user_preference`, the messaging config
   *   grids (`sys_notification_subscription`, `_template`, `_preference`). Two
   *   boundaries define it: the SCHEMA is the platform's (versioned with the
   *   release, not tenant-modelled — that is `platform`), while the DATA is the
   *   admin's or the user's, written through a governed path (not the engine's —
   *   that is `engine-owned`). The bucket DEFAULT is therefore WRITABLE (full
   *   CRUD); narrow it with {@link userActions} where an object takes less. The
   *   affordance is a declaration only — the real authz stays the
   *   delegated-admin gate / RLS / permission sets.
   *   (Renamed from the residual `system` in v17 — #3355. `system` named the
   *   bucket after the half of the overload v16 had already moved out to
   *   `engine-owned`, so it read as "the engine owns this" on precisely the
   *   objects users write.)
   * - `engine-owned` — Runtime rows whose lifecycle a platform service owns
   *   end to end (the approval engine, the sharing engine, the job runner, the
   *   metadata store, …), written only via `isSystem` / a service `SYSTEM_CTX` /
   *   a context-less engine call. No user writes, ever. Generic CRUD is hidden —
   *   users interact via *domain actions* on the source record (e.g. "Submit
   *   for Approval" creates a `sys_approval_request`). Example:
   *   `sys_approval_request`, `sys_record_share`, `sys_notification`,
   *   `sys_automation_run`, `sys_job`, `sys_metadata`, `sys_secret`. (ADR-0103;
   *   the explicit successor to the old engine-owned-DEFAULT overload of
   *   `system`. `append-only` objects granting no resolved write are also
   *   treated as engine-owned by the write guard, so the split is a
   *   self-documenting relabel, not an enforcement change.)
   * - `append-only`  — Immutable audit log. No New / Import / Edit /
   *   Delete; only View and Export. Example: `sys_approval_action`,
   *   `sys_audit_log`, `sys_activity`, `sys_email`, `sys_presence`.
   * - `better-auth`  — Identity tables owned by the better-auth driver
   *   (sys_user, sys_session, sys_account, sys_member, sys_organization,
   *   sys_api_key, sys_jwks, sys_verification, sys_two_factor,
   *   sys_oauth_*, sys_device_code). Mutations must flow through the
   *   better-auth API so password hashing, token signing, email
   *   verification, and invitation flows fire correctly. Generic CRUD
   *   suppressed; replaced by purpose-built actions
   *   (Invite User, Reset Password, Revoke Session, Rotate Key, …).
   *
   * The flag supplies the DEFAULT affordance row; the enforced write policy
   * is {@link resolveCrudAffordances} (bucket default + `userActions`).
   * Enforcement happens in three places:
   *   1. Default permission sets ({@link packages/platform-objects/src/security/default-permission-sets.ts})
   *      deny direct CRUD for `engine-owned` / `append-only` / `better-auth`.
   *   2. UI clients honour {@link resolveCrudAffordances} to gate the
   *      New / Import / Edit / Delete / Export buttons accordingly.
   *   3. Engine write guards fail-closed on user-context generic writes to a
   *      managed object whose resolved affordances forbid the verb —
   *      `better-auth` via plugin-auth's identity write guard (ADR-0092),
   *      `engine-owned` / `append-only` via plugin-security's engine-owned
   *      write guard (ADR-0103). `isSystem` / context-less engine writes bypass.
   *      `system-data` — like `platform` / `config` — is writable by default and
   *      carries no such guard; its writes are adjudicated by the delegated-admin
   *      gate / RLS / permission sets.
   *
   * Use {@link userActions} to override the default matrix for a single
   * field (e.g. an "append-only" table that should still allow Export).
   */
  managedBy: z.enum(['platform', 'config', 'system-data', 'engine-owned', 'append-only', 'better-auth'], {
    // Only the value that USED to be legal gets the retirement prescription —
    // telling the author of `managedBy: 'sytem'` that their value "was removed"
    // would misinform. Everything else keeps zod's own enum message, which
    // already lists the legal values.
    error: (issue) => (issue.input === 'system' ? MANAGED_BY_SYSTEM_RETIRED : undefined),
  }).optional().describe(
    'Lifecycle bucket — platform (user CRUD) | config (admin authored) | system-data (platform-defined schema, admin/user-writable data) | engine-owned (engine owns the lifecycle, no user writes) | append-only (audit) | better-auth (identity). UI clients honour the resolved affordance matrix.',
  ),

  /**
   * Record-ownership model — who a *record* belongs to. Drives the registry's
   * `owner_id` auto-provisioning (`packages/objectql/src/registry.ts` →
   * `applySystemFields`):
   *
   *   - `user` (default) — per-record owner: injects the reassignable `owner_id`
   *     lookup, engaging owner-scoped RLS, "My" views, owner reports and
   *     first-admin bootstrap. Also carries `owning_business_unit_id`.
   *   - `business_unit` — owned by an org UNIT, not by a person (inventory,
   *     equipment ledgers, departmental budgets): `owner_id` is NOT injected,
   *     `owning_business_unit_id` IS. [ADR-0117 D1]
   *   - `org` / `none` — no per-record owner of EITHER kind (Dataverse-style
   *     catalog / junction tables); neither anchor is injected. (Platform-managed
   *     tables — `managedBy` set, or the `sys_` namespace — skip ownership
   *     injection regardless.)
   *
   * The per-tier authority is `resolveInjectedSystemColumns`
   * (`@objectstack/spec/data`) — its table, not this prose, is what
   * `applySystemFields` and author-time lint both read.
   *
   * NOTE: this is the RECORD-ownership model, DISTINCT from the package
   * *contribution* kind (`own` | `extend` | `overlay`,
   * {@link ObjectOwnershipEnum}) that lives on the registry's contributor
   * record and is set via `registerObject` — do not conflate the two despite
   * the shared word.
   */
  ownership: z.enum(['user', 'business_unit', 'org', 'none'], {
    error:
      "`ownership` is the record-ownership model — one of 'user' (default) | 'business_unit' | 'org' | 'none'. " +
      "The package-contribution kind 'own'/'extend' is set via registerObject, not on the object schema.",
  }).optional().describe(
    "Record-ownership model: user (default — injects reassignable owner_id plus owning_business_unit_id) | business_unit (unit-owned: owning_business_unit_id only, no owner_id) | org | none (no per-record owner, neither anchor). Distinct from the package own/extend contribution kind.",
  ),

  /**
   * Per-object override of the generic CRUD affordances that the UI
   * surfaces. Each flag overrides the default derived from
   * {@link managedBy} via {@link resolveCrudAffordances}. Useful for the
   * handful of objects whose lifecycle doesn't cleanly fit a single
   * bucket — e.g. an `append-only` table that should still expose CSV
   * Export, or a `config` table that admins legitimately want to bulk
   * import via CSV.
   *
   * Omitting the block (or leaving individual flags `undefined`) keeps
   * the {@link managedBy}-derived default.
   *
   * Every CRUD flag except `exportCsv` also accepts the object form
   * {@link RowCrudActionOverrideSchema} — `{ enabled?, visibleWhen?,
   * disabledWhen? }` — which gates the affordance on record state instead
   * of only per object. `edit`/`delete` evaluate it per row (objectui#2614);
   * `create`/`import` evaluate it once per toolbar against the record in
   * scope (#7692). Read that schema's docblock for what `record.*` binds to
   * in each position — they are different records.
   */
  userActions: strictObject({
    surface: "this object's `userActions` block",
    history:
      'Until this shape was closed, these were dropped silently — the block still parsed, so an affordance ' +
      'the author meant to hide stayed on the toolbar, and the `managedBy`-derived ' +
      'default silently won.',
    aliases: {
      export: 'exportCsv',
      csvExport: 'exportCsv',
      exportcsv: 'exportCsv',
      new: 'create',
      add: 'create',
      insert: 'create',
      update: 'edit',
      remove: 'delete',
      destroy: 'delete',
    },
    guidance: {
      // Wrong-LAYER, and the trap is that the key name is right somewhere else.
      // `ui/view.zod.ts` declares its own `userActions` with a completely
      // disjoint vocabulary (sort/search/filter/refresh/rowHeight/group/
      // addRecordForm/editInline/hideFields/rowColor/buttons — the last three
      // adopted by commit b37231883), so an author who learned that block writes these
      // here. `group`/`hideFields`/`rowColor` were refused by name but without
      // a curated pointer until #11459 gave them one too, mirroring the other
      // four.
      sort:
        '`sort` is a VIEW `userActions` key, not an object one — the two blocks share a ' +
        'name and nothing else. The object block governs CRUD affordances ' +
        '(create/import/edit/delete/exportCsv); toolbar controls ' +
        '(sort/search/filter/refresh/rowHeight/editInline) live on the view.',
      search:
        '`search` is a VIEW `userActions` key. This object block governs CRUD affordances ' +
        'only — put toolbar controls on the view that renders the records.',
      filter:
        '`filter` is a VIEW `userActions` key. This object block governs CRUD affordances ' +
        'only — put toolbar controls on the view that renders the records.',
      editInline:
        '`editInline` is a VIEW `userActions` key. The object-level `edit` flag decides ' +
        'whether editing is offered AT ALL; how it is offered (inline vs form) is the ' +
        "view's call.",
      group:
        '`group` is a VIEW `userActions` key. This object block governs CRUD affordances ' +
        'only — put toolbar controls on the view that renders the records.',
      hideFields:
        '`hideFields` is a VIEW `userActions` key. This object block governs CRUD ' +
        'affordances only — put toolbar controls on the view that renders the records.',
      rowColor:
        '`rowColor` is a VIEW `userActions` key. This object block governs CRUD ' +
        'affordances only — put toolbar controls on the view that renders the records.',
      clone:
        '`clone` is a CAPABILITY, not a user action — write `enable: { clone: false }`. ' +
        'The `enable` block (ObjectCapabilities) is where record deep-cloning is governed.',
      read:
        '`userActions` toggles WRITE affordances only; there is no read toggle. Read ' +
        'access is governed by permissions (`requiredPermissions`) and `access.default`.',
      view:
        '`userActions` toggles WRITE affordances only; there is no view toggle. ' +
        'Visibility is governed by permissions (`requiredPermissions`) and `access.default`.',
    },
  }, {
    create: z.union([z.boolean(), RowCrudActionOverrideSchema]).optional().describe(
      'Show generic "New" button. Boolean, or an object adding visibleWhen/disabledWhen CEL predicates evaluated once per toolbar against the record in scope (the host record on a related list).',
    ),
    import: z.union([z.boolean(), RowCrudActionOverrideSchema]).optional().describe(
      'Show CSV import wizard entry. Boolean, or an object adding visibleWhen/disabledWhen CEL predicates evaluated once per toolbar against the record in scope (the host record on a related list).',
    ),
    edit: z.union([z.boolean(), RowCrudActionOverrideSchema]).optional().describe(
      'Allow inline / form edit of existing rows. Boolean, or an object adding per-record visibleWhen/disabledWhen CEL predicates.',
    ),
    delete: z.union([z.boolean(), RowCrudActionOverrideSchema]).optional().describe(
      'Show row-level delete + bulk delete. Boolean, or an object adding per-record visibleWhen/disabledWhen CEL predicates.',
    ),
    exportCsv: z.boolean().optional().describe('Show CSV export entry.'),
  }).optional().describe('Per-object override of the resolved CRUD affordance matrix.'),

  /**
   * System-field auto-injection control.
   *
   * The `SchemaRegistry` augments every user object with a small set of
   * implicit system fields at registration time so authors don't have to
   * declare them per-object (Salesforce-style). Currently injected
   * (`packages/objectql/src/registry.ts` → `applySystemFields`):
   *
   *   - `organization_id` — `lookup → sys_organization`. The COLUMN is
   *     provisioned unconditionally (subject to the opt-outs below); only its
   *     DB index is gated on multi-tenant mode. It stays NULL on single-tenant
   *     stacks and is auto-stamped on insert by `@objectstack/organizations`
   *     (the `org-scoping` service) in multi-tenant mode.
   *   - Audit columns — `created_at`, `created_by`, `updated_at`, `updated_by`
   *     (`readonly` + `system`). Gated by `audit` below.
   *   - `owner_id` — `lookup → sys_user`, auto-provisioned on user-authored
   *     business objects (auto-stamped to the creating user on insert;
   *     reassignable). Governed by the object-level `ownership` property
   *     (`'user' | 'business_unit' | 'org' | 'none'`), NOT by `owner` below.
   *     Injected under `'user'` and when `ownership` is omitted; withheld under
   *     `'business_unit' | 'org' | 'none'`.
   *   - `owning_business_unit_id` — `lookup → sys_business_unit`, the
   *     record-level ORG-UNIT ownership tier between `owner_id` (a person) and
   *     `organization_id` (the tenant wall). [ADR-0117 D1, landed in #5677]
   *     Governed by the same `ownership` property, but over a WIDER set of
   *     tiers than `owner_id`: injected under `'user'`, when `ownership` is
   *     omitted, and under `'business_unit'` (the tier that carries this anchor
   *     and deliberately no `owner_id`); withheld under `'org' | 'none'`.
   *     Shaped after `organization_id` (`readonly` + `hidden` + `system`), not
   *     after `owner_id` — it is a server-stamped scope anchor. Provisioned but
   *     **inert**: the stamping middleware (ADR-0117 D2/D4) has not landed, so
   *     nothing writes a value yet — including on `'business_unit'` objects,
   *     where the declaration is authorable (#5678) while the stamp is not.
   *
   * The authority on which of these an object actually carries is
   * `resolveInjectedSystemColumns` (`@objectstack/spec/data`): `applySystemFields`
   * consumes it, and author-time lint reads the same derivation rather than
   * re-deriving the conditions from this prose.
   *
   * Author-declared fields with the same name always win over injection
   * (no overwrite). Objects with `managedBy` set (and the `sys_*` namespace)
   * are skipped for ownership; `managedBy: 'better-auth'` is skipped entirely —
   * better-auth's own migrations own that column layout.
   *
   * Set `systemFields: false` to opt the object out completely. Pass an
   * options object to selectively disable individual injections (`tenant`,
   * `audit`).
   *
   * @default undefined (= injection enabled)
   */
  systemFields: z
    .union([
      z.literal(false),
      strictObject({
        surface: "this object's `systemFields` block",
        history:
          'Until this shape was closed, these were dropped silently — the block still parsed, so an ' +
          'opt-out the author wrote had no effect and the registry injected the column ' +
          'anyway.',
        aliases: {
          organization: 'tenant',
          org: 'tenant',
          tenancy: 'tenant',
          organizationId: 'tenant',
          auditFields: 'audit',
          timestamps: 'audit',
        },
        guidance: {
          // The field doc above this block names `owner` while the shape has
          // never declared it — so an author following the prose lands exactly
          // here. `ownership` is the real, enforced lever.
          owner:
            '`owner` is not a `systemFields` key — `owner_id` injection is governed by the ' +
            "object-level `ownership` property: `'user'` (or omitted) injects it, while " +
            "`'org'` and `'none'` BOTH skip it and no `owner_id` is injected at all — " +
            "`'org'` for an org-wide catalog (Dataverse-style), `'none'` for a junction/link " +
            "table. `'business_unit'` skips it too, for a different reason: that tier is " +
            'owned by an org UNIT rather than a person, so it carries ' +
            '`owning_business_unit_id` and deliberately no `owner_id` (ADR-0117 D1). ' +
            '`systemFields` controls only `tenant` (organization_id) and `audit` ' +
            '(created_at/created_by/updated_at/updated_by).',
          ownership:
            '`ownership` is a TOP-LEVEL object key, not a `systemFields` key — write it ' +
            'beside `systemFields`. It, not this block, decides whether the ownership ' +
            'anchors (`owner_id` and `owning_business_unit_id`) are injected.',
        },
      }, {
        tenant: z.boolean().optional().describe('Inject the organization_id column. Default true (the column is always provisioned; the multi-tenant flag governs only its index).'),
        audit: z.boolean().optional().describe('Inject the audit columns (created_at/created_by/updated_at/updated_by). Default true.'),
      }),
    ])
    .optional()
    .describe('Opt out of, or selectively disable, registry-level system-field auto-injection.'),

  /** 
   * Storage & Virtualization 
   */
  datasource: z.string().optional().default('default').describe('Target Datasource ID. "default" is the primary DB.'),

  /**
   * External Binding (ADR-0015)
   * Present only for federated objects routed to a datasource whose
   * `schemaMode !== 'managed'`. Describes the remote table binding and
   * per-object writability. See {@link ObjectExternalBindingSchema}.
   */
  external: ObjectExternalBindingSchema.optional()
    .describe('Remote table binding for federated (external) objects.'),

  /**
   * Data Model
   */
  fields: refuseRecordProtoKey(
    // [#17852, #19346] The three JS-prototype names are refused by
    // TWO mechanisms, because zod reaches them at two different depths:
    //
    //   - `__proto__` reaches NO schema at all — zod's record parser skips it
    //     with an unconditional `continue` ABOVE the key schema — so it is
    //     refused on the RAW input by `refuseRecordProtoKey` around this.
    //   - `constructor` and `prototype` DO reach the parse (ordinary
    //     lowercase words the snake_case regex below already admits) and are
    //     refused HERE, on the RECORD, through the closed projection list's
    //     `banned-keys` arm.
    //
    // ⭐ The arm — and not the key-schema `.refine()` it replaces (#19147) —
    // is what carries the refusal into `packages/spec/json-schema/**`.
    // `z.toJSONSchema()` has no arm for a `custom` check, so a rule written
    // on the KEY schema was enforced by the runtime and ABSENT from the
    // published file: nine `fields.out.keyType` rows in
    // `dropped-refinements.baseline.json`, one per embedding schema, and a
    // validator reading the published contract answered PASS on a document
    // the platform refuses by name. Declared through `bannedKeys`, the same
    // rule is published as `propertyNames` + `not` and those nine rows leave
    // the ledger (#19346, closing a piece of #18670). The accept set is
    // unchanged in both directions — `bannedKeys` reads OWN properties, which
    // is exactly what the key schema judged.
    //
    // ⭐ [#20997] ONE refine PER NAME, each located AT its key
    // (`fields.constructor`, `fields.prototype`) — the path the `__proto__`
    // guard and the key grammar's `invalid_key` already report at, and the one
    // `saveMetaItem`'s structured issues need for a Studio form to highlight
    // the offending field. `.refine()`'s `path` is STATIC, so a single
    // two-name predicate could only ever name the slot; one single-name
    // predicate per name makes the path a constant again, and the name is ONE
    // string read twice — into the ban and into the path — so the two cannot
    // drift. ⛔ Not a `.superRefine()` with a computed path: that check holds
    // no readable predicate, so the generator could not project it and the
    // published file would go wide again (the nine rows above would return).
    // The published keywords are the same rule, conjoined one clause per name
    // (`not enum [a, b]` ≡ `not enum [a]` ∧ `not enum [b]`), and the message
    // and `custom` code are byte-identical to the one-refine spelling.
    (['constructor', 'prototype'] as const).reduce(
      (record, reserved) =>
        record.refine(bannedKeys([reserved]), {
          message: 'Field names must not be "constructor" or "prototype" (reserved JavaScript prototype property names).',
          path: [reserved],
        }),
      z.record(
        z.string()
          .regex(/^[a-z_][a-z0-9_]*$/, {
            message: 'Field names must be lowercase snake_case (e.g., "first_name", "company", "annual_revenue")',
          }),
        FieldSchema,
      ),
    ),
    'fields',
  ).describe('Field definitions map. Keys must be snake_case identifiers; "__proto__", "constructor" and "prototype" are refused.'),
  indexes: z.array(IndexSchema).optional().describe('Database performance indexes'),

  /**
   * Field Groups (MVP)
   * 
   * Declares logical groups for presenting fields in forms and detail
   * pages. The **array order is the group display order**. Each field's
   * `Field.group` references an entry's `key` to assign it to a group;
   * within a group, fields are displayed in their `ObjectSchema.fields`
   * declaration order.
   * 
   * See {@link ObjectFieldGroupSchema} for the full MVP contract and
   * deferred features.
   */
  fieldGroups: z.array(ObjectFieldGroupSchema).refine(
    (groups) => new Set(groups.map(g => g.key)).size === groups.length,
    { message: 'fieldGroups[].key must be unique within an object' },
  ).optional().describe('Ordered list of field groups (array order = display order). See ObjectFieldGroupSchema.'),
  
  /**
   * Advanced Data Management
   */
  
  // Multi-tenancy configuration
  tenancy: TenancyConfigSchema.optional().describe('Multi-tenancy configuration for SaaS applications'),

  /**
   * [ADR-0066 D2] Secure-by-default object posture. `access.default: 'private'`
   * opts the object OUT of blanket wildcard (`'*'`) permission grants (access
   * then needs an explicit per-object grant) and exempts it from wildcard RLS
   * via the posture-gated superuser bypass. Absent ⇒ `public` (today's
   * allow-by-default behaviour; no migration for existing objects).
   */
  access: ObjectAccessConfigSchema.optional().describe('[ADR-0066 D2] Object exposure posture (public-by-default vs private secure-by-default).'),

  /**
   * [ADR-0066 D3/⑤] Capability contract — capability name(s) (permission-set
   * `systemPermissions`; D1 records) a caller MUST hold to access this object.
   * Mirrors `App.requiredPermissions`. Enforced by plugin-security as an
   * AND-gate: checked IN ADDITION to permission-set CRUD grants — a caller
   * missing any required capability is denied regardless of grants.
   *
   * Two shapes:
   *  - `string[]` — required for ALL operations (read/create/update/delete).
   *  - `{ read?, create?, update?, delete? }` (⑤) — required only for the listed
   *    operation class, so an object can be read-open but write-gated.
   * Absent/empty ⇒ no capability gate.
   */
  requiredPermissions: ObjectRequiredPermissionsSchema.optional().describe('[ADR-0066 D3/⑤] Capabilities required to access this object (AND-gate) — `string[]` gates all CRUD, or a `{read,create,update,delete}` map gates per operation.'),

  // Data lifecycle (ADR-0057) — retention / rotation / archival contract,
  // enforced by the LifecycleService. Absent = `record` (today's behavior).
  lifecycle: LifecycleSchema.optional().describe('Data lifecycle contract (ADR-0057): class + retention/ttl/rotation/archive policies enforced by the platform LifecycleService.'),

  /**
   * Who answers "may this caller download a file owned by this object's media
   * fields?" (ADR-0104 D3 wave 2).
   *
   * By default the storage service asks the question directly — can the caller
   * READ the owning row? That is right for ordinary business objects, where
   * row readability *is* the access rule. It is wrong for an object whose
   * access is **mediated by a service** rather than by row permissions: a
   * system audit table like `sys_approval_action` is deliberately unreadable
   * to ordinary positions, yet a legitimate approver must still be able to
   * open a decision attachment. Testing raw readability there asks the wrong
   * authority and denies the very people the record is for.
   *
   * Naming a kernel service here delegates the question to it. The service
   * must implement `authorizeFileRead(recordId, context) => boolean` (see
   * `IFileAccessDelegate`). Fails CLOSED: a declared service that is missing
   * or does not implement the method denies the download rather than falling
   * back to the raw read.
   */
  fileAccessDelegate: z.string().optional().describe(
    'Kernel service that authorizes downloads of files owned by this object\'s media fields, '
    + 'instead of testing whether the caller can read the owning row. For objects whose access '
    + 'is mediated by a service (e.g. sys_approval_action → approvals). Fails closed.',
  ),

  /**
   * Logic & Validation (Co-located)
   * Best Practice: Define rules close to data.
   */
  validations: z.array(ValidationRuleSchema).optional().describe('Object-level validation rules'),

  /**
   * Declarative semantic activity milestones (ADR-0052 §5b.2). When a watched
   * field transitions INTO `value`, the platform emits a templated activity-row
   * on the record timeline — no `*.hook.ts` / `*.flow.ts`. Complements field-level
   * `trackHistory` (which renders raw "Field: old → new"): use milestones for
   * business-meaningful events ("Deal won", "Task completed"). `summary` supports
   * `{field}` tokens interpolated from the record; the milestone summary takes
   * precedence over the field-change summary for the same update. Consumed by
   * `@objectstack/plugin-audit` audit-writers (enforce-or-remove, ADR-0049).
   */
  activityMilestones: z.array(strictObject({
    surface: 'this activity milestone',
    history:
      'Until this shape was closed, these were dropped silently — the milestone still parsed, so a ' +
      'mis-keyed template shipped a timeline row with the wrong text, or the milestone ' +
      'never fired at all.',
    aliases: {
      message: 'summary',
      template: 'summary',
      text: 'summary',
      title: 'summary',
      to: 'value',
      watch: 'field',
      activityType: 'type',
    },
    guidance: {
      from:
        '`from` is not a milestone key — a milestone fires on transition INTO `value`, ' +
        'whatever the previous value was. There is no from-state filter here; when the ' +
        'TRANSITION itself must be constrained, declare a `state_machine` rule in ' +
        '`validations` (ADR-0020), which is where the legal transition table lives.',
      when:
        '`when` is not a milestone key — the trigger is structural: `field` transitions ' +
        'INTO `value`. For a conditional timeline row, gate it with a `state_machine` ' +
        'rule in `validations` or a hook.',
    },
  }, {
    field: z.string().describe('Field to watch (typically a status/stage select).').meta({ title: 'Field' }),
    value: z.string().describe('The value the field must transition INTO to fire the milestone.').meta({ title: 'Value' }),
    summary: z.string().describe('Activity summary template; {field} tokens interpolate the record value. e.g. "Deal won: {name}".').meta({ title: 'Summary' }),
    type: z.string().optional().describe('Activity type for the emitted row — left unset, it keeps the update row\'s kind, "updated" (a milestone only fires on an update).').meta({ title: 'Type' }),
  })).optional().describe('Declarative semantic activity milestones — emit a templated timeline row when a field transitions into a value, no hook code (ADR-0052 §5b.2).'),

  // ADR-0020: record state machines are not a separate `stateMachines` map —
  // each lifecycle is a `state_machine` rule in `validations` above (one rule
  // per state field). Parallel lifecycles = multiple rules. The write path
  // enforces the transition table; UIs read the legal next states via the
  // `/meta/objects/:name/state/:field?from=` introspection endpoint.

  /**
   * Display & UI Hints (Data-Layer)
   */
  /**
   * [ADR-0079] Canonical pointer to the object's PRIMARY title field — the one
   * real stored field (text / autonumber / formula→text) that is a record's
   * human name. Optional at the schema level for now (a hard required-refine is
   * staged so existing title-less metadata still parses). Resolve / derive via
   * `resolveDisplayField` from `@objectstack/spec/data` (display-name.ts), which
   * falls back to the deprecated `displayNameField` alias and then a derivation.
   * Auto-naming (system-generated record names) is modelled as a `Field` of
   * type 'autonumber' with `autonumberFormat`, designated as the `nameField`.
   */
  nameField: z.string().optional().describe('[ADR-0079] Canonical primary title field — the stored field used as the record display name (e.g. "name", "title").'),
  /**
   * @deprecated [ADR-0079] Renamed to `nameField`. Still ACCEPTED as an alias:
   * the schema copies `displayNameField` onto `nameField` on parse when
   * `nameField` is absent (both are preserved on the parsed output for
   * cross-repo back-compat). New metadata should set `nameField`.
   */
  displayNameField: z.string().optional().describe('[DEPRECATED → nameField] Field to use as the record display name (e.g., "name", "title"). Accepted as an alias for nameField.'),
  titleFormat: TemplateExpressionInputSchema.optional().describe('[DEPRECATED → nameField (ADR-0079)] Render-only title template; the server cannot return or query it, and an explicit nameField now takes precedence. Migrate a single-field title to nameField, a composite to a formula field designated as nameField. Placeholders may be written {{field}} or {field} — the title renderers treat the two as equivalent, normalizing {{field}} to {field} before substituting; neither spelling is judged at parse time.'),
  /**
   * [#21182 — ruling A on objectstack-ai/hotcrm#1199] The record's PICTURE:
   * names the field whose value the record page header — the record chrome
   * every record detail page shares — draws beside the title. A sibling of
   * `nameField`: `nameField` says which field is the record's name, this says
   * which is its picture. One object-level declaration that every detail page
   * reads, deliberately NOT a `page:header` prop (that header's own identity
   * is drawn by the record chrome, which is why its `icon` was retired).
   *
   * - Must name a field of this object whose type is `image` or `avatar`;
   *   anything else — an undeclared name, a `text` URL column, a `file` — is
   *   refused at parse by `refuseNonPictureImageField`, so at every authoring
   *   and publish door.
   * - A record whose field is empty shows no picture. The reader draws nothing
   *   in its place — no initials, no placeholder avatar.
   *
   * The reader is objectui's record chrome (`PageHeaderRenderer` in
   * `packages/components/src/renderers/layout/containers.tsx`): it resolves the
   * record's value of the named field and draws it in the record chip's icon
   * slot beside the title, an `avatar` round and cropped, an `image` whole. The
   * liveness ledger row `object.imageField` cites that reader at the objectui
   * pin it was read at.
   */
  imageField: z.string().optional().describe('The record\'s picture: names the field the record page header (record chrome) draws beside the title — one object-level declaration every record detail page reads, not a per-page header prop. Must name a field of this object whose type is `image` or `avatar`; any other name is refused. A record whose field is empty shows no picture (no initials or placeholder).'),
  /**
   * [ADR-0085] Semantic role: the object's most important fields, in priority
   * order (the first entry wins wherever only one field fits, e.g. child-record
   * previews). Cross-surface by definition — drives default list/grid columns,
   * cards, hover/lookup previews, and the record-detail highlight strip (first
   * 4). Renamed from `compactLayout` (the value is an ordered field list, not
   * a layout); Salesforce compact-layout semantics.
   */
  highlightFields: z.array(z.string()).optional().describe('[ADR-0085] Ordered most-important fields; first entry wins where only one fits. Drives default columns, cards, previews, detail highlight strip. Renamed from compactLayout.'),
  // `compactLayout` (the pre-ADR-0085 spelling of `highlightFields`) was an
  // accepted parse-time alias for one deprecation window and is now RETIRED
  // (framework#2536): authoring it is rejected by `create()` like any unknown
  // key. All first-party consumers read `highlightFields` since objectui#2168.
  /**
   * [ADR-0085] Semantic role: the field that represents the record's LINEAR
   * lifecycle (an ordered pipeline / stage progression). A string names the
   * field; `false` declares the object's status-like field NON-linear (an
   * unordered state set such as active/suspended/void) and suppresses every
   * consumer's stage heuristics. Absent = consumers may heuristically detect
   * a stage field (status/stage/state/phase). Consumed by the record-detail
   * path/stepper today; kanban default grouping, list badges and report
   * bucketing are natural future consumers.
   */
  stageField: z.union([z.string(), z.literal(false)]).optional().describe('[ADR-0085] Lifecycle stage field (linear/ordered), or false to declare the status field non-linear and suppress stage heuristics. Absent = heuristic detection allowed.'),

  /**
   * Cross-renderer EDIT-INTERACTION intent: whether a record of this object is
   * edited in a modal dialog over the current view (`'modal'`) or on a
   * dedicated full-page edit route (`'page'`). Like the other hints in this
   * block it is an intent about the record, not pixel styling — any renderer
   * can honour it. Absent = the renderer chooses its own default (objectui's
   * shipped runtime treats anything but `'page'` as modal:
   * `recordFormNavigation.ts` branches on `editMode !== 'page'`, and
   * `AppContent`'s `handleEdit` dispatcher routes on it).
   *
   * Declared here by commit f11fc61c5's maintainer ruling (the measured residue of the
   * #10144 declare-or-rule-out census): objectui had published the key to
   * authors (CHANGELOG + live runtime read) while this strict parse rejected
   * it. objectui's `ObjectSchemaClientExtensions.editMode` mirror retires in a
   * release-gated follow-up and the spec derivation carries it from then on.
   */
  editMode: z.enum(['modal', 'page']).optional().describe("Edit-interaction intent for records of this object: 'modal' opens the edit form as a dialog over the current view; 'page' navigates to a dedicated full-page edit route. Absent = the renderer picks its own default (objectui defaults to modal). Cross-renderer intent, not pixel styling (family)."),

  /**
   * Built-in List Views
   *
   * Curated, platform-shipped list views (grid / kanban / calendar / …)
   * keyed by view name. Rendered as segmented tabs in the console list page
   * **before** any user-saved `sys_view` rows. Use this for system objects
   * (audit, runtime, config) where the default "All records" grid lacks
   * business context — e.g. an approval-request list should ship with
   * "My pending", "I submitted", "Completed" tabs out of the box.
   *
   * Each value is an `ObjectListViewSchema` (a `ListViewSchema` whose `userFilters`
   * is narrowed to dropdown value chips — ADR-0047 "views" mode, where the
   * `ViewTabBar` owns the tab-bar role so `tabs` presets stay page-only) so authors
   * get the full filter/sort/grouping vocabulary plus quick-filter dropdowns.
   *
   * @example
   * ```ts
   * listViews: {
   *   my_pending: {
   *     type: 'grid',
   *     label: 'My Pending',
   *     filter: [{ field: 'pending_approvers', operator: 'contains', value: '{current_user_id}' }],
   *     sort: [{ field: 'updated_at', order: 'desc' }],
   *   },
   * }
   * ```
   */
  listViews: z.record(z.string(), ObjectListViewSchema).optional().describe('Built-in named list views (segmented tabs) shipped with the object schema — "views" mode, dropdown userFilters allowed, no page-only tabs (ADR-0047)'),

  /**
   * Search Engine Config 
   */
  searchableFields: z.array(z.string()).optional().describe('Fields the `$search` query matches against (ADR-0061). Canonical default for the record picker, list quick-search and global search; views may narrow it. When unset, search auto-defaults to the name/title field plus short-text fields. Entries must name a STORED column: a virtual `formula` field is computed on read and materializes no column, so searching it can never match and it is refused — mirror the value onto a stored text field and declare that.'),

  /**
   * System Capabilities
   */
  enable: ObjectCapabilities.optional().describe('Enabled system features modules'),

  /**
   * Sharing Model (org-wide default).
   *
   * `controlled_by_parent` (ADR-0055) makes this a DETAIL object in a
   * master-detail relationship: its access is *derived* from the master record
   * — a user sees/edits a detail only if they can see/edit its master. The
   * object must declare exactly one required `master_detail` field identifying
   * the master; the security layer auto-injects `masterFK IN (accessible master
   * ids)` on reads and requires master edit-access on by-id writes. No RLS policy
   * is authored — the inheritance is derived from the relationship.
   */
  sharingModel: z.enum(['private', 'public_read', 'public_read_write', 'controlled_by_parent']).optional().describe('Org-Wide Default record visibility (OWD) for INTERNAL users. Canonical four only (legacy aliases removed, ADR-0090 D4): private (owner-only) | public_read (everyone reads, owner writes) | public_read_write (everyone reads+writes) | controlled_by_parent (derived from the master record). A CUSTOM object that omits this resolves to private at runtime (ADR-0090 D1).'),

  /**
   * [ADR-0090 D11] Org-Wide Default for EXTERNAL principals
   * (`principal.audience: 'external'` — portal / partner users). A second,
   * stricter dial: defaults to `private` when omitted and may NEVER be wider
   * than the internal `sharingModel` (validated at authoring). The BU depth
   * axis does not apply to externals; their visibility = own records +
   * explicit shares + this baseline.
   */
  externalSharingModel: z.enum(['private', 'public_read', 'public_read_write', 'controlled_by_parent']).optional().describe('[ADR-0090 D11] OWD for external (portal/partner) principals. Defaults to private; must be <= sharingModel in openness.'),

  /**
   * Public Share-Link Policy
   *
   * Opt-in declaration that records of this object MAY be published via
   * an opaque capability token (Notion / Google Docs / Figma "anyone with
   * the link" style). When omitted or `enabled:false`, the platform
   * refuses to create share-link rows for this object AND refuses to
   * resolve any that already exist — a STANDING policy held at every
   * redemption, not a mint-time check (#14033), so links minted while the
   * block was on stop serving the moment it is turned off, those minted
   * through the system-context / `permissive` mint bypass included. Both
   * halves are independent of any permission the caller holds; see
   * `enabled` below for the whole statement.
   *
   * Distinct from {@link sharingModel}, which governs *principal-based*
   * sharing (share with specific users / teams / roles). A single object
   * can opt into both: principals get full edit, link recipients get
   * read-only with redaction.
   *
   * Defaults are conservative: when `enabled:true` and no other field is
   * provided, the plugin allows `link_only` audience + `view` permission
   * (the safest combination — caller still needs the URL to access).
   *
   * @see {@link isPublicSharingEnabled} — the ONE reading of `enabled`,
   *      exported below beside this declaration.
   * @see packages/plugins/plugin-sharing/src/share-link-service.ts
   */
  publicSharing: strictObject({
    surface: "this object's `publicSharing` policy",
    history:
      'Until this shape was closed, these were dropped silently — the policy still parsed, so a redaction ' +
      'list or an expiry cap the author wrote was never applied to the links the platform ' +
      'went on to issue. On a policy whose whole job is to be restrictive, a silently ' +
      'dropped key fails OPEN.',
    aliases: {
      audiences: 'allowedAudiences',
      permissions: 'allowedPermissions',
      redact: 'redactFields',
      redacted: 'redactFields',
      maxExpiry: 'maxExpiryDays',
      expiryDays: 'maxExpiryDays',
      condition: 'eligibility',
    },
    guidance: {
      sharingModel:
        '`sharingModel` governs PRINCIPAL-based sharing (specific users / teams / roles) ' +
        'and is a TOP-LEVEL object key, not a `publicSharing` key. `publicSharing` is the ' +
        'separate opt-in for opaque share LINKS — an object may declare both, and they ' +
        'do not constrain each other.',
      externalSharingModel:
        '`externalSharingModel` is a TOP-LEVEL object key (ADR-0090 D11) — the OWD for ' +
        'external portal/partner principals. Link sharing is this block; principal-based ' +
        'external access is that key, one level up.',
    },
  }, {
    /**
     * Master switch — a STANDING policy held at every redemption, not a
     * mint-time check (#14033; the same shape as the `eligibility` predicate
     * below, commit fc9ba76a5).
     *
     * When false (default), no share links can be issued for this object AND
     * no share link on it resolves: `resolveToken` re-reads this switch on
     * every redemption, so links minted while it was on stop serving the
     * moment it is turned off — links minted through the system-context /
     * `permissive` mint bypass included (redemption is an anonymous act; how
     * the row got there buys it nothing). Not a revocation: no row moves, and
     * re-enabling the block serves them again. Off ⇒ nothing inside this block
     * is evaluated; on ⇒ the sibling keys apply at redemption. The refusal is
     * the undifferentiated `null` documented on `IShareLinkService.resolveToken`
     * (`contracts/share-link-service.ts`).
     */
    enabled: z.boolean().default(false).describe('Allow records of this object to be published via share link'),
    /**
     * Audiences the platform will accept when issuing a link.
     * - `public`       — search engines may index; no token check (rare)
     * - `link_only`    — anyone holding the token (default)
     * - `signed_in`    — token + an authenticated session of any tenant user
     * - `email`        — token + recipient's email matches an allowlist
     */
    allowedAudiences: z.array(z.enum(['public', 'link_only', 'signed_in', 'email'])).optional().describe('Audiences callers may select when creating a link'),
    /** Permission levels callers may grant via a link. Defaults to `['view']`. */
    allowedPermissions: z.array(z.enum(['view', 'comment', 'edit'])).optional().describe('Permission levels selectable on the share dialog'),
    /** Hard cap on requested expiry, in days. Links with `expires_at` further out are rejected. */
    maxExpiryDays: z.number().int().positive().optional().describe('Reject links with expiry beyond this many days'),
    /**
     * Fields stripped from every response served via a share token,
     * regardless of audience. Use for prompts, raw model output,
     * internal metadata, PII, etc. The owner's normal API access is
     * unaffected — redaction is applied only when the request principal
     * is `kind:'share-link'`.
     */
    redactFields: z.array(z.string()).optional().describe('Field names removed from records served via a share token'),
    /**
     * Optional CEL predicate over the candidate record. It is a STANDING
     * policy about which records may be reached anonymously, and the platform
     * holds it at BOTH points in a link's life (commit fc9ba76a5):
     *
     *   - **at mint** — `createLink` refuses with 422 when the predicate is
     *     false (e.g. "draft records cannot be shared") and writes no link row;
     *   - **at redemption** — every `resolveToken` re-evaluates it against the
     *     record it is about to serve. A record that STOPS qualifying (an
     *     `audience` flipped to internal, a `status` reverted to draft) stops
     *     being served through links minted while it did qualify.
     *
     * ⚠️ Tightening this policy therefore cuts off already-minted links, on
     * purpose — no revocation step, no grace period. That is the point of a
     * standing policy, and it is a behaviour change for deployments that
     * shipped before commit fc9ba76a5.
     *
     * Fail-CLOSED at both points: a predicate that does not compile, that
     * faults on the record, or that answers anything other than `true` refuses
     * rather than assuming consent. The redemption refusal is deliberately
     * INDISTINGUISHABLE from a revoked, expired or unknown token — an
     * anonymous holder is told nothing about why a link died; that reason goes
     * to the server-side log.
     *
     * Evaluator is the same one used by sharing rules.
     */
    eligibility: z.string().optional().describe('CEL expression that must evaluate to true on the target record. Enforced at BOTH points in a link\'s life: when the link is minted, and again on every redemption — a record that stops qualifying stops being served through links already minted for it. Fail-closed: a predicate that will not compile, or that faults on the record, refuses.'),
  }).optional().describe('Public share-link policy (Notion/Figma-style link sharing)'),

  // [ADR-0085] The former `detail: { … }.passthrough()` UI-hints block is
  // REMOVED. Presentation intent lives in the cross-surface semantic roles
  // above (nameField / highlightFields / stageField / fieldGroups); per-page
  // control is an assigned Page. The passthrough block bred silently-inert
  // keys (9 read by renderers vs 3 typed; the typed `hideReferenceRail` was
  // itself a no-op for spec authors) — see the ADR for the full inventory.
  // `renderViaSchema` — the block's last-surviving key, kept only as the
  // legacy monolith detail renderer's kill-switch — retired with that
  // renderer in objectui#2546 (ADR-0085 PR4).

  /**
   * Object Actions
   * 
   * Actions associated with this object. Populated automatically by `defineStack()`
   * when top-level actions specify `objectName` matching this object.
   * Can also be defined directly on the object.
   * 
   * Aligns with Salesforce/ServiceNow patterns where actions are part of the
   * object schema, so API responses (e.g., `/api/v1/meta/objects/:name`)
   * include the action list without requiring downstream merge.
   */
  actions: z.array(ActionSchema).optional().describe('Actions associated with this object (auto-populated from top-level actions via objectName)'),

  /**
   * ADR-0010 §3.7 — Package-level protection envelope. Package
   * authors declare lock policy here; the loader translates it
   * into the private `_lock` envelope at registration time and
   * strips this block before persistence. See
   * `shared/protection.zod.ts`.
   */
  protection: ProtectionSchema.optional().describe(
    'Package author protection block — lock policy for this object.',
  ),

  // ADR-0010 — runtime protection envelope (internal — set by loader).
  ...MetadataProtectionFields,
}).superRefine((object, ctx) => {
  // [#14892] A `tree` field's `reference`, when present, must be this object's
  // own name — judged here because only the object knows its name. `.superRefine`
  // keeps this a `ZodObject` (zod 4 attaches checks in place), so `.shape` and
  // `create()`'s unknown-key walk are untouched; see the helper's docblock.
  refuseForeignTreeReference(object.name, object.fields, ctx);
  // [#21182] `imageField` names a declared `image` / `avatar` field of THIS
  // object — the same door, for the same reason: only the object holds the
  // field map the pointer resolves against.
  refuseNonPictureImageField(object.name, object.imageField, object.fields, ctx);
});

/**
 * [#14935] Is `publicSharing` switched ON for this object schema?
 *
 * The ONE reading of the standing switch declared in the `publicSharing` block
 * above, exported here beside the declaration so that every surface gating on
 * it asks the same question. Two packages read it today — the share-link
 * service and the route probe above it (`@objectstack/plugin-sharing`), and the
 * `/share-links` dispatcher domain (`@objectstack/runtime`) — and the second
 * carried a documented copy of this expression, because the plugin is only a
 * DEV dependency of the runtime. That copy was never structurally forced: both
 * packages already depend on THIS one, so the shared home existed all along.
 * One policy read spelled twice, held equal by a comment and by two pins, is a
 * contract defect even while the two spellings agree.
 *
 * Fail-CLOSED, and the three unreadable cases are ONE answer, `false`: an absent
 * `publicSharing` block, an absent schema, and an engine that cannot answer
 * `getSchema` at all. `enabled` defaults to off, so a surface that cannot read
 * the policy must refuse rather than answer from the share-link row — a
 * distinguishable "sharing is off for this object" is an existence oracle for a
 * caller holding nothing but a token. Only the boolean `true` enables: the
 * strict comparison is deliberate, so a truthy `'true'` or `1` that never went
 * through this schema does not publish records.
 *
 * The same shape as {@link isTenancyDisabled} — an object posture the spec owns
 * precisely because more than one package must not re-derive it independently.
 */
export function isPublicSharingEnabled(schema: unknown): boolean {
  return (schema as { publicSharing?: { enabled?: unknown } } | null | undefined)
    ?.publicSharing?.enabled === true;
}

/**
 * Converts a snake_case name to a human-readable Title Case label.
 * @example snakeCaseToLabel('project_task') → 'Project Task'
 */
function snakeCaseToLabel(name: string): string {
  return name
    .split('_')
    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
    .join(' ');
}

/** Levenshtein edit distance — backs the "did you mean" hint for typo'd keys. */
function editDistance(a: string, b: string): number {
  const dp: number[][] = Array.from({ length: a.length + 1 }, () =>
    new Array<number>(b.length + 1).fill(0),
  );
  for (let i = 0; i <= a.length; i++) dp[i][0] = i;
  for (let j = 0; j <= b.length; j++) dp[0][j] = j;
  for (let i = 1; i <= a.length; i++) {
    for (let j = 1; j <= b.length; j++) {
      dp[i][j] = a[i - 1] === b[j - 1]
        ? dp[i - 1][j - 1]
        : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
    }
  }
  return dp[a.length][b.length];
}

/** Closest known key within a small edit distance, for typo hints (`indexs` → `indexes`). */
function suggestKey(unknown: string, knownKeys: string[]): string | undefined {
  let best: string | undefined;
  let bestDist = Infinity;
  for (const key of knownKeys) {
    const d = editDistance(unknown.toLowerCase(), key.toLowerCase());
    if (d < bestDist) {
      bestDist = d;
      best = key;
    }
  }
  // Only suggest when the keys are genuinely close (guards against noise).
  return best !== undefined && bestDist <= Math.max(2, Math.floor(unknown.length / 3))
    ? best
    : undefined;
}

/**
 * Builds a precise, fixable error for unknown top-level keys on
 * `ObjectSchema.create()` — the metadata-shape analogue of ADR-0032's "no
 * silent failure" (issue #1535). Because authored `*.object.ts` modules call
 * `create()`, this surfaces as a located build error instead of a silently
 * stripped field.
 */
function unknownKeyError(objectName: unknown, unknownKeys: string[], knownKeys: string[]): Error {
  const name = typeof objectName === 'string' && objectName.length > 0 ? objectName : '<unnamed>';
  const lines = unknownKeys.map((key) => {
    const guidance = UNKNOWN_KEY_GUIDANCE[key];
    if (guidance) return `  • ${guidance}`;
    const suggestion = suggestKey(key, knownKeys);
    return suggestion
      ? `  • \`${key}\` is not an ObjectSchema field — did you mean \`${suggestion}\`?`
      : `  • \`${key}\` is not an ObjectSchema field.`;
  });
  return new Error(
    `ObjectSchema.create('${name}'): unknown key(s) — ${unknownKeys.join(', ')}.\n` +
    'These keys would previously have been stripped silently at build, shipping ' +
    'dead metadata with no diagnostic (ADR-0032 "no silent failure").\n\n' +
    `${lines.join('\n')}\n\n` +
    'Remove the unknown key(s), fix the typo, or move the logic to a supported mechanism.',
  );
}

/**
 * Rejects excess top-level keys at compile time: any key of `T` that is not a
 * key of the ObjectSchema input shape is constrained to `never`, turning the
 * silent strip into a `tsc` error at the authoring site as well as at build.
 */
type NoExcessObjectKeys<T> = T &
  Record<Exclude<keyof T, keyof z.input<typeof ObjectSchemaBase>>, never> &
  NoExcessNestedActionParams<T>;

/**
 * [#12615] Extends the compile-time excess-key rejection one level DOWN, to the
 * action-param literals nested inside `actions[].params[]`.
 *
 * Why the top-level trick alone does not reach them: `create()` infers `T`
 * from the argument itself, so the argument always matches `T` exactly and
 * TypeScript's excess-property (freshness) checking never fires — at any
 * depth. {@link NoExcessObjectKeys} compensates at the top level by mapping
 * every non-schema key to `never`; nested literals had no such map, so a
 * typo'd param key (measured 2026-08-26: `carryOverX` on
 * `sys-permission-set.object.ts`) sailed through `tsc` and was caught only by
 * `ActionParamSchema`'s strict parse at module load. This mirrors the same
 * map over each element of each action's `params` array, turning the typo
 * into a located compile error at the authoring site.
 *
 * Compile-layer signal only — the strict parse at module load remains the
 * enforcement of record; nothing here changes what parses or when.
 */
type NoExcessNestedActionParams<T> =
  T extends { actions: infer As extends readonly unknown[] }
    ? { actions: { [I in keyof As]: NoExcessActionParams<As[I]> } }
    : unknown;

/** Maps one action literal: constrain each of its `params` entries, if any. */
type NoExcessActionParams<A> =
  A extends { params: infer Ps extends readonly unknown[] }
    ? A & { params: { [I in keyof Ps]: NoExcessActionParamKeys<Ps[I]> } }
    : A;

/** One action-param literal: every key outside `ActionParam` becomes `never`. */
type NoExcessActionParamKeys<P> = P &
  Record<Exclude<keyof P, keyof ActionParam>, never>;

/** Object names already warned about a generic `password` field (dedup per name). */
const warnedPasswordObjects = new Set<string>();

/**
 * Non-fatal author-time diagnostic (ADR-0100): a `password`-typed field on a
 * generic (non-`better-auth`) object gets defined-but-surprising semantics —
 * masked-on-read but **plaintext at rest**, with no one-way hashing (that lives
 * only in the auth subsystem). Steer authors to `secret` for reversible machine
 * credentials, or to the auth subsystem for real login credentials.
 *
 * A warning, not an error: `password` now has a defined generic-path contract,
 * and the field-zoo example intentionally exercises every field type — a hard
 * error would be self-inflicted breakage. Deduped per object name so a schema
 * imported many times warns once. Objects whose `managedBy` exempts `password`
 * from the read mask are exempt (today `better-auth`), as are fields that opt in
 * with `ackPlaintextMasking: true` — the author's explicit "this is intended"
 * acknowledgment (#3420), which lets a deliberate demo/design (e.g. the showcase
 * field-zoo) start with zero warnings.
 *
 * [#20141] The exemption is READ from the masked-on-read declaration
 * (`MASKED_ON_READ_FIELD_TYPES`, via `isMaskedOnReadFieldType`), never restated:
 * the warning describes a `password` that is masked on read yet plaintext at
 * rest, so it fires exactly where the read mask applies to `password`. If that
 * declaration's `exemptManagedBy` changes, this warning follows it. ⛔ Not
 * widened to `secret` — a `secret` is encrypted at rest, which is the whole
 * point of steering authors to it.
 */
function warnGenericPasswordFields(
  objectName: unknown,
  fields: unknown,
  managedBy: unknown,
): void {
  if (!isMaskedOnReadFieldType('password', managedBy)) return;
  if (!fields || typeof fields !== 'object') return;
  const passwordFields = Object.entries(
    fields as Record<string, { type?: string; ackPlaintextMasking?: boolean }>,
  )
    .filter(([, def]) => def && def.type === 'password' && def.ackPlaintextMasking !== true)
    .map(([fieldName]) => fieldName);
  if (passwordFields.length === 0) return;
  const name = typeof objectName === 'string' && objectName.length > 0 ? objectName : '<unnamed>';
  if (warnedPasswordObjects.has(name)) return;
  warnedPasswordObjects.add(name);
  console.warn(
    `ObjectSchema.create('${name}'): field(s) ${passwordFields.map((f) => `\`${f}\``).join(', ')} ` +
    "use type 'password' on a non-auth object. The generic CRUD path stores a " +
    'password field as plaintext at rest and masks it to •••••••• on read (ADR-0100) — ' +
    'it is NOT one-way hashed (that is owned by the auth subsystem, for its identity ' +
    "tables only). Use `Field.secret(...)` for reversible machine credentials, or model " +
    'login credentials on the auth user object. If this is intended, the masking contract ' +
    'applies — affirm it with `ackPlaintextMasking: true` on the field to silence this warning.',
  );
}

/**
 * [#3355] Authoring-time refusal for the ONE way `system-data` can be
 * mis-assigned: declaring it on an object that grants no user write at all.
 *
 * The v17 rename fixed a name that lied. This keeps it from lying again. The two
 * halves of `system-data` are "platform-defined SCHEMA" and "admin/user-writable
 * DATA"; an object whose resolved affordances forbid create AND edit AND delete
 * satisfies the first half and contradicts the second, and the value it is
 * actually describing is `engine-owned` (or `append-only` for an audit log).
 * That contradiction is fully computable from the declaration alone — no call
 * graph needed — so it is refused rather than reviewed.
 *
 * This matters more under the v17 defaults than it would have under v16. `system`
 * defaulted LOCKED, so a mislabelled engine-owned object inherited a harmless
 * read-only matrix; `system-data` defaults WRITABLE, so the same mistake now
 * hands a table generic CRUD affordances it should never advertise. The write
 * guard does not cover `system-data` (nothing to fail closed on when the default
 * grants the write), so authoring time is the only place this can be caught —
 * hence a throw, not a `console.warn`.
 *
 * Threshold is "no write verb at all", not "any narrowing": `system-data` +
 * `userActions: { create: false, delete: false }` (an editable-only config grid)
 * is a legitimate NARROW and passes. Only the all-writes-false shape is a
 * contradiction, and it has no honest reading.
 *
 * Lives at `create()` — the authoring surface (ADR-0077) — alongside
 * {@link warnGenericPasswordFields}, rather than in raw `.parse()`: stored rows
 * arriving through the protocol-17 conversion are a 1:1 rename of values that
 * were already writable, and failing a LOAD on metadata already at rest would
 * turn an authoring defect into an outage.
 */
function assertSystemDataIsWritable(
  objectName: unknown,
  managedBy: unknown,
  userActions: unknown,
): void {
  if (managedBy !== 'system-data') return;
  const aff = resolveCrudAffordances({ managedBy, userActions } as never);
  if (aff.create || aff.edit || aff.delete) return;
  const name = typeof objectName === 'string' && objectName.length > 0 ? objectName : '<unnamed>';
  throw new Error(
    `ObjectSchema.create('${name}'): \`managedBy: 'system-data'\` declares "platform-defined `
    + 'schema, admin/user-writable DATA", but this object\'s resolved affordances grant no '
    + 'create, edit or delete — so nothing about it is user-writable and the bucket name is '
    + 'false. Use `managedBy: \'engine-owned\'` for rows a platform service owns end to end '
    + '(written via `isSystem` / a service SYSTEM_CTX), or `append-only` for an immutable '
    + 'audit log. If the object IS user-writable, drop the `userActions` entries closing '
    + 'create/edit/delete — the `system-data` default already grants create, edit, delete and '
    + 'exportCsv, so `userActions` is for NARROWING those. The one verb it does not '
    + 'grant is CSV `import`, which is opt-in per object.',
  );
}

/**
 * [#11339] A field's `referenceVia` must name a DECLARED sibling field —
 * the type half of a polymorphic pointer pair (ADR-0052 §5; `record_id` with
 * `referenceVia: 'object_name'` on `sys_activity` is the canonical pair).
 *
 * Why here: `FieldSchema` sees one field at a time, so "the sibling exists"
 * is only checkable at the object level. A pointer whose declared sibling is
 * missing can never resolve — every seed row would fail at load time with a
 * per-row error, far from the one-line declaration mistake that caused it.
 * Refusing at `create()` puts the error where the fix is.
 *
 * Lives at `create()` — the authoring surface (ADR-0077) — beside
 * {@link assertSystemDataIsWritable}, and deliberately NOT in raw
 * `.parse()`/`.safeParse()`: metadata already at rest must keep loading; the
 * seed loader independently reports an un-addressable pointer per row.
 */
function assertReferenceViaSiblingDeclared(objectName: unknown, fields: unknown): void {
  if (fields === null || typeof fields !== 'object') return;
  const name = typeof objectName === 'string' && objectName.length > 0 ? objectName : '<unnamed>';
  const fieldMap = fields as Record<string, { referenceVia?: unknown } | undefined>;
  for (const [fieldName, fieldDef] of Object.entries(fieldMap)) {
    const via = fieldDef?.referenceVia;
    if (typeof via !== 'string') continue;
    if (via === fieldName) {
      throw new Error(
        `ObjectSchema.create('${name}'): field "${fieldName}" declares \`referenceVia: '${via}'\` — `
        + 'pointing at ITSELF. `referenceVia` names the sibling field that holds the target OBJECT '
        + "machine name (the type half of the pointer pair), e.g. `record_id` with `referenceVia: "
        + "'object_name'`; a field cannot be both halves.",
      );
    }
    if (!Object.prototype.hasOwnProperty.call(fieldMap, via)) {
      throw new Error(
        `ObjectSchema.create('${name}'): field "${fieldName}" declares \`referenceVia: '${via}'\`, but `
        + `this object declares no field named "${via}". \`referenceVia\` names the sibling field that `
        + 'holds the target object machine name per row (ADR-0052 §5 pointer pair) — declare that '
        + `sibling, or fix the spelling. Declared fields: ${Object.keys(fieldMap).join(', ')}.`,
      );
    }
  }
}

/**
 * [#9138 — commit 75b7c240a, maintainer ruling Direction 2 / ADR-0055] Under
 * `sharingModel: 'controlled_by_parent'` the builder FORCES `required: true`
 * on every `master_detail` reference, and REFUSES an explicit
 * `required: false` there, loudly.
 *
 * Why: a `controlled_by_parent` detail's access is *derived* from its master
 * through that reference (the `sharingModel` docblock above already states
 * "exactly one required `master_detail` field"). A non-required master
 * reference arms the worst measured failure shape: an insert may omit the
 * master FK, the row lands with a null FK, the derived read filter
 * `masterFK IN (accessible master ids)` can never match null — the row is
 * invisible to everyone — and every later by-id write answers
 * `422 MISSING_REQUIRED_FIELD`. Today only the security gate
 * (`assertControlledByParentWrite`) closes that shape, and commit 75b7c240a records that
 * the declaration and the enforcement disagree. This makes the unsafe shape
 * impossible to NEWLY declare:
 *
 * - omitted `required` → forced to `true` (the lint rule
 *   `relationship/master-detail-required` already computes exactly this fix);
 * - explicit `required: false` → refused with a located error — the author
 *   wrote a contradiction, and silently flipping an explicitly authored value
 *   would hide it (ADR-0032 "no silent failure").
 *
 * Lives at `create()` — the authoring surface (ADR-0077) — beside
 * {@link assertSystemDataIsWritable}, and deliberately NOT in raw
 * `.parse()`/`.safeParse()`: metadata already at rest must keep loading.
 * Runtime tolerance is the other half of commit 75b7c240a's ruling — the security
 * gate's fallbacks stay, and the lint rule stays `warning` until v18 — so
 * publish-time refuses new declarations while runtime tolerates old ones.
 *
 * Alias spellings (`isRequired` / `mandatory` / `notNull`) need no handling
 * here: `FieldSchema` is a `strictObject`, so those keys are refused at parse
 * with a rename suggestion — they can never land a `required: false` this
 * check would miss. A non-boolean `required` is left for Zod to report as the
 * real type error.
 */
function forceCbpMasterDetailRequired(
  objectName: unknown,
  sharingModel: unknown,
  fields: unknown,
): unknown {
  if (sharingModel !== 'controlled_by_parent') return fields;
  if (!fields || typeof fields !== 'object' || Array.isArray(fields)) return fields;
  let out: Record<string, unknown> | undefined;
  for (const [fieldName, def] of Object.entries(fields as Record<string, unknown>)) {
    if (!def || typeof def !== 'object' || Array.isArray(def)) continue;
    const field = def as Record<string, unknown>;
    if (field.type !== 'master_detail') continue;
    if (field.required === true) continue;
    if (field.required === false) {
      const name = typeof objectName === 'string' && objectName.length > 0 ? objectName : '<unnamed>';
      throw new Error(
        `ObjectSchema.create('${name}'): field \`${fieldName}\` declares \`required: false\` on a `
        + "`master_detail` reference under `sharingModel: 'controlled_by_parent'` — a contradiction "
        + 'with no honest reading. A controlled-by-parent detail derives ALL of its record '
        + 'access from the master this field names (ADR-0055); a row allowed to omit the master FK '
        + 'is unreadable by everyone (the derived filter `masterFK IN (accessible master ids)` '
        + 'never matches null) and unwritable thereafter. Remove `required: false` (the builder '
        + 'declares the reference required by construction), or if this object is not a '
        + 'master-detail child, change its `sharingModel`.',
      );
    }
    if (field.required !== undefined) continue;
    out ??= { ...(fields as Record<string, unknown>) };
    out[fieldName] = { ...field, required: true };
  }
  return out ?? fields;
}

/**
 * [ADR-0079] Back-compat alias normalization: an object authored with the
 * deprecated `displayNameField` key still parses by mapping it onto the
 * canonical `nameField` when `nameField` is absent. `displayNameField` is
 * PRESERVED on the output (cross-repo consumers / older tests still read it).
 * Non-object inputs pass through untouched (Zod raises the real type error).
 */
function normalizeNameFieldAlias(input: unknown): unknown {
  if (!input || typeof input !== 'object' || Array.isArray(input)) return input;
  const obj = input as Record<string, unknown>;
  if (obj.nameField == null && typeof obj.displayNameField === 'string') {
    return { ...obj, nameField: obj.displayNameField };
  }
  return input;
}

/**
 * [ADR-0085] Parse-time alias normalization for the semantic-role renames
 * (same pattern as `normalizeNameFieldAlias`; deprecated keys are PRESERVED
 * on output for cross-repo back-compat):
 *
 * - (`compactLayout` ⇄ `highlightFields` mirrored here during the ADR-0085
 *   deprecation window; RETIRED by framework#2536 once objectui#2168 shipped.)
 * - `fieldGroups[].collapse` derived from the deprecated flags when absent:
 *   the UI-dialect `collapsible`/`collapsed` pair wins over the old
 *   `defaultExpanded` (it is what designer-authored metadata actually
 *   carries); mapping: collapsed:true → 'collapsed'; collapsible:true →
 *   'expanded'; collapsible:false → 'none'; defaultExpanded:false →
 *   'collapsed'; defaultExpanded:true → 'expanded'.
 */
function normalizeSemanticRoleAliases(input: unknown): unknown {
  if (!input || typeof input !== 'object' || Array.isArray(input)) return input;
  const obj = input as Record<string, unknown>;
  let out = obj;

  if (Array.isArray(obj.fieldGroups)) {
    let changed = false;
    const groups = (obj.fieldGroups as unknown[]).map((g) => {
      if (!g || typeof g !== 'object' || Array.isArray(g)) return g;
      const grp = g as Record<string, unknown>;
      if (grp.collapse != null) return g;
      let collapse: string | undefined;
      if (typeof grp.collapsible === 'boolean' || typeof grp.collapsed === 'boolean') {
        collapse = grp.collapsed === true ? 'collapsed' : grp.collapsible === true ? 'expanded' : 'none';
      } else if (typeof grp.defaultExpanded === 'boolean') {
        collapse = grp.defaultExpanded ? 'expanded' : 'collapsed';
      }
      if (collapse === undefined) return g;
      changed = true;
      return { ...grp, collapse };
    });
    if (changed) out = { ...out, fieldGroups: groups };
  }

  return out;
}

/**
 * Enhanced ObjectSchema with Factory
 */
export const ObjectSchema = lazySchema(() => {
  // Capture the ORIGINAL ZodObject parse/safeParse before `Object.assign`
  // mutates `ObjectSchemaBase` in place (assign returns the same object, so
  // overriding `.parse` on the result would otherwise recurse into itself).
  const baseParse = ObjectSchemaBase.parse.bind(ObjectSchemaBase);
  const baseSafeParse = ObjectSchemaBase.safeParse.bind(ObjectSchemaBase);
  return Object.assign(ObjectSchemaBase, {
  /**
   * [ADR-0079] Parse with deprecated-`displayNameField`→`nameField` alias
   * normalization applied first. Wraps the captured original ZodObject parse,
   * so `.shape` / `.create()`'s internal `ObjectSchemaBase.parse` keep working.
   */
  parse(data: unknown, params?: Parameters<typeof ObjectSchemaBase.parse>[1]) {
    return baseParse(normalizeSemanticRoleAliases(normalizeNameFieldAlias(data)), params);
  },
  safeParse(data: unknown, params?: Parameters<typeof ObjectSchemaBase.safeParse>[1]) {
    return baseSafeParse(normalizeSemanticRoleAliases(normalizeNameFieldAlias(data)), params);
  },
  /**
   * Type-safe factory for creating business object definitions.
   * 
   * Enhancements over raw schema:
   * - **Auto-label**: Generates `label` from `name` if not provided (snake_case → Title Case).
   * - **Validation**: Runs Zod `.parse()` to validate the config at creation time.
   * - **No silent strip** (ADR-0032 / #1535): unknown top-level keys (e.g. a
   *   typo'd `validation`, or an object-level `workflows[]`) are rejected with a
   *   precise, fixable error instead of being discarded by Zod's `.strip()`.
   *
   * @example
   * ```ts
   * const Task = ObjectSchema.create({
   *   name: 'project_task',
   *   // label auto-generated as 'Project Task'
   *   fields: {
   *     subject: { type: 'text', label: 'Subject', required: true },
   *   },
   * });
   * ```
   */
  create: <const T extends z.input<typeof ObjectSchemaBase>>(config: NoExcessObjectKeys<T>): Omit<ServiceObject, 'fields'> & Pick<T, 'fields'> => {
    // ADR-0032 "no silent failure" for schema shape (issue #1535): an unknown
    // top-level key here used to be discarded silently by Zod's `.strip()`. We
    // reject it with a located, fixable message *before* parsing so authors get
    // a build error instead of vanished metadata.
    const cfg = config as T & Record<string, unknown>;
    const knownKeys = Object.keys(ObjectSchemaBase.shape);
    const unknownKeys = Object.keys(cfg).filter((k) => !knownKeys.includes(k));
    if (unknownKeys.length > 0) {
      throw unknownKeyError(cfg.name, unknownKeys, knownKeys);
    }
    // ADR-0100: warn (non-fatally) when a `password` field is declared on a
    // generic, non-better-auth object — it is masked-on-read but plaintext at
    // rest, not hashed. `create()` is the authoring surface (ADR-0077), so the
    // steer lives here rather than in raw `.parse()`.
    warnGenericPasswordFields(cfg.name, cfg.fields, cfg.managedBy);
    // [#3355] `system-data` on an object that grants no user write is a
    // contradiction with no honest reading — refuse it here, where it is cheap
    // to fix, rather than shipping a bucket whose name lies again.
    assertSystemDataIsWritable(cfg.name, cfg.managedBy, cfg.userActions);
    // [#11339] A `referenceVia` pointer pair whose type-half sibling is not
    // declared can never resolve — refuse at the authoring seam, beside its
    // sibling assertions, rather than one error per seeded row at load time.
    assertReferenceViaSiblingDeclared(cfg.name, cfg.fields);
    // [#9138 — commit 75b7c240a, ruling Direction 2] A `controlled_by_parent` object's
    // `master_detail` reference is forced `required: true` (an explicit
    // `required: false` throws, loudly) so the unsafe shape cannot be newly
    // declared. Raw `.parse()`/`.safeParse()` stay tolerant for metadata at
    // rest — see the function's docblock.
    const forcedFields = forceCbpMasterDetailRequired(cfg.name, cfg.sharingModel, cfg.fields);
    const withDefaults = {
      ...cfg,
      ...(forcedFields === cfg.fields ? {} : { fields: forcedFields }),
      label: cfg.label ?? snakeCaseToLabel(cfg.name as string),
    };
    // [ADR-0079] `ObjectSchemaBase.parse` here is the alias-normalizing override
    // assigned just below (Object.assign mutates the base in place), so the
    // deprecated `displayNameField`→`nameField` mapping is applied for create()
    // too — no need to normalize again at this call site.
    return ObjectSchemaBase.parse(withDefaults) as Omit<ServiceObject, 'fields'> & Pick<T, 'fields'>;
  },
  });
});

export type ServiceObject = z.input<typeof ObjectSchemaBase>;
/** Post-parse shape of {@link ServiceObject} — defaults applied, transforms run (ADR-0122). */
export type ServiceObjectParsed = z.infer<typeof ObjectSchemaBase>;
export type ObjectCapabilities = z.input<typeof ObjectCapabilities>;
/** Post-parse shape of {@link ObjectCapabilities} — defaults applied, transforms run (ADR-0122). */
export type ObjectCapabilitiesParsed = z.infer<typeof ObjectCapabilities>;
export type ObjectIndex = z.input<typeof IndexSchema>;
/** Post-parse shape of {@link ObjectIndex} — defaults applied, transforms run (ADR-0122). */
export type ObjectIndexParsed = z.infer<typeof IndexSchema>;
export type TenancyConfig = z.input<typeof TenancyConfigSchema>;
export type ObjectAccessConfig = z.input<typeof ObjectAccessConfigSchema>;
/** Post-parse shape of {@link ObjectAccessConfig} — defaults applied, transforms run (ADR-0122). */
export type ObjectAccessConfigParsed = z.infer<typeof ObjectAccessConfigSchema>;
export type LifecycleClass = z.input<typeof LifecycleClassSchema>;
export type Lifecycle = z.input<typeof LifecycleSchema>;

/**
 * Resolved CRUD affordance matrix for an object — what generic
 * lifecycle actions UI clients should expose in their toolbars.
 *
 * Use {@link resolveCrudAffordances} to compute this from a schema; the
 * `managedBy` flag drives the defaults, and the optional `userActions`
 * block per-flag-overrides them. UI clients (`ObjectView`,
 * `RecordDetailView`, `RecordFormPage`, …) gate their buttons on this
 * matrix in combination with the user's permissions.
 *
 * The presence of an affordance here means "the *object* permits this
 * action conceptually"; the user still needs the matching permission
 * grant to execute it.
 */
export interface CrudAffordances {
  /** Generic "New" button (single record creation form). */
  create: boolean;
  /**
   * CSV bulk-import wizard. `platform` is the only bucket that grants it by
   * default; every other bucket — `config`, `system-data`, `engine-owned`,
   * `append-only`, `better-auth` — makes it opt-in via
   * `userActions: { import: true }`.
   */
  import: boolean;
  /** Inline + form editing of existing rows. */
  edit: boolean;
  /** Row-level + bulk delete. */
  delete: boolean;
  /** CSV / clipboard export. Allowed even on append-only audit tables by default. */
  exportCsv: boolean;
  /**
   * Per-record CEL predicates for the built-in row Edit action, present only
   * when `userActions.edit` used the object form (objectui#2614). Evaluate
   * per row against `record.*`; see {@link RowCrudActionOverrideSchema}.
   */
  editPredicates?: RowCrudPredicates;
  /** Per-record CEL predicates for the built-in row Delete action. */
  deletePredicates?: RowCrudPredicates;
  /**
   * CEL predicates for the generic New button, present only when
   * `userActions.create` used the object form (#7692). Unlike the row
   * predicates above these evaluate **once per toolbar**, against the record
   * in scope where the toolbar renders — the host record on a related list,
   * and nothing at all on a standalone object list. See
   * {@link RowCrudActionOverrideSchema}.
   */
  createPredicates?: RowCrudPredicates;
  /** Toolbar-scope CEL predicates for the CSV import entry; same binding as {@link createPredicates}. */
  importPredicates?: RowCrudPredicates;
}

/**
 * Per-record gating predicates carried through {@link resolveCrudAffordances}.
 * Kept as authored (`string` shorthand or `{ dialect, source }` envelope) —
 * consumers hand them to the canonical CEL row-predicate evaluator untouched.
 */
export interface RowCrudPredicates {
  visibleWhen?: EvaluatedExpression | EvaluatedExpressionInput;
  disabledWhen?: EvaluatedExpression | EvaluatedExpressionInput;
}

/**
 * Default affordance matrix per {@link ObjectSchemaBase.managedBy} bucket.
 * Mirrors how Salesforce / ServiceNow / Workday / Notion expose CRUD on
 * different categories of system tables.
 *
 *   platform     — full CRUD (user-owned business data)
 *   config       — admin authored: New/Edit/Delete OK, no CSV import
 *                  (definitions have nested envelopes; admins should use
 *                  a purpose-built "Import definition" action instead)
 *   system-data  — platform-defined schema holding admin/user-writable data
 *                  (RBAC link tables, prefs, messaging config). DEFAULT is
 *                  WRITABLE — the bucket exists to say "the data is yours" —
 *                  and an object that takes less NARROWS via `userActions`.
 *                  The ONE exception is CSV import, which is opt-IN here:
 *                  the bucket's charter members are the RBAC link tables, and
 *                  a bulk-import entry point on a grant table is a lever a
 *                  bucket default should not hand out by inheritance (#4671).
 *                  An object that genuinely wants the wizard writes
 *                  `userActions: { import: true }`.
 *                  Affordance declaration only; authz stays the delegated-admin
 *                  gate / RLS / permission sets (ADR-0103, renamed from the
 *                  locked-default `system` in v17 — #3355)
 *   engine-owned — runtime rows the engine owns end to end; no user writes.
 *                  The explicit, self-documenting successor to the old
 *                  engine-owned DEFAULT of `system`
 *   append-only  — audit log: View + Export only
 *   better-auth  — identity tables owned by better-auth driver; CRUD
 *                  routed through purpose-built actions (Invite, Reset
 *                  PW, Revoke, …)
 */
const CRUD_AFFORDANCE_DEFAULTS: Record<NonNullable<ServiceObject['managedBy']> | 'platform', CrudAffordances> = {
  platform:       { create: true,  import: true,  edit: true,  delete: true,  exportCsv: true },
  config:         { create: true,  import: false, edit: true,  delete: true,  exportCsv: true },
  'system-data':  { create: true,  import: false, edit: true,  delete: true,  exportCsv: true },
  'engine-owned': { create: false, import: false, edit: false, delete: false, exportCsv: true },
  'append-only':  { create: false, import: false, edit: false, delete: false, exportCsv: true },
  'better-auth':  { create: false, import: false, edit: false, delete: false, exportCsv: true },
};

/**
 * Resolve the effective CRUD affordance matrix for an object schema.
 *
 * Starts from the bucket default keyed off `managedBy` (defaulting to
 * `'platform'` if unset) and applies the per-flag overrides in
 * `userActions`. Returns a fresh object so callers can mutate safely.
 *
 * @example
 * ```ts
 * const aff = resolveCrudAffordances(sysApprovalRequestSchema);
 * // → { create:false, import:false, edit:false, delete:false, exportCsv:true }
 * ```
 */
export function resolveCrudAffordances(
  obj: Pick<ServiceObject, 'managedBy' | 'userActions'> | { managedBy?: string; userActions?: ServiceObject['userActions'] },
): CrudAffordances {
  const bucket = (obj?.managedBy ?? 'platform') as keyof typeof CRUD_AFFORDANCE_DEFAULTS;
  const base = CRUD_AFFORDANCE_DEFAULTS[bucket] ?? CRUD_AFFORDANCE_DEFAULTS.platform;
  const overrides = obj?.userActions ?? {};
  const create = normalizeRowCrudOverride(overrides.create, base.create);
  const imp = normalizeRowCrudOverride(overrides.import, base.import);
  const edit = normalizeRowCrudOverride(overrides.edit, base.edit);
  const del = normalizeRowCrudOverride(overrides.delete, base.delete);
  const out: CrudAffordances = {
    create:    create.enabled,
    import:    imp.enabled,
    edit:      edit.enabled,
    delete:    del.enabled,
    exportCsv: overrides.exportCsv ?? base.exportCsv,
  };
  if (create.predicates) out.createPredicates = create.predicates;
  if (imp.predicates) out.importPredicates = imp.predicates;
  if (edit.predicates) out.editPredicates = edit.predicates;
  if (del.predicates) out.deletePredicates = del.predicates;
  return out;
}

/**
 * Collapse a `userActions` CRUD override — bare boolean or
 * `{ enabled, visibleWhen, disabledWhen }` object — onto the bucket default.
 * The predicates pass through as authored; `predicates` is only set when at
 * least one predicate is present, so the boolean-only path stays
 * byte-identical to the pre-#2614 result. Shared by all four predicate-
 * carrying flags: `edit`/`delete` (per row) and `create`/`import` (per
 * toolbar, #7692) — the collapse is the same, only the binding differs.
 */
function normalizeRowCrudOverride(
  override: boolean | { enabled?: boolean; visibleWhen?: unknown; disabledWhen?: unknown } | null | undefined,
  base: boolean,
): { enabled: boolean; predicates?: RowCrudPredicates } {
  if (override == null) return { enabled: base };
  if (typeof override === 'boolean') return { enabled: override };
  const enabled = override.enabled ?? base;
  const visibleWhen = override.visibleWhen as RowCrudPredicates['visibleWhen'];
  const disabledWhen = override.disabledWhen as RowCrudPredicates['disabledWhen'];
  if (visibleWhen == null && disabledWhen == null) return { enabled };
  const predicates: RowCrudPredicates = {};
  if (visibleWhen != null) predicates.visibleWhen = visibleWhen;
  if (disabledWhen != null) predicates.disabledWhen = disabledWhen;
  return { enabled, predicates };
}

// =================================================================
// Object Ownership Model
// =================================================================

/**
 * How a contribution relates to the object it targets — the registry's
 * CONTRIBUTOR-kind vocabulary.
 * 
 * - `own`: This package is the original author/owner of the object.
 *   Only one package may own a given object name. The owner defines
 *   the base schema (table name, primary key, core fields).
 * 
 * - `overlay`: [ADR-0029 D9.1] A TENANT customization layer over the owner's
 *   definition, hydrated from a `sys_metadata` row. It REPLACES the base layer
 *   at resolution time (`base = overlay ?? own`) while owning nothing — no
 *   namespace claim, no package membership, no table — so the single-owner
 *   invariant keeps counting exactly one `own` per object name with no
 *   exemption clause.
 * 
 * - `extend`: This package adds fields, views, or actions to an
 *   existing object owned by another package. Multiple packages
 *   may extend the same object. Extensions are merged at boot time.
 * 
 * ## LOADER-FACING, NEVER AUTHOR-FACING
 * 
 * No author ever writes one of these values. A package author declares
 * `objectExtensions: [{ extend: '…' }]` and the LOADER picks `extend`; the
 * package loader picks `own`; ADR-0029 D9.1 binds `overlay` to the two
 * `sys_metadata` hydration seams and to nothing else. This enum is the shared
 * vocabulary those loaders name their choice with — not an authoring surface —
 * and D9.1 binds it to stay that way, because a new kind that no hand-written
 * or AI-written metadata can reach for adds no way to get metadata wrong.
 * 
 * NOTE: this is the package-CONTRIBUTION kind, DISTINCT from the RECORD
 * -ownership model (`user` | `org` | `none`) that lives on the object schema's
 * own `ownership` property — do not conflate the two despite the shared word.
 * 
 * Follows Salesforce/ServiceNow patterns:
 *   object name = database table name, globally unique, no namespace prefix.
 */
export const ObjectOwnershipEnum = z.enum(['own', 'extend', 'overlay']);
export type ObjectOwnership = z.input<typeof ObjectOwnershipEnum>;

/**
 * Object Extension Entry — used in `objectExtensions` array.
 * Declares fields/config to merge into an existing object owned by another package.
 * 
 * @example
 * ```ts
 * objectExtensions: [{
 *   extend: 'contact',               // target object FQN
 *   fields: { sales_stage: Field.select([...]) },
 * }]
 * ```
 */
export const ObjectExtensionSchema = lazySchema(() => strictObject({
  surface: 'this object extension',
  history:
    'Until this shape was closed, these were dropped silently — the extension still parsed and still ' +
    'registered, so fields or rules an author meant to merge into someone else\'s object ' +
    'simply never arrived, on a surface where the target is owned by another package and ' +
    'the absence is easy to blame on precedence.',
  aliases: {
    object: 'extend',
    objectName: 'extend',
    target: 'extend',
    name: 'extend',
    extends: 'extend',
    order: 'priority',
  },
  guidance: {
    // The merge in `objectql/src/engine.ts` copies EXACTLY the declared keys
    // (extend / fields / label / pluralLabel / description / validations /
    // indexes / priority) onto the extension def. Anything else is not
    // "unsupported yet" — there is no slot for it to arrive through.
    actions:
      '`actions` cannot be contributed through an object extension — the merge carries ' +
      '`fields`, `label`, `pluralLabel`, `description`, `validations` and `indexes` only. ' +
      "Declare a top-level action with `objectName: '<target>'`; `defineStack()` attaches " +
      'it to the object.',
    hooks:
      '`hooks` cannot be contributed through an object extension — declare a top-level ' +
      'hook bound to the target object instead.',
    listViews:
      '`listViews` cannot be contributed through an object extension — declare a ' +
      'top-level `view` bound to the target object instead.',
    fieldGroups:
      '`fieldGroups` cannot be contributed through an object extension — the merge does ' +
      'not carry them. Add the fields here and declare the groups on the owning object, ' +
      'or assign a Page for the layout.',
  },
}, {
  /** The target object name (FQN) to extend */
  extend: z.string().describe('Target object name (FQN) to extend'),
  
  /** Fields to merge into the target object (additive) */
  fields: z.record(z.string(), FieldSchema).optional().describe('Fields to add/override'),
  
  /** Override label */
  label: z.string().optional().describe('Override label for the extended object'),
  
  /** Override plural label */
  pluralLabel: z.string().optional().describe('Override plural label for the extended object'),
  
  /** Override description */
  description: z.string().optional().describe('Override description for the extended object'),
  
  /** Additional validation rules to add */
  validations: z.array(ValidationRuleSchema).optional().describe('Additional validation rules to merge into the target object'),
  
  /** Additional indexes to add */
  indexes: z.array(IndexSchema).optional().describe('Additional indexes to merge into the target object'),
  
  /** Merge priority. Higher number applied later (wins on conflict). Default: 200 */
  priority: z.number().int().min(0).max(999).default(200).describe('Merge priority (higher = applied later)'),
}).superRefine((extension, ctx) => {
  // [#14892] The same rule as on `ObjectSchema`: the fields merge into
  // `extend`, so that is the object a `tree` field's `reference` must name.
  refuseForeignTreeReference(extension.extend, extension.fields, ctx);
}));

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

/**
 * Type-safe factory for an extension to an object owned by another package. Validates at authoring time via
 * `.parse()` and accepts input-shape config (optional defaults, CEL
 * shorthand) — preferred over a bare `: ObjectExtension` literal.
 */
export function defineObjectExtension(config: z.input<typeof ObjectExtensionSchema>): ObjectExtensionParsed {
  return ObjectExtensionSchema.parse(config);
}