protocol.zod.ts

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

import { z } from 'zod';
import { ViewSchema } from '../ui/view.zod';
import { I18nLabelSchema } from '../ui/i18n.zod';
import { DiscoverySchema } from './discovery.zod';
import {
  BatchUpdateRequestSchema,
  BatchUpdateResponseSchema,
  UpdateManyRequestSchema,
  DeleteManyRequestSchema,
} from './batch.zod';
import { MetadataCacheRequestSchema, MetadataCacheResponseSchema } from './http-cache.zod';
import { QUERY_DISTINCT_REMOVED } from '../data/query.zod';
import { retiredKey } from '../shared/retired-key';
// The closed list of refinements that reach the published JSON Schema (#18670
// item 2) — `UpdateAiConversationRequest`'s at-least-one rule is declared
// through it, so `api/UpdateAiConversationRequest.json` states it.
import { requiredOneOf } from '../shared/refinement-projection';
import { MetadataItemNameSchema } from '../shared/identifiers.zod';
import { DroppedFieldsEventSchema, QueryWithTransportSchema, ValidationAdvisoryEventSchema } from '../data/data-engine.zod';
import { 
  AnalyticsQueryRequestSchema,  
  AnalyticsResultResponseSchema, 
  GetAnalyticsMetaRequestSchema, 
  AnalyticsMetadataResponseSchema 
} from './analytics.zod';
import { RealtimePresenceSchema, TransportProtocol } from './realtime.zod';
import { ObjectPermissionSchema, EffectiveObjectPermissionSchema, FieldPermissionSchema } from '../security/permission.zod';
import { ActionDescriptorSchema } from '../automation/node-executor.zod';
import { PlatformTranslationDataSchema } from '../system/translation.zod';
// #5950 / #5882 — the ADR-0010 read-side protection envelope both metadata-item
// responses publish. Same three vocabularies the resolver filters against, so a
// value this spec cannot name is a value the resolver would have dropped.
import {
  MetadataLockSchema,
  MetadataLockSourceSchema,
  MetadataProvenanceSchema,
} from '../kernel/metadata-protection.zod';
import { MetadataValidationResultSchema } from '../kernel/metadata-plugin.zod';
// [#23183] The package-id grammar the app item read's package-id key is
// recognised by ({@link isAppPackageIdKey}) — its one declaration.
import { MANIFEST_ID_PATTERN } from '../kernel/manifest.zod';
// [#10235] The per-column sortability projection the object read serves on its
// envelope — computed at serve time, never authorable; see sortability.zod.ts.
import { ObjectSortabilitySchema } from './sortability.zod';
import {
  ListPackagesRequestSchema,
  ListPackagesResponseSchema,
  GetPackageRequestSchema,
  GetPackageResponseSchema,
  InstallPackageRequestSchema,
  InstallPackageResponseSchema,
  UninstallPackageRequestSchema,
  UninstallPackageResponseSchema,
  EnablePackageRequestSchema,
  EnablePackageResponseSchema,
  DisablePackageRequestSchema,
  DisablePackageResponseSchema,
} from '../kernel/package-registry.zod';
import type {
  ListPackagesRequest,
  ListPackagesResponse,
  GetPackageRequest,
  GetPackageResponse,
  InstallPackageRequest,
  InstallPackageResponse,
  UninstallPackageRequest,
  UninstallPackageResponse,
  EnablePackageRequest,
  EnablePackageResponse,
  DisablePackageRequest,
  DisablePackageResponse,
  InstalledPackage,
  PackageStatus,
} from '../kernel/package-registry.zod';

import { lazySchema } from '../shared/lazy-schema';
export const AutomationTriggerRequestSchema = lazySchema(() => z.object({
  trigger: z.string(),
  payload: z.record(z.string(), z.unknown())
}));

export const AutomationTriggerResponseSchema = lazySchema(() => z.object({
  success: z.boolean(),
  jobId: z.string().optional(),
  result: z.unknown().optional()
}));

/**
 * Response for `GET /api/v1/automation/actions` (ADR-0018).
 *
 * Returns the live action/node registry — the platform's built-in actions plus
 * any plugin-contributed ones — backing the designer palette and flow
 * validation. Each entry is a canonical {@link ActionDescriptorSchema}.
 */
export const AutomationActionsResponseSchema = lazySchema(() => z.object({
  actions: z.array(ActionDescriptorSchema).describe('Registered action descriptors (built-in + plugin)'),
  total: z.number().int().nonnegative().describe('Number of descriptors returned (after any filters)'),
}));

/**
 * ObjectStack Protocol - Zod Schema Definitions
 * 
 * Defines the runtime-validated contract for interacting with ObjectStack metadata and data.
 * Used by API adapters (HTTP, WebSocket, gRPC) to fetch data/metadata without knowing engine internals.
 * 
 * This protocol enables:
 * - Runtime request/response validation at API gateway level
 * - Automatic API documentation generation
 * - Type-safe RPC communication between microservices
 * - Client SDK generation from schemas
 * 
 * Architecture Alignment:
 * - Salesforce: REST API Request/Response schemas
 * - Kubernetes: API Resource schemas with runtime validation
 * - GraphQL: Schema-first API design
 */

// ==========================================
// Discovery & Metadata Operations
// ==========================================

/**
 * Get API Discovery Request
 * No parameters needed
 */
export const GetDiscoveryRequestSchema = lazySchema(() => z.object({}));

/**
 * Get API Discovery Response
 * Derived from DiscoverySchema (single source of truth) for protocol-level use.
 * 
 * All fields from DiscoverySchema are available but made optional (except `version`)
 * to support progressive disclosure and backward compatibility with existing clients.
 * 
 * - `routes` provides a flat endpoint map for client routing.
 * - `services` is the single source of truth for service availability.
 * - `apiName` is kept as an optional alias for `name` for backward compatibility.
 *
 * ## This schema is the CLIENT's tolerance, never a producer's licence (#4828)
 *
 * `.partial()` exists so a client can parse an OLDER server's response without
 * exploding, and zod's default unknown-key strip lets it parse a NEWER one.
 * That tolerance is correct at this boundary and wrong as a producer contract —
 * and for a long time it was the only schema anything referenced, so it acted
 * as both. The result was `declared ≠ enforced` in both directions at once:
 * `getDiscovery()` never emitted the required `name`/`environment`/`locale` and
 * still parsed clean, while the runtime dispatcher emitted `features` and
 * `endpoints` — declared nowhere — and also parsed clean.
 *
 * So the two schemas now have separate jobs, and a gate compares them:
 *
 * - **{@link DiscoverySchema} is authoritative for PRODUCERS.** Every producer's
 *   live shape must satisfy it (`packages/metadata-protocol`, `packages/runtime`
 *   and `packages/rest` each carry a `discovery-schema-conformance.test.ts`).
 * - **This schema is the CONSUMER's parse**, and its key set is the allowance
 *   those producer gates check against — i.e. `DiscoverySchema`'s keys plus the
 *   declared deprecated aliases. `./discovery.test.ts` pins that equivalence, so
 *   a key can never again appear on one side only.
 *
 * ## `apiName` retirement schedule (ADR-0087)
 *
 * `apiName` is the sole surviving deprecated alias here. `name` is canonical and
 * REQUIRED by `DiscoverySchema`; as of protocol 17 every producer emits `name`,
 * and `getDiscovery()` additionally emits `apiName` with the identical value so
 * clients pinned to the alias keep working.
 *
 * - **Protocol 17 (now)**: both emitted; `name` canonical, `apiName` deprecated.
 * - **Protocol 18**: producers stop emitting `apiName` and it is removed from
 *   this schema. Consumers migrate to `name` — a pure rename with no semantic
 *   change, which is why it needs no D2 conversion entry (that table converts
 *   AUTHORED metadata at load; a response payload has no load seam).
 *
 * Consumers to migrate before 18 — measured 2026-08-05 across `objectstack`,
 * `objectui` and `cloud`: `packages/client/tests/integration/01-discovery.test.ts`
 * (TC-DISC-001/002). No product code in any of the three repos reads `apiName`.
 *
 * @see DiscoverySchema in ./discovery.zod.ts — the canonical definition.
 */
export const GetDiscoveryResponseSchema = lazySchema(() => DiscoverySchema
  .partial()
  .required({ version: true })
  .extend({
    /**
     * @deprecated Use `name` instead. Removed in protocol 18 — see the
     * retirement schedule above. Emitted alongside `name` until then.
     */
    apiName: z.string().optional().describe('API name (deprecated — use `name`; removed in protocol 18)'),
  }));

/**
 * Get Metadata Types Request
 */
export const GetMetaTypesRequestSchema = lazySchema(() => z.object({}));

/**
 * Get Metadata Types Response
 *
 * Phase 3a-1: returns the bare `types` array (for backwards compatibility)
 * plus rich per-type `entries` describing label, domain, file patterns, and
 * runtime capability flags. Admin UIs (Metadata Directory, Resource list,
 * Quick Find) consume `entries`; legacy code that only needs the type list
 * keeps using `types`.
 */
export const GetMetaTypesResponseSchema = lazySchema(() => z.object({
  types: z.array(z.string()).describe('Available metadata type names (e.g., "object", "plugin", "view")'),
  entries: z.array(z.object({
    type: z.string().describe('Singular type identifier'),
    label: z.string().describe('Human-readable label'),
    description: z.string().optional().describe('Brief description'),
    filePatterns: z.array(z.string()).describe('Glob patterns used to discover artifacts of this type'),
    supportsOverlay: z.boolean().describe('Whether a stored overlay row of an item a managed package ships may be removed through the ordinary delete door without the type\'s environment-overlay permission: the removal removes no managed definition, and changes what is served for permission alone; it opens no save and it decides no read'),
    allowEnvironmentOverlay: z.boolean().describe('True when the registry grants environment overlays of this type\'s packaged items, or when OS_METADATA_WRITABLE names the type (overrideSource env), which opens the type\'s writes of items no managed package ships and never a managed item (ADR-0131 D6)'),
    allowRuntimeCreate: z.boolean().describe('New artifacts of this type can be created via runtime API'),
    supportsVersioning: z.boolean().describe('History is tracked for this type'),
    executionPinned: z.boolean().describe('Runtime transactions pin a specific historical version_hash (ADR-0009)'),
    loadOrder: z.number().int().describe('Loading priority (lower = earlier)'),
    domain: z.enum(['data', 'ui', 'automation', 'system', 'security', 'ai']).describe('Protocol domain'),
    overrideSource: z.enum(['registry', 'env']).describe('Whether allowEnvironmentOverlay comes from the static registry or is elevated by the OS_METADATA_WRITABLE environment variable'),
    createSeed: z.unknown().optional().describe('Authoritative minimal valid create seed for this type — Studio/CLI/API derive create defaults from it (single source of truth in @objectstack/spec). Absent for canvas-create types whose shape is built interactively.'),
  })).optional().describe('Enriched per-type registry entries (Phase 3a)'),
}));

/**
 * Get Metadata Items Request
 * Get all items of a specific metadata type
 *
 * **`environmentId` is deliberately NOT a member here — or on any meta-read
 * request schema** (maintainer ruling 2026-08-18, commit 2a29caa53). It is the
 * TRANSPORT-level multi-kernel routing key: the REST layer resolves the target
 * kernel from it *before* the protocol call, and the implementation's own
 * parameter types (`@objectstack/metadata-protocol`) never read it off the
 * request. Its absence from these schemas is a recorded contract decision —
 * "not part of the request" — not an undeclared-surface omission. Callers that
 * must carry it alongside a request do so in a typed transport envelope at
 * their own layer (see `TransportScopedMetaRequest` in `@objectstack/rest`),
 * never by widening these shapes.
 */
export const GetMetaItemsRequestSchema = lazySchema(() => z.object({
  type: z.string().describe('Metadata type name (e.g., "object", "plugin")'),
  packageId: z.string().optional().describe('Optional package ID to filter items by'),
  previewDrafts: z.boolean().optional().describe(
    'Draft-visibility switch (ADR-0033 draft-overlay preview): when true, '
    + 'pending `state=\'draft\'` rows are overlaid on the active list — draft '
    + 'wins on name collision, draft-only items appear, and each overlaid item '
    + 'is tagged `_draft: true` so UIs can badge the preview. Absent/false = '
    + 'published world only. Declaration ≠ authorization: this member only '
    + 'switches which rows are read, and ADR-0106 masking is unaffected — '
    + 'callers without draft-preview authorization are refused upstream '
    + '(admin-gated), not by this schema.',
  ),
}));

/**
 * What the automation engine threw when it refused to register a stored flow:
 * the engine's own `code` and `message`, verbatim. ⛔ Never paraphrased, never
 * re-coded: a consumer renders `message`, and branches on `code` only where
 * the engine set one (many registration refusals are plain errors, which carry
 * none — so `code` is absent there rather than invented).
 */
export const FlowRegistrationRefusalSchema = lazySchema(() => z.object({
  code: z.string().optional().describe(
    'The machine code the engine\'s refusal carried, verbatim. Absent when the thrown error carried none.',
  ),
  message: z.string().describe(
    'The engine\'s refusal message, verbatim. Render it as sent; do not parse it.',
  ),
}));

/**
 * The automation engine's verdict on ONE stored flow, as the metadata read
 * serves it — beside the item, never inside it.
 *
 * Two facts, deliberately apart: the stored `status` is what the author
 * declared and stays as authored, while this is what the engine made of the
 * definition. Before this member existed, a flow the engine refused at boot
 * (withdrawn, with a warn line) was served as `status: 'active'` and nothing
 * on the read said it never runs.
 *
 * A closed set, total over the engine's state for a name:
 *
 * - `registered` — the engine holds a registration under the name.
 *   Registration is not arming: whether a trigger is bound is
 *   `GET /automation/_status`'s answer, not this one.
 * - `refused` — the engine's last attempt to register the stored flow threw,
 *   and it holds nothing under the name; `reason` is what it threw. A later
 *   successful registration of the name (a save, a publish, a reload) ends
 *   the state.
 * - `unregistered` — the engine holds nothing under the name and recorded no
 *   refusal: the flow has not reached it (a read during boot, or between a
 *   save and the engine following it), or it was unregistered on purpose.
 *
 * It is the verdict of the engine in the process that answered the read: on a
 * deployment of several processes each answers for its own engine, and no
 * cross-process store is consulted.
 */
export const FlowRegistrationSchema = lazySchema(() => z.discriminatedUnion('state', [
  z.object({
    state: z.literal('registered').describe('The engine holds a registration under the flow\'s name.'),
  }),
  z.object({
    state: z.literal('refused').describe(
      'The engine refused to register the stored flow and holds nothing under its name: it never runs.',
    ),
    reason: FlowRegistrationRefusalSchema.describe('What the engine threw, verbatim.'),
  }),
  z.object({
    state: z.literal('unregistered').describe(
      'The engine holds nothing under the flow\'s name and recorded no refusal for it.',
    ),
  }),
]));

/**
 * Get Metadata Items Response
 *
 * `registrations` is the list's position for the automation engine's verdict
 * ({@link FlowRegistrationSchema}): the items stay bare documents, so the
 * verdict sits beside them, keyed by each item's `name` — readable without a
 * per-item read, and never inside an item.
 */
export const GetMetaItemsResponseSchema = lazySchema(() => z.object({
  type: z.string().describe('Metadata type name'),
  items: z.array(z.unknown()).describe('Array of metadata items'),
  registrations: z.record(z.string(), FlowRegistrationSchema).optional().describe(
    'The automation engine\'s verdict on each listed flow, keyed by the item\'s `name`: one entry per '
    + 'listed item that is not a pending draft. Present only on a `flow` list answered by a process that '
    + 'runs an automation service; absent otherwise, and absence means no engine judged them, never '
    + '`registered`. The verdict is the answering process\'s engine. Beside the items, never inside one: '
    + 'an item\'s `status` stays what its author declared.',
  ),
}));

/**
 * [#22877] The `member` every by-name door that reads or changes ONE stored
 * item declares (get, delete, publish, history; revert has no declared
 * request) — one sentence, so the four requests cannot drift apart. On the
 * REST door it is the `?member=` query parameter of each route's closed set.
 */
const BUNDLE_MEMBER_SELECTOR_DESCRIPTION =
  'Bundle member selector, for a metadata type whose identity is a pair (today only `email_template`, ' +
  'identified by `(name, locale)`): the member this request addresses, spelled as its discriminator value ' +
  '(`zh-CN`). Absent, the canonical member (`en-US` for `email_template`), which is what a bare-name read ' +
  'answers; naming the canonical value is the same request. It is not the response translation locale, ' +
  'which `?locale=` and `Accept-Language` choose. Refused with 400 `VALIDATION_ERROR` on a type that has ' +
  'no members, and for a blank value or one longer than a stored member can be (100 characters). A ' +
  'well-formed member with nothing stored or shipped answers as that door answers an absent item.';

/**
 * Get Metadata Item Request
 * Get a specific metadata item by type and name
 */
export const GetMetaItemRequestSchema = lazySchema(() => z.object({
  type: z.string().describe('Metadata type name'),
  name: z.string().describe(
    'Item name: the item\'s own `name`. For `type: \'app\'` only, it may instead be the id of the '
    + 'package that ships the app (`manifest.id`, reverse-domain, e.g. `com.acme.crm`): with one app '
    + 'per package the app IS the package container, and the package id is its route key (ADR-0048 '
    + '§3.1). The two grammars are disjoint (an app name is snake_case with no dot; a package id '
    + 'matches `MANIFEST_ID_PATTERN`, with at least one dot), so an app key in the package-id grammar '
    + 'always names the package (`isAppPackageIdKey`). That read answers the package\'s one app as the '
    + 'by-name read answers it, under the app\'s own `name`, and the per-caller read gate judges it as '
    + 'it judges that app read by name (an app withheld from the caller answers 403 '
    + '`PERMISSION_DENIED`). A package with no app, or with more than one, answers as an absent item. '
    + 'A `packageId` naming a different package is refused with 400 `INVALID_REQUEST`. Every other '
    + 'type, and every other key, is read by name.',
  ),
  packageId: z.string().optional().describe('Optional package ID to filter items by'),
  member: z.string().optional().describe(BUNDLE_MEMBER_SELECTOR_DESCRIPTION),
  state: z.enum(['active', 'draft']).optional().describe(
    'Draft-visibility switch — which lifecycle row to read (strict mode): '
    + '`\'draft\'` opens the pending draft buffer (Studio\'s editor read) and '
    + 'fails when no draft exists; absent or `\'active\'` reads the live '
    + 'published row. Distinct from `previewDrafts`, which FALLS BACK to the '
    + 'active row when no draft exists. Declaration ≠ authorization: this '
    + 'member only selects which stored row is read — ADR-0106 masking is '
    + 'unaffected, and draft access is gated upstream, not by this schema.',
  ),
  previewDrafts: z.boolean().optional().describe(
    'Draft-visibility switch (ADR-0033 draft-overlay preview, non-strict): '
    + 'when true and `state` is not `\'draft\'`, a pending draft row is '
    + 'preferred if one exists, else the read falls back to the active row — '
    + 'the render path degrades to the published value instead of erroring. A '
    + 'served draft is tagged `_draft: true` so UIs can badge it. Declaration '
    + '≠ authorization: this member only switches which row is read, and '
    + 'ADR-0106 masking is unaffected — draft preview is admin-gated '
    + 'upstream, not by this schema.',
  ),
}));

/**
 * [#23183] Does `name` address the app item read by PACKAGE ID — the arm
 * {@link GetMetaItemRequestSchema}'s `name` declares (ADR-0048 §3.1)? True
 * exactly when `type` is `app` and `name` is in the package-id grammar
 * ({@link MANIFEST_ID_PATTERN}), which no app name can be: `AppSchema.name` is
 * snake_case with no dot, and a package id carries at least one. So the arm is
 * unambiguous, and a by-name read of every other key is unchanged.
 *
 * The one spelling of the rule: the producer that resolves the key
 * (`getMetaItem` in `@objectstack/metadata-protocol`) asks it, and so does any
 * door that must tell the arm from a by-name read — ⛔ never a second regex or
 * type test beside it. `type` is the canonical SINGULAR type: a door folds
 * `apps` once, at its boundary, before asking.
 */
export function isAppPackageIdKey(type: string, name: string): boolean {
  return type === 'app' && MANIFEST_ID_PATTERN.test(name);
}

/**
 * ADR-0010 read-side protection envelope — the flags a metadata READ publishes
 * alongside the document, all derived in one place.
 *
 * These are the UN-prefixed, envelope-level counterparts of the `_lock` /
 * `_provenance` fields `MetadataProtectionFields` splices into the document
 * itself: the document stores `_lock`, and the read RESOLVES it — joined with
 * the write doors' locked-packaged-base verdict — into `lock` plus the three
 * `editable` / `deletable` / `resettable` verdicts Studio renders affordances
 * from (ADR-0010 §5), so no consumer re-implements the lock algebra.
 *
 * Shared by {@link GetMetaItemResponseSchema} and
 * {@link GetMetaItemLayeredResponseSchema} — both are produced by the SAME
 * derivation in `metadata-protocol` (`resolveLockState` joined with
 * `packagedBaseRefusal`), so a mixin is what keeps the two declarations from
 * drifting apart key by key. Module-local on purpose: it
 * is a shape these two responses share, not a new public vocabulary.
 *
 * Every key is optional HERE and tightened per-response where the producer
 * guarantees presence — see each schema's note. Optionality is measured, not
 * assumed: the six `lockReason` … `packageVersion` keys are spread only when
 * `!== undefined` (they read off `_`-prefixed document fields that are
 * themselves optional), so they are conditional on EVERY path.
 */
const MetadataProtectionEnvelopeFields = {
  lock: MetadataLockSchema.optional().describe(
    'Resolved lock verdict for this item (ADR-0010 §3.3). `none` means unlocked; '
    + '`no-overlay` / `no-delete` / `full` mean the write doors refuse the '
    + 'corresponding write with 403. Joins two refusals: the document\'s own '
    + '`_lock` (`ITEM_LOCKED`; the packaged artifact wins over any overlay), '
    + 'and the locked packaged base — an item a code package ships, on a type with '
    + 'no per-org overlay channel (`NOT_OVERRIDABLE`, or `ITEM_LOCKED` when the '
    + 'write names the read-only package).',
  ),
  lockReason: z.string().optional().describe(
    'Human-readable explanation shown next to a refused write. Present only when '
    + 'the resolved item declares `_lockReason`.',
  ),
  lockSource: MetadataLockSourceSchema.optional().describe(
    'Which layer asserted the lock. Present only when the resolved item declares '
    + '`_lockSource`.',
  ),
  lockDocsUrl: z.string().optional().describe(
    'Documentation link surfaced beside `lockReason`. Present only when the '
    + 'resolved item declares `_lockDocsUrl`.',
  ),
  provenance: MetadataProvenanceSchema.optional().describe(
    'Where the item came from (package | org | env-forced). Present only when the '
    + 'resolved item declares `_provenance`.',
  ),
  packageId: z.string().optional().describe(
    'Owning package machine id. Present only when the resolved item declares '
    + '`_packageId`.',
  ),
  packageVersion: z.string().optional().describe(
    'Owning package version. Present only when the resolved item declares '
    + '`_packageVersion`.',
  ),
  editable: z.boolean().optional().describe(
    'Whether an overlay write is permitted — false iff `lock` is `no-overlay` or '
    + '`full`. A derived verdict: do not recompute it from `lock` client-side.',
  ),
  deletable: z.boolean().optional().describe(
    'Whether deleting the overlay is permitted — false iff `lock` is `no-delete` '
    + 'or `full`.',
  ),
  resettable: z.boolean().optional().describe(
    'Whether the item can be reset to its packaged default — true iff it is '
    + 'artifact-backed, i.e. there is a baseline to reset TO.',
  ),
} as const;

/**
 * Get Metadata Item Response
 *
 * Describes the FULL body `GET /api/v1/meta/:type/:name` can return, not the
 * three-key subset it used to claim (#5950 — the read-side twin of the write-side
 * gap #5745 closed on {@link SaveMetaItemResponseSchema}).
 *
 * The declaration stopped at `{ type, name, item }` while the uncached branch
 * served ten more keys: the ADR-0010 protection envelope, spread onto the wire
 * verbatim by the REST layer (`rest-server.ts`'s `translateMetaEnvelope` does
 * `{ ...envelope, item }`). `lock` in particular is the read half of the ADR-0008
 * optimistic-concurrency story the write half already declares — so an SDK caller
 * typed against this response could not see it, and reading it meant a cast, the
 * consumer-side tolerance this repo rejects by Prime Directive #12.
 *
 * **Why every protection key is optional, measured rather than assumed.** This
 * route reaches a body by two branches and they publish different amounts:
 *
 * - **cached** (`getMetaItemCached`, THE DEFAULT — `enableCache` defaults to
 *   `true`): the REST layer rebuilds the envelope as `{ type, name, item }` and
 *   deliberately resolves NO lock — it is the fast published-value path and
 *   never consults the lock resolver (`rest-server.ts`, the `cachedEnvelope`
 *   note). All ten keys are ABSENT.
 * - **uncached** (`getMetaItem`): `lock`, `editable`, `deletable` and
 *   `resettable` are always set; the other six appear only when the resolved
 *   document carries the corresponding `_`-prefixed field.
 *
 * So `optional` here means "this deployment/branch did not publish it", NEVER
 * "unlocked" — a consumer that needs the OCC carriers must read the uncached
 * path and must not read absence as `lock: 'none'`. Declaring them required
 * would make the default deployment's own response fail its own contract, which
 * is the #5563 defect in mirror image.
 *
 * ⚠️ This is a DECLARATION change only — zero runtime behaviour is altered. That
 * lock presence depends on a server-side cache setting is a separate, larger
 * question (#5950 says so explicitly) and is deliberately NOT decided here.
 *
 * [#10235] `sortability` is the one envelope key that is NOT part of the
 * protection family: the per-column sortability projection, present exactly
 * when the served type is `object` (every branch — cached included, unlike the
 * protection keys — because it is computed from the served document itself,
 * never from the lock resolver). See `sortability.zod.ts` for the category
 * set and the consumer contract.
 *
 * [#22114] `version` is the READ half of the ADR-0008 optimistic-concurrency
 * chain: the token a client sends back as `If-Match`, served by the read it
 * edits from. ADR-0008 says clients pass `If-Match: <hash>`, and a client can
 * only send a token it was served — before this member only a save receipt
 * served one, so the first save after a load could not be pinned and two
 * editors who each loaded and saved once overwrote each other. It is the
 * keyed token of the stored row a SAVE to this item would compare against —
 * the same producer and the same row as {@link SaveMetaItemResponseSchema}'s
 * `version`, so a read after a save serves the receipt's token byte for byte.
 * Like the protection keys it is published by the uncached branch only (the
 * cached branch never consults the store's rows), and it is the one key whose
 * `null` is a statement: no stored row is there, so the next save is a create.
 *
 * [#23316] `registration` is the automation engine's verdict on a `flow`
 * ({@link FlowRegistrationSchema}), an envelope sibling of `lock` for the same
 * reason `lock` is one: it is a fact about the item that the document cannot
 * carry. The stored `status` is the author's declared state, and a flow the
 * engine refused at boot used to be served as `status: 'active'` with nothing
 * beside it. Unlike the protection keys it is published by BOTH branches:
 * the cached branch is the default door, so it carries the verdict too, read
 * live and kept out of the ETag ({@link GetMetaItemCachedResponseSchema}). It
 * is absent wherever no automation engine answered, so absence is never read
 * as `registered`.
 *
 * [#24298] `draftChanges` is a pending draft's per-key provenance: for each
 * changed key path of the draft body, which authoring surface (`copilot`,
 * `studio`, `api`) last changed it, under which actor, and when. It is what
 * lets Studio's properties mark a field or a view setting the AI copilot
 * changed, with the draft chip and the source line objectui#12725 rules
 * (「由 AI 副驾在 2 分钟前作为草稿加入」). It carries ADR-0033's provenance
 * item, "attribute each AI draft to the acting user + mark it AI-sourced",
 * at the grain of a key: `actor` is the acting user and `by: 'copilot'` the
 * AI-sourced mark, two members because one user makes both kinds of edit.
 * Four measured choices:
 *
 * - **On this read, not on the `_drafts` row.** The reader is Studio's
 *   properties, and they read the item they edit through the strict draft
 *   read (`?state=draft`, the client's `getDraft`); the `_drafts` list is the
 *   change badge's and the changes drawer's read, one row per item. Here the
 *   provenance comes from the same stored row as the body and `version` it
 *   sits beside, so a mark can never describe a body the editor has not
 *   loaded.
 * - **Beside `item`, never inside it**, like `registration`: a fact about the
 *   stored row the document cannot carry. Inside the body it would be one more
 *   read decoration every GET → edit → PUT round trip must strip
 *   (`METADATA_READ_DECORATIONS`), and `provenance` is already the ADR-0010
 *   envelope key (where the item came from), hence the distinct name.
 * - **A path is an array of keys, and an array value is one leaf.** Keys may
 *   contain dots (a permission set's `fields` map is keyed `object.field`), so
 *   a dotted string would be ambiguous; and an index (`columns[3]`) moves when
 *   a column is inserted or reordered, so the path stops at `columns` — the
 *   granularity the ruling names, "a field or a view setting". The ruled
 *   properties artboard also marks ELEMENTS of an array setting: a kanban
 *   card's two copilot-added fields, under the line
 *   「读者」「应还日期」两项由 AI 副驾在 2 分钟前作为草稿加入. The reader finds
 *   which elements by comparing the draft's array with the published body's,
 *   and the array's entry says who last changed it and when. Attribution is
 *   per array, never per element.
 * - **Optional, never defaulted to `[]`.** Absent means "not recorded" (a
 *   server with no writer, or a draft row saved before one); an empty-array
 *   default would answer "nothing changed" for exactly those rows.
 *
 * The history log's per-event `source` (see `HistoryMetaItemResponseSchema`)
 * is not this vocabulary: it is an open label of the code path that wrote the
 * event, not the surface a person or the copilot used, and it is per write,
 * not per key.
 */
export const GetMetaItemResponseSchema = lazySchema(() => z.object({
  type: z.string().describe('Metadata type name'),
  name: z.string().describe('Item name'),
  item: z.unknown().describe('Metadata item definition'),
  sortability: ObjectSortabilitySchema.optional().describe(
    'Per-column sortability projection — present exactly when `type` '
    + 'is `object`, on every serving branch. Computed at serve time from the '
    + 'served document via the spec\'s own storage predicates; consumers render '
    + 'sort affordances from this signal and never re-derive it from field '
    + '`type`. See `ObjectSortabilitySchema` for the closed category set.',
  ),
  ...MetadataProtectionEnvelopeFields,
  version: z.string().nullable().optional().describe(
    'ADR-0008 version token of the STORED row a save to this item compares '
    + 'against, at this read\'s scope (the environment\'s partition and '
    + '`?package=`) and lifecycle (`?state=draft` reads the draft row, the plain '
    + 'read the active row). The same keyed token a save receipt\'s `version` '
    + 'serves for that row: send it back as the `If-Match` request header on '
    + '`PUT /meta/:type/:name` (with `?mode=draft` for the draft) and a '
    + 'concurrent edit is refused 409 `METADATA_CONFLICT` instead of '
    + 'overwritten. `null` when no stored row is there — an item served from '
    + 'code or a package artifact, or from a row in another scope (a '
    + 'package-less row a package read falls back to) — so the next save '
    + 'creates one: pin it with '
    + '`If-None-Match: *`. A `null` beside `editable: false` is no such '
    + 'invitation: that item takes no save at this address, so no pin is '
    + 'prescribed for it. ABSENT on the cached published-value branch and on a '
    + '`?preview=draft` read, which publish no version: absence means "not '
    + 'published here", never "no row". Opaque — echo it verbatim, never parse '
    + 'it.',
  ),
  registration: FlowRegistrationSchema.optional().describe(
    'The automation engine\'s verdict on this flow (see `FlowRegistrationSchema`): `registered`, or '
    + '`refused` with the engine\'s `reason` verbatim, or `unregistered`. Present only on a `flow` read '
    + 'answered by a process that runs an automation service; absent otherwise, and absence means no '
    + 'engine judged it, never `registered`. Unlike the protection keys it is published by the cached '
    + 'branch too, read live and never part of the ETag, so a cached read that carries it is never '
    + 'answered 304; it is absent on a draft read, whose pending body no engine holds. The verdict is '
    + 'the answering process\'s engine. Beside `item`, never inside it: the item\'s `status` stays what '
    + 'its author declared.',
  ),
  draftChanges: z.array(z.object({
    path: z.array(z.string().min(1)).describe(
      'The changed key path inside `item`: one object key per segment, from the body root down to the '
      + 'deepest key whose value the write changed, added or removed. `["fields", "renewal_count"]` is a '
      + 'field the write added; `["fields", "renewal_count", "label"]` is one property of it. A segment '
      + 'is the key exactly as stored, dots included (a permission set\'s `fields` map is keyed '
      + '`object.field`), so a path is never one dotted string. An array is one value: its path ends at '
      + 'its key (`["columns"]`) and never carries an index, which an insert or a reorder would shift. '
      + 'Which elements of an array the draft added or dropped is read by comparing it with the '
      + 'published body\'s array; the entry answers only who last changed the array as a whole. '
      + '`[]` is the whole body: the write that created the draft of an item with no published body.',
    ),
    by: z.enum(['copilot', 'studio', 'api']).describe(
      'The authoring surface of the write that last changed this path. Closed: `copilot` is an AI '
      + 'assistant\'s tool writing on a person\'s behalf (Studio\'s AI copilot); `studio` is a person '
      + 'editing in Studio; `api` is any other caller of the save door. It names the surface, not the '
      + 'person: a copilot write and a Studio write of the same user carry the same `actor`.',
    ),
    actor: z.string().nullable().describe(
      'The identity that write was recorded under: the save\'s `actor`, the value its history event '
      + 'carries. `null` when the write recorded none, never a sentinel string.',
    ),
    at: z.string().datetime().describe(
      'When that write happened: an ISO-8601 instant in UTC, written with `Z` (the form '
      + '`toISOString()` produces). An offset or a local time is refused.',
    ),
  }).describe('One changed key path of the pending draft, and the last write that changed it.'))
    .optional().describe(
      'Per-key provenance of the pending draft: which authoring surface last changed each key path of '
      + '`item`, under which actor, and when. No server writes the key yet: until the engine\'s draft '
      + 'save records it, every draft read is one whose saves recorded none, and the key is absent. '
      + 'The contract a writer must meet: it compares each draft save with the body that save replaced '
      + '(the previous draft, or the published body for the draft\'s first save); it keeps the entries '
      + 'from the first recorded save until the draft is published or discarded, which remove the draft '
      + 'row and the entries with it; and it keeps no two entries on one path, replacing every entry at '
      + 'or under a path a save changes, so the last write to change a key is the entry whose `path` is '
      + 'the longest prefix of that key\'s path, and entries under a key\'s path are changes inside it. '
      + 'The entries name which writes changed what; they are not a list of every difference from the '
      + 'published body (compare the two bodies for that). Served only on a `?state=draft` read that '
      + 'answers a stored draft row. ABSENT on the active read, the cached branch and a '
      + '`?preview=draft` read, and for a draft row whose saves recorded none: absence means "not '
      + 'recorded", never "no changes".',
    ),
}));

/**
 * Get Metadata Item — LAYERED Request
 *
 * Request shape for `GET /api/v1/meta/:type/:name/layers` (the
 * `getMetaItemLayered` protocol method). Mirrors the implementation's
 * parameter type in `@objectstack/metadata-protocol` member for member — a
 * declared-surface catch-up, not a new capability: the verb and every member
 * here already ship and are enforced.
 */
export const GetMetaItemLayeredRequestSchema = lazySchema(() => z.object({
  type: z.string().describe('Metadata type name'),
  name: z.string().describe('Item name'),
  packageId: z.string().optional().describe(
    'Optional package ID — scopes the `code` layer so a same-name collision '
    + 'resolves to the requested package\'s artifact (ADR-0048).',
  ),
}));

/**
 * Get Metadata Item — LAYERED Response
 *
 * The body of `GET /api/v1/meta/:type/:name/layers`: a three-layer diagnostic
 * projection that shows the packaged baseline, the tenant's customization row
 * and the merged result SIDE BY SIDE, which is what drives Studio's
 * "code default vs override vs effective" comparison tabs.
 *
 * **Why this is a separate schema on a separate path** (#5882, ruled B by the
 * maintainer 2026-08-06). This projection used to be reached by putting
 * `?layers=true` on the ordinary read, so one route answered two unrelated
 * resource representations while `packages/spec` declared only one of them —
 * anything generating a client from the route table (SDK annotations, codegen,
 * an AI-written integration) produced a parser that was simply wrong for the
 * flagged call. Collapsing the three layers into
 * {@link GetMetaItemResponseSchema}'s single `item` was never an option: seeing
 * the layers apart IS the diagnostic. The rejected alternative was teaching the
 * route declaration to express "two shapes, chosen by query flag"; that adds a
 * new primitive every future tool must understand, and conditional response
 * selection is precisely where codegen and AI clients go wrong. One path, one
 * response shape — so the projection got its own path.
 *
 * The `?layers=` flag still answers this same body during its deprecation
 * window, marked with `Deprecation` / `Link` response headers.
 *
 * **Required vs optional, measured against the producer.** Unlike the ordinary
 * read there is exactly ONE producer path here (`getMetaItemLayered`; the
 * layered view deliberately skips the cache), so the four resolved verdicts
 * `lock` / `editable` / `deletable` / `resettable` are ALWAYS set and are
 * required below. The six conditional protection keys stay optional for the
 * same reason they are optional on the ordinary read.
 */
export const GetMetaItemLayeredResponseSchema = lazySchema(() => z.object({
  type: z.string().describe('Metadata type name (canonical singular)'),
  name: z.string().describe('Item name'),
  code: z.unknown().describe(
    'LAYER 1 — the packaged artifact baseline exactly as shipped, before any '
    + 'tenant customization. `null` when no artifact ships this item (it exists '
    + 'only as an overlay).',
  ),
  overlay: z.unknown().describe(
    'LAYER 2 — the stored customization row ALONE, not merged with `code`. '
    + '`null` when the environment has not customized the item.',
  ),
  overlayScope: z.enum(['env']).nullable().describe(
    'Which scope the `overlay` row was read from: `env`, the environment layer — '
    + 'the only layer a read serves (ADR-0131 D6). `null` exactly when `overlay` is null.',
  ),
  effective: z.unknown().describe(
    'LAYER 3 — the merged result, i.e. the value an ordinary '
    + '`GET /meta/:type/:name` would return under `item`. `null` when the item '
    + 'resolves to nothing at all.',
  ),
  _diagnostics: MetadataValidationResultSchema.optional().describe(
    'Load-time spec-validation verdict for `effective`, so the Studio edit page '
    + 'can raise invalid-metadata banners and inline field errors without a '
    + 'second round trip. ABSENT for metadata types that register no Zod schema '
    + '(function / service / router) — absence means "no opinion", never "valid".',
  ),
  ...MetadataProtectionEnvelopeFields,
  // The four resolved verdicts are unconditional on this single-producer path —
  // tightened from the mixin's optional baseline. See the note above.
  lock: MetadataLockSchema.describe(
    'Resolved lock verdict (ADR-0010 §3.3), artifact winning over overlay. Always '
    + 'present on this path.',
  ),
  editable: z.boolean().describe('Whether an overlay write is permitted. Always present on this path.'),
  deletable: z.boolean().describe('Whether deleting the overlay is permitted. Always present on this path.'),
  resettable: z.boolean().describe('Whether the item can be reset to its packaged default. Always present on this path.'),
}));

/**
 * One finding from the #4463 runtime authoring gate — the fourth door.
 *
 * The gate runs the SHARED author-time rule registry (`@objectstack/lint`'s
 * `AUTHORING_RULES`, the same table `os validate` / `os build` / `os lint` run)
 * over a body about to go `active`, and partitions its findings by severity.
 * The `error` half becomes the 422 `invalid_metadata` envelope's `issues[]`;
 * the rest are ADVISORY — they do not block the write, and #4463 D3 decided
 * they ride the 2xx response instead of being discarded.
 *
 * This is that ONE element shape, declared once and used by both halves, which
 * is the whole point of D3's "reuse the Zod envelope": a consumer reads the
 * same six keys whether the verdict arrived on a refusal or on a success.
 * `@objectstack/metadata-protocol` re-exports this type as its
 * `RuntimeAuthoringIssue` rather than declaring a second interface (#4717).
 */
export const RuntimeAuthoringIssueSchema = lazySchema(() => z.object({
  rule: z.string().describe(
    'Stable diagnostic rule id (`flow-multi-write-unfiltered`, '
    + '`approval-expression-invalid`, …). Machine-readable and stable across '
    + 'releases — the key a renderer groups or suppresses by.',
  ),
  path: z.string().describe(
    'Config path inside the SUBMITTED body (`flows[0].nodes[1].config.multi`), '
    + 'so an editor can jump to the offending key. May be empty when the '
    + 'finding is about the item as a whole. The TOP-LEVEL collection entry '
    + 'follows one rule. The gate evaluates against a private per-write '
    + 'snapshot whose indexes no caller can resolve; a collection-resident '
    + 'write type is one whose collection that snapshot fills with the '
    + 'tenant\'s other stored items beside the written one, and there the '
    + 'entry is keyed by NAME, never by an array index — for example '
    + '`objects.acme_invoice.sharingModel` (an `object` write) or '
    + '`datasets.acme_invoice_metrics.dimensions[0].field` (a `dataset` '
    + 'write). Every other write type is the sole member of its own '
    + 'collection in that snapshot, so its `[0]` IS the written item and '
    + 'stays positional (for example `flows[0]...`). Which write types are '
    + 'collection-resident is derived, never listed: `@objectstack/lint`\'s '
    + 'runtime gate computes the set (`NAME_KEYED_STACK_KEYS`) as the '
    + 'collections it carries as resolution context that a gated write type '
    + 'also lands in, so it changes with the gate, not with this text. An '
    + 'entry whose name cannot be spliced into a dotted path keeps its index. '
    + 'Nested positions inside one named item stay positional '
    + '(`objects.acme_invoice.indexes[1]`): they index the author\'s own '
    + 'document.',
  ),
  where: z.string().describe(
    'Human-readable location — `flow "leave_approval" · node "approve"`. Prose '
    + 'for a person; use `path` for anything mechanical.',
  ),
  message: z.string().describe('What is wrong, in the rule author\'s own words.'),
  hint: z.string().describe('How to fix it.'),
  severity: z.enum(['error', 'warning', 'info']).describe(
    'How the gate treated this finding. `error` means the write was REFUSED '
    + '(these appear on the 422, never on a 2xx); `warning` / `info` are '
    + 'advisory — the write succeeded and the finding is FYI.',
  ),
}));

/**
 * Save Metadata Item Request
 * Create or update a metadata item — the request shape for
 * `PUT /api/v1/meta/:type/:name` (the `saveMetaItem` protocol method).
 *
 * Declared member for member against the implementation's parameter type in
 * `@objectstack/metadata-protocol` and the REST save door's actual sends — a
 * declared-surface catch-up, not a new capability (#12004, the maintainer-ruled
 * pattern of commit cccbe51bf, 2026-08-22 option B, carried one door over
 * exactly as #11679/PR #12003 carried it to the reset twin). `saveMetaItem`
 * is a REQUIRED protocol member, so this was the sharpest instance of the
 * request-shape gap: the schema declared 3 of the ~11 members the door
 * sends, and the call-site literal had to stay behind an `as any` cast
 * (removing it surfaced `TS2353` on the undeclared keys — pure
 * request-shape smuggling, never member-existence feature detection).
 * Every member below already ships and is read and enforced by the
 * implementation.
 *
 * `name` carries the enforced item-name grammar (commit 311433f6b — lowercase
 * snake_case segments, optionally dot-qualified; `shared/identifiers.zod.ts`
 * is the single source). The implementation refuses an off-grammar name at
 * the door with `400 INVALID_REQUEST`, so declared = enforced. The read and
 * delete request shapes deliberately stay `z.string()`: pre-grammar residue
 * rows must remain listable and clearable.
 *
 * Two members the implementation's parameter type family carries are
 * deliberately NOT declared:
 *
 * - `environmentId` — the TRANSPORT-level multi-kernel routing key, OUT of
 *   protocol request shapes by the maintainer ruling of 2026-08-18 (commit 2a29caa53):
 *   `resolveProtocol(environmentId)` has already selected the target kernel
 *   before this method is entered, and `packages/rest` layers that one
 *   member on top of the declared shape via its `TransportScopedMetaRequest`
 *   wrapper, which is where a routing key belongs.
 * - `source` — write-provenance for the history/audit rows
 *   (`'protocol.saveMetaItem'` by default). The implementation declares it,
 *   but NO door sends it: its only producer is the implementation's own
 *   internal `migrateStoredMetadata` call (`'migrate-stored'`), which does
 *   not travel through this contract. The publish-door precedent (#11426)
 *   leaves such a member undeclared until a producer on THIS contract pulls
 *   it — declaring it here would advertise a wire-authorable provenance
 *   channel the REST layer deliberately never reads.
 *
 * `writeFace` IS declared, and the distinction with `source` is the point:
 * both are server-stated, but `writeFace` is sent by three doors (the two
 * metadata write doors and the external-table import) and the
 * duplicate-package internal call — four real producers on this parameter
 * — and the implementation branches its refusal envelopes on it. See the
 * member's own doc for why declaring it does not make it client-authorable.
 */
export const SaveMetaItemRequestSchema = lazySchema(() => z.object({
  type: z.string().describe('Metadata type name'),
  name: MetadataItemNameSchema.describe(
    'Item name — lowercase snake_case segments, optionally dot-qualified '
    + '(`crm_lead`, `crm_lead.pipeline`). Slash-compound names are refused at '
    + 'the publish door.',
  ),
  item: z.unknown().describe('Metadata item definition'),
  parentVersion: z.string().nullable().optional().describe(
    'ADR-0008 optimistic-concurrency pin: the version token the caller '
    + 'believes is current (on the REST door, the `If-Match` request '
    + 'header; the item read\'s `version` and a save receipt\'s `version` '
    + 'serve it). Present as a string, a concurrent edit is reported as a 409 '
    + 'conflict instead of silently overwritten. ⚠️ `null` is NOT the same '
    + 'as absent: a present `null` asserts "no current row of this '
    + 'lifecycle" — the first-write pin, refused 409 when a row already '
    + 'exists (on the REST door, `If-None-Match: *`; that header takes `*` '
    + 'alone and never beside `If-Match`, and any other spelling is refused '
    + '400) — while an ABSENT key is unpinned: the implementation adopts '
    + 'the current row\'s hash as the parent (last-write-wins). Nullable '
    + 'because that is the implementation\'s parameter type, and unlike the '
    + 'reset twin (which folds a present `null` back to the current hash) '
    + 'this verb passes `null` through to the repository\'s conflict check '
    + 'unchanged.',
  ),
  actor: z.string().optional().describe(
    'Identity recorded on the write\'s history event (`recorded_by`, a '
    + 'lookup into `sys_user`) and audit row. On the REST door this is the '
    + 'request\'s authenticated identity (one producer) — never a '
    + 'caller-supplied header. Absent, the event is recorded actor-less '
    + '(null), deliberately not attributed to "system".',
  ),
  force: z.boolean().optional().describe(
    'Destructive-change acknowledgement (`?force=true` on the REST door): '
    + 'skips the safety diff that refuses an `object` save whose body drops '
    + 'fields or narrows types the stored item still carries (409 with the '
    + 'findings otherwise). Only `object` saves reach that diff, so the '
    + 'flag is inert for every other type. Absent = the guard runs.',
  ),
  mode: z.enum(['draft', 'publish']).optional().describe(
    'Per-item lifecycle (ADR-0005 drafts): `draft` stages the body as a '
    + 'pending draft overlay (`?mode=draft` on the REST door; the publish '
    + 'door promotes it later); `publish` or ABSENT writes straight to the '
    + 'live `active` row — the legacy default, kept so callers that '
    + 'predate the draft/publish split keep working. Any value other than '
    + '`draft` is read as `publish`.',
  ),
  packageId: z.string().nullable().optional().describe(
    'ADR-0048 — the software package to bind the saved row to '
    + '(`sys_metadata.package_id`; `?package=<id>` on the REST door, where '
    + '`all` and an empty value name no package). Set when authoring inside '
    + 'a Studio package workspace; a named read-only base package is '
    + 'refused. On create the row is stamped with this id; on update an '
    + 'existing binding is preserved, never silently re-bound. Absent or '
    + '`null` names no package. An `active` save then writes the row of the '
    + 'one package the item\'s active rows are bound to, as a save naming '
    + 'that package does, is refused `409 RESOURCE_CONFLICT` when they are '
    + 'bound to two or more, and with none writes the env-local overlay (no '
    + 'package stamp); a `draft` save writes the draft of the one package '
    + 'the item\'s active rows are bound to (a pending change stays in the '
    + 'package it edits), else its package-unbound draft, adopted into that '
    + 'package — the draft the per-item publish naming no package promotes. '
    + 'For an item never published into a package it is the package-unbound '
    + 'draft, else the one package\'s draft, and with no draft at all the save '
    + 'creates the package-unbound draft. It is refused `409 RESOURCE_CONFLICT` '
    + 'when the active rows (or, with none and no package-unbound draft, the '
    + 'drafts) are bound to two or more packages, as that publish is (see '
    + '`PublishMetaItemRequestSchema.packageId`). The row written is also the one the parent-version '
    + 'resolution reads: an unpinned save takes its version as the parent '
    + '(last-write-wins), a pinned one is judged against it, and the item '
    + 'read at the same scope serves it as `version`.',
  ),
  writeFace: z.enum(['package-duplicate', 'meta-envelope', 'meta-dispatch', 'external-import']).optional().describe(
    'Which write door a refusal is being rendered FOR — stated by the '
    + 'SERVER, never by a remote caller: every door builds this request '
    + 'field by field and never spreads a request body into it, so there is '
    + 'no path for a client to smuggle a face in, and a face arriving in a '
    + 'wire body is simply never read. Two refusals branch on it, for '
    + 'different questions: the 409 destructive-change remedy names the '
    + 'acknowledgement mechanism that actually exists on the refusing door '
    + '(`?force=true` on the REST doors; the dispatcher, the '
    + 'duplicate-package door and the external-table import have none), '
    + 'and the 422 invalid-metadata '
    + 'message adapts to whether a structured `issues[]` channel reaches '
    + 'the consumer beside it. Absent = the conservative default wording.',
  ),
}));

/**
 * Save Metadata Item Response
 *
 * Describes the FULL body `PUT /api/v1/meta/:type/:name` returns, not a subset
 * of it (#5745, settled by the #5563 maintainer ruling "补齐 spec 字段"). The
 * declaration previously stopped at `{ success, message }`, so a `.parse()` of
 * a real response silently STRIPPED `version` / `seq` / `state` — and
 * `SaveMetaItemResponse` could not even name them at the type level. `version`
 * in particular is the token the ADR-0008 optimistic-concurrency chain already
 * runs on (echo it back as `If-Match` on the next write to get a 409 instead of
 * a lost update), so leaving it undeclared meant the OCC carrier existed on the
 * wire with no contract behind it.
 *
 * Presence was measured against `origin/main`, not assumed: the sole producer is
 * `ObjectStackProtocolImplementation.saveMetaItem`, whose single success return
 * is the repository write path, and the REST route hands that object to
 * `res.json()` verbatim. That path always sets `version` / `seq` / `state`, so
 * the three are REQUIRED here; `projectionApplied` is conditional on an
 * ADR-0094 mutation projector being registered for the type, so it alone is
 * optional. (A second, receipt-less legacy return used to exist and would have
 * forced all three to be optional — it was proved unreachable and deleted in
 * #5264 / PR #5782, which is why `required` is safe to state.)
 */
export const SaveMetaItemResponseSchema = lazySchema(() => z.object({
  success: z.boolean(),
  version: z.string().describe(
    'Version token of the row this write left, and the token the ADR-0008 '
    + 'optimistic-concurrency chain runs on: send it back as the `If-Match` '
    + 'request header on the next write to that item and a concurrent edit is '
    + 'refused 409 `METADATA_CONFLICT` instead of silently overwritten. The item '
    + 'read serves the same token for the same row (`GetMetaItemResponseSchema.version`). '
    + 'A keyed digest of the stored content hash, never the hash itself (under '
    + 'the registered crypto provider\'s key, or a process-scoped key while none '
    + 'is registered). Opaque to callers — echo it verbatim, never parse it. '
    + 'Currently emitted as `hmac-sha256:` plus 64 hex characters, but the '
    + 'format is not part of this contract.',
  ),
  seq: z.number().int().describe(
    'Monotonic sequence number of the metadata event this write appended to '
    + 'the item history (sys_metadata_history.event_seq). Orders writes; unlike '
    + '`version` it is not an OCC token.',
  ),
  state: z.enum(['draft', 'active']).describe(
    'Lifecycle the body was written into: "draft" when the request asked for '
    + 'draft mode (`?mode=draft`), otherwise "active" (published and live). A '
    + 'draft is staged only — it is not served to the runtime until published.',
  ),
  projectionApplied: z.object({
    success: z.boolean().describe('False when the projector threw; the metadata write itself still succeeded.'),
    error: z.string().optional().describe('Projector failure message, present only when `success` is false.'),
  }).optional().describe(
    'Outcome of the awaited ADR-0094 mutation projector — the post-persist step '
    + 'that materializes this metadata into its derived data-plane read model '
    + '(e.g. `datasource` → its live connection pool). Present ONLY when a projector '
    + 'is registered for this metadata type, which is why it is optional: its '
    + 'absence means "no projector ran", never "the projection failed". '
    + 'Best-effort by design — a projector failure is reported here and logged, '
    + 'never thrown, so a caller that needs the read model to be live must check '
    + '`projectionApplied.success` rather than rely on the 200.',
  ),
  advisories: z.array(RuntimeAuthoringIssueSchema).optional().describe(
    'Non-gating findings from the runtime authoring gate — the same '
    + 'shared author-time rules `os validate` / `os build` / `os lint` run, '
    + 'applied to this body on its way to `active`. The write SUCCEEDED; these '
    + 'are what the gate has to say about it anyway (closing D3). '
    + 'Present ONLY when at least one advisory was raised — an empty array is '
    + 'never emitted, so a clean save\'s response bytes are unchanged and '
    + 'absence means "nothing to report", never "the gate did not run". '
    + 'Advisory by construction: every entry has `severity` `warning` or '
    + '`info`, because an `error` finding refuses the write and arrives as the '
    + '422 `invalid_metadata` envelope instead of here. A caller that ignores '
    + 'this key behaves exactly as before. Runtime-only: the CLI surfaces the '
    + 'same findings on its own stdout, and a Studio / MCP / AI author has no '
    + 'CLI at all, which is the gap this key exists to close. The gate runs on '
    + 'both write doors (D1), and both report: '
    + '`POST /meta/:type/:name/publish` carries the same key on '
    + '`PublishMetaItemResponseSchema`.',
  ),
  message: z.string().optional(),
}));

/**
 * Metadata Conflict — the 409 body of the `/meta/:type/:name` write doors
 *
 * Describes the body `PUT /api/v1/meta/:type/:name` (and its sibling write
 * doors: `POST …/publish`, `POST …/rollback`, `DELETE …`) answers when the
 * ADR-0008 optimistic lock refuses the write: a version token that names no
 * current head (`If-Match`), a "no row" pin a row has since contradicted
 * (`If-None-Match: *`), or a race the repository lost. The body is the REST
 * door's flat ADR-0112 dialect — `code` beside `error`, not inside it — the
 * position `check:route-envelope` holds for that door.
 *
 * `currentVersion` is the current head AS DATA (#22114). The sentence in
 * `error` has always named it (`… (current is <token>)`), so a client offering
 * "reload" or "overwrite anyway" had to parse prose or re-send unguarded; it
 * now reads the token it would pin to here. On the save door it is the token
 * the next item read at the same address serves as `version`
 * ({@link GetMetaItemResponseSchema}), and `null` when no row of the target
 * lifecycle is there (a draft save after a publish drained the draft) — the
 * state `If-None-Match: *` pins. Both doors of the chain serve it keyed, never
 * the stored content hash.
 *
 * Scope: this is the body of the conflicts the four `/meta` item doors answer
 * through the protocol's one conflict builder, which is how each of them
 * answers the repository's refusal. Not described here: a per-item
 * `METADATA_CONFLICT` inside a batch outcome (`failed[]` of the package publish
 * door), which is a row of a 2xx, not a refusal body.
 */
export const MetadataConflictErrorSchema = lazySchema(() => z.object({
  error: z.string().describe(
    'Human-readable refusal sentence, unchanged by `currentVersion`: it names '
    + 'the item and the version the door judged current. For display and logs; '
    + 'branch on `code` and read `currentVersion`, never parse this.',
  ),
  code: z.literal('METADATA_CONFLICT').describe(
    'ADR-0112 registered code of the optimistic-lock refusal.',
  ),
  currentVersion: z.string().nullable().describe(
    'The version token of the head the door judged current — the value the '
    + 'sentence names — or `null` when no row of the target lifecycle exists. '
    + 'Send it as `If-Match` to overwrite deliberately (or `If-None-Match: *` '
    + 'when it is `null`), or re-read the item to merge first. A `null` for an '
    + 'item whose read serves `editable: false` prescribes no pin: that item '
    + 'takes no save. Opaque — echo '
    + 'it verbatim, never parse it.',
  ),
}));

/**
 * Publish Metadata Item Request
 *
 * Request shape for `POST /api/v1/meta/:type/:name/publish` (the
 * `publishMetaItem` protocol method) — the promotion door: `saveMetaItem`
 * (with `?mode=draft`) stages a body, and this verb promotes the pending
 * DRAFT overlay to the live `active` row. Mirrors the implementation's
 * parameter type in `@objectstack/metadata-protocol` member for member — a
 * declared-surface catch-up, not a new capability (commit cccbe51bf, maintainer ruling
 * 2026-08-22: option B, closing the half-declared door #7294 left — the
 * response side was declared there while the request and the interface member
 * were not). The verb and every member here already ship and are enforced.
 *
 * Two members the implementation's parameter type family carries are
 * deliberately NOT declared:
 *
 * - `environmentId` — the TRANSPORT-level multi-kernel routing key, OUT of
 *   protocol request shapes by the maintainer ruling of 2026-08-18 (commit 2a29caa53):
 *   `resolveProtocol(environmentId)` has already selected the target kernel
 *   before this method is entered, and `packages/rest` layers that one member
 *   on top of the declared shape via its `TransportScopedMetaRequest` wrapper,
 *   which is where a routing key belongs.
 * - `_skipSeedApply` — internal coordination between `publishPackageDrafts`
 *   and the per-item path (the batch door suppresses the per-item seed apply
 *   and loads every seed body in one later pass). Never read from the wire,
 *   so it is not part of the contract.
 */
export const PublishMetaItemRequestSchema = lazySchema(() => z.object({
  type: z.string().describe('Metadata type name'),
  name: MetadataItemNameSchema.describe(
    'Item name — lowercase snake_case segments, optionally dot-qualified '
    + '(`crm_lead`, `crm_lead.pipeline`). The promotion door enforces the '
    + 'same grammar as `saveMetaItem`.',
  ),
  actor: z.string().optional().describe(
    'Identity recorded on the `op=\'publish\'` history event. On the REST door '
    + 'this is the request\'s authenticated identity (one producer) — '
    + 'never a caller-supplied header.',
  ),
  message: z.string().optional().describe(
    'Optional human-readable note recorded with the publish history event.',
  ),
  packageId: z.string().nullable().optional().describe(
    'ADR-0048 — the software package the draft being promoted was listed '
    + 'under, when the caller has one to state (`?package=<id>` on the REST '
    + 'door). Named, the publish promotes that package\'s draft and no other. '
    + 'ABSENT names no package: the publish promotes the draft a draft save '
    + 'that names no package writes — the draft of the one package the '
    + 'item\'s active rows are bound to, else its package-unbound draft, '
    + 'promoted into that package — and answers `404 NO_DRAFT` when neither '
    + 'exists, as the strict draft read does. For an item never published into '
    + 'a package it is the package-unbound draft, else the one package\'s '
    + 'draft. It is refused `409 RESOURCE_CONFLICT` when the active rows (or, '
    + 'with none and no package-unbound draft, the drafts) are bound to two or '
    + 'more packages. ⚠️ `null` is '
    + 'NOT the same as absent: the implementation branches on the KEY BEING '
    + 'PRESENT, and `null` pins the lookup to the package-UNBOUND row. Spread '
    + 'it in conditionally; a present-and-`undefined` key coerces to `null` '
    + 'downstream and makes a package-bound draft unfindable — a silent '
    + '`no_draft`.',
  ),
  member: z.string().optional().describe(BUNDLE_MEMBER_SELECTOR_DESCRIPTION),
}));

/**
 * Publish Metadata Item Response
 *
 * Describes the FULL body `POST /api/v1/meta/:type/:name/publish` returns
 * (#7294 — the #5745 discipline carried one door over). The publish door is the
 * sibling write surface of the save door: `saveMetaItem` writes a body, and
 * `publishMetaItem` promotes an already-written DRAFT body to `active`. Until
 * this declaration the route was served with no contract behind it at all —
 * the string `PublishMetaItem` appeared nowhere under `packages/spec/src/`, so
 * `version` here sat in exactly the undeclared state `version` on the save
 * response sat in before #5745, despite being the same ADR-0008
 * optimistic-concurrency token with the same "echo it back as `If-Match`" job.
 *
 * Presence was measured against `origin/main`, not assumed. The sole producer
 * is `ObjectStackProtocolImplementation.publishMetaItem`, which builds ONE
 * response object and the REST route hands it to `res.json()` verbatim. That
 * object literal always sets `success` / `version` / `seq`, so the three are
 * REQUIRED; the three `*Applied` receipts are each attached only when the
 * corresponding side effect ran, so each is optional — and their absence means
 * "that side effect did not run", NEVER "it failed".
 *
 * **The three conditional receipts, and what makes each conditional**
 * (`runPublishSideEffects`, phase 2 of the ADR-0067 D2 split):
 *
 * - `seedApplied` — only when the published type is `seed`. Publishing a seed
 *   is what makes its rows live, so the row materialization rides along.
 * - `materializeApplied` — only when an ADR-0086 P2 publish materializer is
 *   registered for the type (e.g. `flow`, whose draft credentials become the
 *   live ones).
 * - `projectionApplied` — only when an ADR-0094 mutation projector is
 *   registered for the type. Same field, same meaning, as on
 *   {@link SaveMetaItemResponseSchema}: both write doors run the projector.
 *
 * All three are **best-effort by contract**: publishing the metadata always
 * succeeds independently, and a side-effect failure is SURFACED here rather
 * than thrown. So `success: true` on the envelope does not mean the data plane
 * caught up — a caller that needs it live must read the receipt's own
 * `success`, which is why every receipt carries one.
 *
 * **`advisories` is the fourth conditional key** (#9176, mirroring #4717 one
 * door over): the #4463 runtime authoring gate runs on BOTH write doors by
 * D1 — a draft→active promotion is gated exactly as a direct active save —
 * and its non-blocking findings ride the 2xx of whichever door earned it.
 * Until #9176 only the save door reported; the promotion call site received
 * the gate's advisory return and discarded it, which mattered precisely
 * because Studio's designer takes draft-then-publish on every edit, so the
 * one door its authors actually use was the one that said nothing.
 */
export const PublishMetaItemResponseSchema = lazySchema(() => z.object({
  success: z.boolean().describe(
    'Always true on a 2xx — the draft was promoted. It does NOT cover the '
    + 'best-effort side effects below, each of which reports its own `success`.',
  ),
  version: z.string().describe(
    'Version token of the row this promotion left, and the token the ADR-0008 '
    + 'optimistic-concurrency chain runs on: send it back as the `If-Match` '
    + 'request header on the next write to that item and a concurrent edit is '
    + 'refused 409 `METADATA_CONFLICT` instead of silently overwritten. A keyed '
    + 'digest of the stored content hash, never the hash itself — the same form '
    + '`SaveMetaItemResponseSchema.version` and the item read\'s `version` '
    + 'serve. Opaque to callers — echo it verbatim, never parse it. Currently '
    + 'emitted as `hmac-sha256:` plus 64 hex characters, but the format is not '
    + 'part of this contract.',
  ),
  seq: z.number().int().describe(
    'Monotonic sequence number of the `op=\'publish\'` metadata event this '
    + 'promotion appended to the item history (sys_metadata_history.event_seq). '
    + 'Orders writes; unlike `version` it is not an OCC token.',
  ),
  seedApplied: z.object({
    success: z.boolean().describe(
      'False when the seed rows did not fully land. The publish itself still '
      + 'succeeded — check this rather than assuming data went live.',
    ),
    inserted: z.number().int().describe('Rows created by the externalId-keyed upsert.'),
    updated: z.number().int().describe('Rows updated by the externalId-keyed upsert.'),
    error: z.string().optional().describe(
      'Single failure message, present when the seed apply threw before the '
      + 'loader ran (including "no readable seed bodies").',
    ),
    errors: z.array(z.unknown()).optional().describe(
      'Per-record failures reported by the seed loader. Present only when the '
      + 'loader ran and returned a non-empty error list.',
    ),
  }).optional().describe(
    'Outcome of materializing a published `seed` body into data rows. Present '
    + 'ONLY when the published type is `seed` — publishing a seed is what makes '
    + 'its rows live, so the load rides along with the metadata promotion. '
    + 'Best-effort: a seed-load problem is surfaced here, never thrown, so a '
    + 'caller must check `seedApplied.success` instead of assuming the 200 '
    + 'covered the data. Absent on the batch path, which suppresses the '
    + 'per-item apply and loads every seed body in one later pass.',
  ),
  materializeApplied: z.object({
    success: z.boolean().describe('False when the materializer threw or reported failure; the publish still succeeded.'),
    inserted: z.number().int().describe('Data-plane rows created by the materializer.'),
    updated: z.number().int().describe('Data-plane rows updated by the materializer.'),
    error: z.string().optional().describe('Materializer failure message, present only when `success` is false.'),
  }).optional().describe(
    'Outcome of the ADR-0086 P2 publish-time materializer — the step that '
    + 'applies the published body to its data-plane state (e.g. `flow`, whose '
    + 'draft credentials become the live ones). Present ONLY when a '
    + 'materializer is registered for this metadata type, which is why it is '
    + 'optional: its absence means "no materializer ran", never "it failed". '
    + 'Best-effort, same contract as `seedApplied`.',
  ),
  projectionApplied: z.object({
    success: z.boolean().describe('False when the projector threw; the metadata promotion itself still succeeded.'),
    error: z.string().optional().describe('Projector failure message, present only when `success` is false.'),
  }).optional().describe(
    'Outcome of the awaited ADR-0094 mutation projector — the post-persist step '
    + 'that materializes this metadata into its derived data-plane read model. '
    + 'The same receipt {@link SaveMetaItemResponseSchema} carries, because the '
    + 'projector runs on BOTH write doors: a direct active save and this '
    + 'draft→active promotion. Present ONLY when a projector is registered for '
    + 'this metadata type. Best-effort — a projector failure is reported here '
    + 'and logged, never thrown.',
  ),
  advisories: z.array(RuntimeAuthoringIssueSchema).optional().describe(
    'Non-gating findings from the runtime authoring gate — the same '
    + 'shared author-time rules `os validate` / `os build` / `os lint` run, '
    + 'applied to the DRAFT body this promotion carried to `active` ('
    + 'the same key `SaveMetaItemResponseSchema` carries, because the gate '
    + 'runs on both write doors, D1). The promotion SUCCEEDED; these '
    + 'are what the gate has to say about it anyway. Present ONLY when at '
    + 'least one advisory was raised — an empty array is never emitted, so a '
    + 'clean publish\'s response bytes are unchanged and absence means '
    + '"nothing to report", never "the gate did not run". Advisory by '
    + 'construction: every entry has `severity` `warning` or `info`, because '
    + 'an `error` finding refuses the promotion and arrives as the 422 '
    + '`invalid_metadata` envelope instead of here. A caller that ignores '
    + 'this key behaves exactly as before. This door is the one Studio\'s '
    + 'designer takes on every edit (draft save, then publish), and a Studio '
    + '/ MCP / AI author has no CLI at all — which is the gap this key exists '
    + 'to close.',
  ),
  message: z.string().optional().describe(
    'Human-readable receipt, e.g. `Published draft — type=view, name=cases '
    + '[seq=3]`. The producer sets it on every publish today; it stays optional '
    + 'to match the producer\'s own signature and its `SaveMetaItemResponse` '
    + 'twin, and because an absent human-readable string strips no data — the '
    + 'failure mode this key exists to prevent.',
  ),
}));

/**
 * Publish Package Drafts Response — the "publish whole app" door.
 *
 * Describes the FULL body `POST /api/v1/packages/:id/publish-drafts` answers
 * inside the dispatcher's `{ success, data }` envelope (#9406 — the #5745
 * "declared = returned" discipline carried to the batch door, the same move
 * #7294 made for the single-item `POST /meta/:type/:name/publish`). Until this
 * declaration the batch response was only an inline TypeScript return type in
 * `@objectstack/metadata-protocol` — no spec schema, no pin suite, no
 * conformance gate — so a field added to or dropped from Studio's "publish
 * whole app" response could not turn anything red (#9343's discarded
 * advisories were the measured instance).
 *
 * **The wire face is the helper's return PLUS the route's mutations** —
 * measured on the producer pair, not assumed:
 *
 * - `ObjectStackProtocolImplementation.publishPackageDrafts` builds the base
 *   object. Its three return sites always set `success` / `outcome` /
 *   `publishedCount` / `failedCount` / `published` / `failed` (so those six
 *   are REQUIRED), and
 *   attach `seedApplied` / `materializeApplied` / `probes` / `commitId` /
 *   `backfillApplied` (#24253, only when the request named a `backfill`) only
 *   on the happy path when the corresponding fact exists (so each is
 *   optional — absence means "did not apply", never "failed").
 * - The REST door (`packages/runtime/src/domains/packages.ts`) then mutates
 *   that object before `res.json()`: it back-fills `seedApplied` for custom
 *   protocols that do not self-apply, and attaches the ADR-0045 visibility
 *   flip receipts `unhiddenApps` / `unhideError` and the `metadata:reloaded`
 *   announce receipt `rebindError`. Those keys are ON the wire, so they are
 *   declared here — a schema of the helper's raw return would strip them.
 *
 * **`success` is the batch verdict, not an HTTP echo**: the producer sets
 * `failed.length === 0 && published.length > 0`, and the two refusal returns
 * (pre-flight violations; the ADR-0067 D2 all-or-nothing rollback) answer
 * `success: false` on a 200 with `publishedCount: 0`, `published: []` and the
 * whole batch in `failed[]` (`BATCH_ABORTED` marks the non-causal items).
 * `success: false` alone does NOT mean a refusal — a publish with no pending
 * drafts answers it too, with `failed: []`; `outcome` (#10462) names which of
 * the three exits answered, so no consumer has to reverse-engineer that from
 * `failed.length`.
 *
 * **`probes` is deliberately OPAQUE** — see its own note below. Do not model
 * it here without a consumer-driven card (#9406 ruling).
 */
export const PublishPackageDraftsResponseSchema = lazySchema(() => z.object({
  success: z.boolean().describe(
    'True only when every pending draft promoted (`failed` empty) AND at '
    + 'least one item published. A pre-flight refusal or an ADR-0067 D2 '
    + 'rollback answers false on a 200 — but so does a publish with nothing '
    + 'to promote, so false alone is NOT a refusal: read `outcome`, '
    + 'not this boolean or the HTTP status. Always equal to '
    + '`outcome === \'published\'` (pinned). It does NOT cover the '
    + 'best-effort receipts below, each of which reports its own `success`.',
  ),
  outcome: z.enum(['published', 'refused', 'nothing_to_publish']).describe(
    'First-class discriminant for WHICH exit answered — the fact '
    + '`success` compresses into one boolean. `published`: at least one draft '
    + 'promoted and none refused. `refused`: the batch was refused — a '
    + 'pre-flight violation or the ADR-0067 D2 all-or-nothing rollback; the '
    + 'per-item story is in `failed[]`, which is non-empty exactly on this '
    + 'outcome (the invariant consumers previously had to reverse-engineer, '
    + 'now stated by the producer). `nothing_to_publish`: the package had no '
    + 'pending drafts — nothing landed AND nothing was refused; `success` '
    + 'stays false (a no-op is not a successful publish), which before this '
    + 'field made that answer indistinguishable from a refusal. Producer '
    + 'invariants, pinned in the conformance suites: '
    + '`success === (outcome === \'published\')`; `refused` if and only if '
    + '`failed.length > 0`; `nothing_to_publish` if and only if '
    + '`published.length === 0 && failed.length === 0`. Values are lowercase '
    + 'snake, matching the `sys_metadata_audit` outcome vocabulary.',
  ),
  publishedCount: z.number().int().describe(
    'Number of drafts promoted to active — `published.length`. 0 on every '
    + 'refusal path (the batch is all-or-nothing, ADR-0067 D2).',
  ),
  failedCount: z.number().int().describe(
    'Number of items that did not publish — `failed.length`. On a rollback '
    + 'this counts the WHOLE batch: the causal item plus every sibling '
    + 'marked BATCH_ABORTED.',
  ),
  published: z.array(z.object({
    type: z.string().describe('Metadata type of the promoted draft (canonical singular).'),
    name: z.string().describe('Item name of the promoted draft.'),
    version: z.string().describe(
      'Version token of the promoted row — the same keyed ADR-0008 '
      + 'optimistic-concurrency token the single-item doors return: echo it '
      + 'back as `If-Match` on the next write to this item. A keyed digest of '
      + 'the stored content hash, never the hash itself. Opaque to callers; '
      + 'currently `hmac-sha256:` plus 64 hex characters, but the format is '
      + 'not part of this contract.',
    ),
    advisories: z.array(RuntimeAuthoringIssueSchema).optional().describe(
      'Non-gating findings the runtime authoring gate raised against '
      + 'THIS draft\'s promotion (the same element shape and the '
      + 'same omitted-when-empty discipline as '
      + '`PublishMetaItemResponseSchema.advisories`, riding each element '
      + 'rather than a parallel top-level map). Present ONLY when at least '
      + 'one finding was raised — an empty array is never emitted, so an '
      + 'advisory-free batch\'s response bytes are unchanged. Advisory by '
      + 'construction: every entry is `warning`/`info`, because an `error` '
      + 'finding refuses the promotion and — the batch being all-or-nothing '
      + '— aborts the whole batch as `failed[]` instead; `failed[]` '
      + 'elements never carry this key.',
    ),
  })).describe(
    'Every draft promoted to active, in publish order. Empty on every '
    + 'refusal path.',
  ),
  failed: z.array(z.object({
    type: z.string().describe('Metadata type of the item that did not publish.'),
    name: z.string().describe('Item name.'),
    error: z.string().describe(
      'What refused it. On a rollback, the causal item carries its real '
      + 'error and every sibling carries the all-or-nothing explanation. '
      + 'A refusal that produced structured findings states a one-sentence '
      + 'HEADLINE here (what failed, where, which rules, how many); the '
      + 'per-path detail rides `issues[]` instead of being restated in this '
      + 'string (consumers rendering both channels were showing '
      + 'every finding twice).',
    ),
    code: z.string().optional().describe(
      'Machine code for the refusal class (SCREAMING_SNAKE, ADR-0112 '
      + 'vocabulary) — e.g. a pre-flight violation code, or BATCH_ABORTED '
      + 'on the non-causal items of a rolled-back batch.',
    ),
    issues: z.array(RuntimeAuthoringIssueSchema).optional().describe(
      'The structured findings behind the refusal, when the refusing error '
      + 'carried them — today the author-time gate\'s '
      + 'INVALID_METADATA refusal on the causal item. The producer has '
      + 'emitted this key; declaring it is what lets a '
      + 'typed consumer read it back, and what lets `error` stay a headline '
      + 'without losing the per-path detail. Same element shape as '
      + '`published[].advisories` and the single-item 422\'s `issues[]` '
      + '(— one dialect, declared once). Present ONLY on the causal '
      + 'item and only when the refusal produced structured findings; '
      + 'BATCH_ABORTED siblings never carry it. Absent means "this refusal '
      + 'carried no structured findings", never "no problems".',
    ),
  })).describe(
    'Items that did not publish. Because the batch is all-or-nothing '
    + '(ADR-0067 D2), a non-empty list means NOTHING landed: '
    + '`published: []`, `publishedCount: 0`.',
  ),
  seedApplied: z.object({
    success: z.boolean().describe(
      'False when the seed rows did not fully land. The publish itself '
      + 'still succeeded — check this rather than assuming data went live.',
    ),
    inserted: z.number().int().optional().describe(
      'Rows created by the externalId-keyed upsert. Optional ONLY because '
      + 'the route-level fallback producer (custom protocols that do not '
      + 'self-apply) reports early failures without counters; the in-batch '
      + 'producer always emits both counters.',
    ),
    updated: z.number().int().optional().describe(
      'Rows updated by the externalId-keyed upsert. Same optionality '
      + 'rationale as `inserted`.',
    ),
    error: z.string().optional().describe(
      'Single failure message, present when the apply failed before the '
      + 'loader ran (including "no readable seed bodies"). When the failure '
      + 'is the seed bodies\' own schema refusal, this is a one-sentence '
      + 'headline and the per-path detail rides `issues[]`.',
    ),
    errors: z.array(z.unknown()).optional().describe(
      'Per-record failures reported by the seed loader, plus any seed-body '
      + 'read failures. May be present and empty on a clean load.',
    ),
    issues: z.array(z.object({
      path: z.string().describe(
        'Dotted config path inside the submitted seed set (`seeds.0.mode`), '
        + 'so an author can jump to the offending key. May be empty for a '
        + 'whole-request finding.',
      ),
      message: z.string().describe('What is wrong, in the schema\'s own words.'),
      code: z.string().optional().describe(
        'Zod\'s own issue code, verbatim — deliberately NOT the ADR-0114 '
        + '`fields[]` vocabulary (the decision: this is a '
        + 'metadata-authoring diagnostic and its consumers read raw zod '
        + 'codes; aligning the vocabularies is a separate decision).',
      ),
    })).optional().describe(
      'Structured spec-validation findings behind `error`, present when the '
      + 'apply was refused by the seed bodies\' own schema — the declared '
      + '422 `seedRequestValidationError` mints. The per-path '
      + 'detail lives HERE, once; `error` stays a one-sentence headline'
      + '. Absent on non-validation failures (driver faults, '
      + 'unreadable bodies), whose whole story is `error` / `errors[]`.',
    ),
  }).optional().describe(
    'Aggregate outcome of materializing EVERY published `seed` body in one '
    + 'multi-pass loader run (cross-seed references need the whole set). '
    + 'Present ONLY when the batch published at least one seed. Two '
    + 'producers, one key: the batch itself self-applies '
    + '(`applySeedBodies`), and the REST door back-fills the same key for '
    + 'custom protocols that do not — never both (an externalId-less seed '
    + 'would double-insert). Best-effort: a seed problem is surfaced here, '
    + 'never thrown.',
  ),
  materializeApplied: z.object({
    success: z.boolean().describe('False when any item\'s materializer failed; the publish still succeeded.'),
    inserted: z.number().int().describe('Data-plane rows created across the batch.'),
    updated: z.number().int().describe('Data-plane rows updated across the batch.'),
    failures: z.array(z.object({
      type: z.string().describe('Metadata type of the item whose projection did not land.'),
      name: z.string().describe('Item name.'),
      error: z.string().describe('Why the projection did not land.'),
    })).describe(
      'Each item whose data-plane projection did NOT land — named '
      + 'per-item, unlike the single-item door\'s scalar `error`, because '
      + 'one aggregate boolean over N items would hide WHICH ones never '
      + 'went live.',
    ),
  }).optional().describe(
    'ADR-0086 P2 — aggregate result of publish-time materializers across '
    + 'the batch (e.g. `flow`, whose draft credentials become the live ones), including '
    + 'side-effect failures surfaced by the per-item effects loop. Present '
    + 'ONLY when at least one published item had a registered materializer '
    + 'or a side-effect failure. Best-effort, same contract as '
    + '`seedApplied`.',
  ),
  // #9406 ruling: `probes` (`BuildProbeReport`) gets a DELIBERATELY OPAQUE
  // passthrough declaration — the key is declared so the face is complete and
  // nothing strips it, but its inner shape is NOT modeled here. It upgrades to
  // a modeled Zod schema only when a consumer needs a field of it (maintainer,
  // 2026-08-18: "Do not model it speculatively"). The TS shape lives on
  // `packages/metadata-protocol/src/build-probes.ts` (`BuildProbeReport`:
  // `issues[]` + per-plane `checked` counters).
  probes: z.unknown().optional().describe(
    'ADR-0038 L3 post-publish runtime probe report — one real read per '
    + 'published artifact (seeded objects have rows, views are readable, '
    + 'widget dataset selections execute). DELIBERATELY OPAQUE in this '
    + 'contract: the key is declared and carried through verbatim, '
    + 'but its inner shape is intentionally not modeled until a consumer '
    + 'needs a field of it. Present only when something was publishable; '
    + 'probes never fail the publish.',
  ),
  commitId: z.string().optional().describe(
    'ADR-0067 — id of the commit this publish recorded. Absent when '
    + 'nothing published.',
  ),
  backfillApplied: z.object({
    success: z.boolean().describe(
      'False when any field stopped short (its entry carries `error`). The '
      + 'publish itself still succeeded and is not undone.',
    ),
    fields: z.array(z.object({
      object: z.string().describe('Object the backfilled field belongs to.'),
      field: z.string().describe('The field this publish added and the request named.'),
      updated: z.number().int().describe(
        'Existing rows this publish wrote the field\'s default into, as the '
        + 'caller. A row that already held a value is not counted (on the SQL '
        + 'driver the new column\'s DEFAULT fills existing rows itself, so 0 is '
        + 'a complete answer there); nor is a row the caller cannot read. On a '
        + 'failure, the rows written before it.',
      ),
      error: z.string().optional().describe(
        'Present when this field\'s backfill stopped: the record it stopped at '
        + 'and why. Rows counted in `updated` stay written. Client-facing text '
        + 'only, same ADR-0112 withhold as `unhideError`.',
      ),
      code: z.string().optional().describe(
        'Machine code of the refusal that stopped this field, when it declared '
        + 'one (SCREAMING_SNAKE, ADR-0112 vocabulary).',
      ),
    })).describe('One element per requested field, in request order.'),
  }).optional().describe(
    'The opt-in `backfill` request key\'s receipt: the literal '
    + '`defaultValue` of each named field this publish added, written into '
    + 'the object\'s existing rows whose value is absent, page by page, as '
    + 'the caller (permissions, RLS/FLS and record hooks apply as on their '
    + 'own edit). Present ONLY when the request named at least one field and '
    + 'the batch published; absent means nothing was asked. A request that '
    + 'names a field this publish does not add, or one without a literal '
    + 'default, is refused with a 400 before anything is published, so this '
    + 'key never reports a refusal.',
  ),
  unhiddenApps: z.array(z.string()).optional().describe(
    'ADR-0045 §3 — names of the apps whose `_unpublished` gate this publish '
    + 'cleared (publish = live AND visible; a materialized additive build '
    + 'has no drafts, only this flip). Attached by the REST door, not the '
    + 'protocol helper. Present ONLY when at least one app flipped — on a '
    + 'mid-loop failure it names the apps that DID persist, beside '
    + '`unhideError` (\'s split report). Spelling is a permanent wire '
    + 'contract (see the door\'s note).',
  ),
  unhideError: z.string().optional().describe(
    'Present when the ADR-0045 visibility flip failed (wholly or partway): '
    + 'the drafts ARE published, but apps still stored `_unpublished: true` '
    + 'stay externally unobservable. Client-facing text only — undeclared '
    + 'driver text is withheld per ADR-0112; the full cause is in '
    + 'the server log. The route is idempotent: re-run it once the cause is '
    + 'resolved.',
  ),
  rebindError: z.string().optional().describe(
    'Present when the post-publish `metadata:reloaded` announce failed: '
    + 'everything is published and stored, but boot-cached consumers keep '
    + 'the pre-publish view until re-run or restart (a newly published '
    + 'record-triggered flow does not bind its trigger). Client-facing text '
    + 'only, same ADR-0112 withhold as `unhideError`.',
  ),
}));

/**
 * Delete Metadata Item Request
 * Removes a customization overlay row from sys_metadata (ADR-0005) — the
 * "reset to artifact factory default" semantic behind
 * `DELETE /api/v1/meta/:type/:name`.
 *
 * Declared member for member against the implementation's parameter type in
 * `@objectstack/metadata-protocol` and the REST reset door's actual sends — a
 * declared-surface catch-up, not a new capability (#11679, the maintainer-ruled
 * pattern of commit cccbe51bf): every member here already ships and is enforced.
 * The member existed on `MetadataProtocol` all along; the request schema
 * declared 2 of the 8 members the reset door sends, so the door's call site
 * had to stay behind an `as any` cast (removing it surfaced `TS2353` on the
 * six undeclared keys — the opposite half of the publish door's `TS2339`).
 *
 * One wire member is deliberately NOT declared: `environmentId`, the
 * transport-level multi-kernel routing key, OUT of protocol request shapes by
 * the maintainer ruling of 2026-08-18 (commit 2a29caa53) — `resolveProtocol(environmentId)`
 * selects the target kernel before this method is entered, the implementation
 * never reads it off the request, and `packages/rest` layers it on via its
 * `TransportScopedMetaRequest` wrapper.
 */
export const DeleteMetaItemRequestSchema = lazySchema(() => z.object({
  type: z.string().describe('Metadata type name'),
  name: z.string().describe('Item name'),
  parentVersion: z.string().optional().describe(
    'ADR-0008 optimistic-concurrency pin: the version token the caller '
    + 'believes is current (on the REST door, the `If-Match` request header). '
    + 'Present, a concurrent edit is reported as a 409 conflict instead of '
    + 'silently reset; absent = last-write-wins against the current row '
    + '(Studio\'s "Reset" button is unpinned).',
  ),
  actor: z.string().optional().describe(
    'Identity recorded on the delete\'s history tombstone row. On the REST '
    + 'door this is the request\'s authenticated identity (one producer) '
    + '— never a caller-supplied header. Absent, the event is recorded '
    + 'actor-less (null), deliberately not attributed to "system".',
  ),
  state: z.enum(['active', 'draft']).optional().describe(
    'Which lifecycle row to discard: `draft` discards the pending draft '
    + 'overlay only (the still-active overlay, if any, keeps serving); '
    + '`active` or absent resets the live row. Absent defaults to `active`.',
  ),
  dropStorage: z.boolean().optional().describe(
    'Destructive opt-in, default false: also drop the object\'s physical '
    + 'table after the metadata row is removed (`object` type + `active` '
    + 'state only; never `sys_` tables). Used by the "discard a previewed '
    + 'object" flow so a publish-to-preview leaves no orphan table.',
  ),
  member: z.string().optional().describe(BUNDLE_MEMBER_SELECTOR_DESCRIPTION),
  packageId: z.string().nullable().optional().describe(
    'ADR-0048 — the software package whose row this delete removes '
    + '(`sys_metadata.package_id`; `?package=<id>` on the REST door, where '
    + '`all` and an empty value name no package), as a save names the row it '
    + 'writes. Named, the delete removes that package\'s row and no other; a '
    + 'package that holds no row removes nothing. Absent or `null` names no '
    + 'package: the delete of the `active` row then removes the row of the '
    + 'one package the item\'s active rows are bound to, is refused `409 '
    + 'RESOURCE_CONFLICT` when they are bound to two or more, and with none '
    + 'removes the env-local row (no package stamp); the discard of the '
    + '`draft` removes the draft a draft save naming no package writes, the '
    + 'one the per-item publish naming none promotes, and is refused where '
    + 'that publish is (see `PublishMetaItemRequestSchema.packageId`). That '
    + 'row is the one `parentVersion` is judged against. When another row of '
    + 'the item is '
    + 'still stored afterwards, the receipt `message` names it.',
  ),
}));

/**
 * Delete Metadata Item Response
 *
 * Describes the FULL body `DELETE /api/v1/meta/:type/:name` returns (#13155 —
 * the #5745 ruling carried to the third verb on this door). `reset === true`
 * means a row was deleted; `reset === false` means the delete's address held
 * no row, so nothing was removed. Either way the item is at its artifact
 * default only when no other row of it is still stored, and the `message`
 * names any that is (ADR-0048: one row per package).
 *
 * **Why the widening.** The metadata door has three write verbs, all running
 * the same ADR-0094 mutation projector and the same history append, and all
 * three put `seq` (and `projectionApplied`, when a projector is registered) on
 * the wire. #5745 ("补齐 spec 字段", the #5563 maintainer ruling) filled the gap
 * on {@link SaveMetaItemResponseSchema} and #7294 carried it to
 * {@link PublishMetaItemResponseSchema}; this declaration alone stopped at
 * `{ success, reset, message }`, so a `.parse()` of a real reset response
 * silently STRIPPED both keys and `DeleteMetaItemResponse` could not name them
 * at the type level. That is a decision made for one verb and never carried to
 * its sibling, not a fresh question — the two keys below are the siblings'
 * own, unchanged in type and meaning.
 *
 * ⚠️ DECLARATION change only — zero runtime behaviour is altered, and nothing
 * here says the wire was wrong. The wire is right and the two siblings already
 * agree with it; the third declaration was short.
 *
 * **Presence was measured against `origin/main`, not assumed.** The sole
 * producer is `ObjectStackProtocolImplementation.deleteMetaItem`, whose return
 * the REST route hands to `res.json()` verbatim (`rest-server.ts`, the reset
 * door), so the protocol return IS the wire body. That method has exactly FOUR
 * success returns, and they are why both new keys are optional here while
 * `seq` is REQUIRED on both siblings:
 *
 * - **repository path, row deleted** — the only return that carries either
 *   key: `seq` always, `projectionApplied` when a projector is registered.
 * - **repository path, no row** ("nothing to delete" / "already at artifact
 *   default") — a success/no-op that appends no history event, so there is no
 *   sequence number to report.
 * - **legacy raw-engine path, row deleted** — reachable in control-plane
 *   bootstrap for a code-only type (#5264, deliberately alive). It writes no
 *   history row and emits no watch event, so it carries no `seq` either; its
 *   receipt message omits the `[seq=…]` suffix for the same reason.
 * - **legacy raw-engine path, no row** — same no-op as above.
 *
 * So `seq` absent means "this branch appended no history event", NEVER "the
 * delete did not happen", and `projectionApplied` absent means "no projector
 * ran", never "the projection failed" — the same reading its siblings declare.
 *
 * Two keys the siblings carry are deliberately NOT declared, because this
 * branch provably never sends them: `version` (a delete mints no new content
 * hash — the row is gone, so there is no ADR-0008 OCC token to echo) and
 * `advisories` (the #4463 runtime authoring gate runs on the two WRITE doors
 * by D1; a delete submits no body for it to judge).
 */
export const DeleteMetaItemResponseSchema = lazySchema(() => z.object({
  success: z.boolean(),
  reset: z.boolean().optional(),
  seq: z.number().int().optional().describe(
    'Monotonic sequence number of the metadata event this delete appended to '
    + 'the item history (sys_metadata_history.event_seq) — the ordering token '
    + 'the history/audit trail is read by, and the same key both write-verb '
    + 'siblings declare. Unlike `version` it is not an OCC token. Optional '
    + 'HERE, unlike on those siblings, because only the repository path\'s '
    + 'delete-ful branch appends an event: a no-op reset (no overlay row '
    + 'existed) and the control-plane legacy raw-engine path both answer '
    + 'without one. Absence means "this branch appended no history event", '
    + 'never "nothing was deleted" — read `reset` for that.',
  ),
  projectionApplied: z.object({
    success: z.boolean().describe('False when the projector threw; the metadata delete itself still succeeded.'),
    error: z.string().optional().describe('Projector failure message, present only when `success` is false.'),
  }).optional().describe(
    'Outcome of the awaited ADR-0094 mutation projector — the post-persist step '
    + 'that materializes this metadata into its derived data-plane read model. '
    + 'The same receipt {@link SaveMetaItemResponseSchema} and '
    + '{@link PublishMetaItemResponseSchema} carry, because the projector runs '
    + 'on all three verbs of this door: on a delete it re-reads the layered '
    + 'state and either retires the derived record or resets it to the artifact '
    + 'baseline. Present ONLY when a projector is registered for this metadata '
    + 'type AND a row was actually deleted, which is why it is optional: its '
    + 'absence means "no projector ran", never "the projection failed". '
    + 'Best-effort by design — a projector failure is reported here and logged, '
    + 'never thrown, so a caller that needs the read model to be live must '
    + 'check `projectionApplied.success` rather than rely on the 200.',
  ),
  message: z.string().optional(),
}));

/**
 * Audit Metadata Item Request
 *
 * Request shape for `GET /api/v1/meta/:type/:name/audit` (the `auditMetaItem`
 * protocol method) — the ADR-0010 §3.6 compliance trail: recent
 * `sys_metadata_audit` rows (save/publish/rollback/delete/reset attempts, both
 * allowed and denied) that Studio's 审计日志 / Audit log tab renders. Mirrors
 * the implementation's parameter type in `@objectstack/metadata-protocol`
 * member for member — a declared-surface catch-up, not a new capability
 * (the maintainer-ruled pattern of commit cccbe51bf, 2026-08-22 option B, carried one door
 * over): the verb and every member here already ship and are enforced.
 *
 * `environmentId` is deliberately NOT declared — the transport-level
 * multi-kernel routing key is OUT of protocol request shapes by the
 * maintainer ruling (2026-08-18, commit 2a29caa53): `resolveProtocol(environmentId)` selects the
 * target kernel before this method is entered, and the implementation never
 * reads it off the request (the REST audit door stopped sending it when #8747
 * scoped the read).
 */
export const AuditMetaItemRequestSchema = lazySchema(() => z.object({
  type: z.string().describe('Metadata type name'),
  name: z.string().describe('Item name'),
  limit: z.number().optional().describe(
    'Maximum events to return, newest first. The implementation clamps to '
    + '[1, 500] and defaults to 100 — out-of-range values are clamped, never '
    + 'refused.',
  ),
}));

/**
 * Audit Metadata Item Response
 *
 * The body of `GET /api/v1/meta/:type/:name/audit`, mirrored member for member
 * from the implementation's return type (`ObjectStackProtocolImplementation
 * .auditMetaItem`), newest event first.
 *
 * **What an empty `events` means, and what it deliberately does NOT mean**
 * (#9426 / ADR-0110 D3 — a MISS and a FAULT are different facts): `[]` is the
 * honest answer for a genuinely clean trail, for a host engine that exposes no
 * `find` (a metadata-only store), and for an environment whose audit table has
 * not been provisioned. It is NEVER the answer for a protocol that lacks the
 * verb — the REST door refuses 501 before the call — nor for a failed read: a
 * non-benign read failure (connection drop, timeout, permission denial)
 * propagates as an error rather than being invented into an empty trail
 * (#9638).
 */
export const AuditMetaItemResponseSchema = lazySchema(() => z.object({
  events: z.array(z.object({
    id: z.unknown().describe('Row id of the audit event. Opaque to callers.'),
    occurredAt: z.string().describe('When the attempt happened (ISO-8601 string).'),
    actor: z.string().describe(
      'Who attempted the operation. `system` when the row recorded no actor.',
    ),
    source: z.string().nullable().describe(
      'Which code path recorded the event (e.g. `protocol.deleteMetaItem`). '
      + '`null` when the row recorded none.',
    ),
    operation: z.enum(['save', 'publish', 'rollback', 'delete', 'reset']).describe(
      'Which metadata-protection door was attempted.',
    ),
    outcome: z.enum(['allowed', 'denied', 'forced']).describe(
      'Whether the attempt went through, was refused, or overrode a lock '
      + '(ADR-0010 §3.6).',
    ),
    code: z.string().describe(
      'Machine-readable verdict code for the outcome (e.g. `item_locked`). '
      + 'Empty string when the row recorded none.',
    ),
    lockState: MetadataLockSchema.nullable().describe(
      'The lock verdict in force at the time of the attempt (ADR-0010 §3.3). '
      + '`null` when no lock applied.',
    ),
    lockOverridden: z.boolean().describe(
      'True when the attempt went through by overriding a lock (`outcome: '
      + '"forced"` rows).',
    ),
    requestId: z.string().nullable().describe(
      'Correlation id of the originating request. `null` when the row '
      + 'recorded none.',
    ),
    note: z.string().nullable().describe(
      'Free-text note recorded with the event. `null` when the row recorded '
      + 'none.',
    ),
  })).describe(
    'Recent protection-audit events for the item, newest first. See the '
    + 'schema-level note for what an empty array means — and what it never '
    + 'means.',
  ),
}));

/**
 * History Metadata Item Request
 *
 * Request shape for `GET /api/v1/meta/:type/:name/history` (the
 * `historyMetaItem` protocol method) — the durable change-log for one item:
 * the `sys_metadata_history` events (every overlay put/delete, ADR-0008 §2.4)
 * that Studio's History tab renders as a timeline. Mirrors the
 * implementation's parameter type in `@objectstack/metadata-protocol` member
 * for member — a declared-surface catch-up, not a new capability (the maintainer-ruled
 * pattern of commit cccbe51bf, 2026-08-22 option B, carried one door over
 * exactly as #11678 carried it to the audit twin): the verb and every member
 * here already ship and are enforced.
 *
 * `environmentId` is deliberately NOT declared — the transport-level
 * multi-kernel routing key is OUT of protocol request shapes by the
 * maintainer ruling (2026-08-18, commit 2a29caa53): `resolveProtocol(environmentId)` selects
 * the target kernel before this method is entered, and the implementation
 * never declares or reads it off the request. Unlike the audit twin (whose
 * door stopped sending it when #8747 scoped the read), the REST history door
 * still spreads it into the outgoing payload; that long-standing wire member
 * rides the door's `TransportScopedMetaRequest` wrapper, never this schema.
 */
export const HistoryMetaItemRequestSchema = lazySchema(() => z.object({
  type: z.string().describe('Metadata type name'),
  name: z.string().describe('Item name'),
  sinceSeq: z.number().optional().describe(
    'Exclusive lower bound on `seq` for pagination: only events with '
    + '`seq > sinceSeq` are returned. Absent means "from the beginning".',
  ),
  limit: z.number().optional().describe(
    'Maximum events to return, oldest first. Forwarded to the repository '
    + 'unclamped and with NO default — absent means the full remaining '
    + 'change log. (Deliberately no declared bounds: unlike the audit '
    + 'twin\'s [1, 500] clamp, nothing on this path clamps or refuses, so '
    + 'declaring `.min()`/`.max()` here would refuse values the shipped '
    + 'verb accepts.)',
  ),
  member: z.string().optional().describe(BUNDLE_MEMBER_SELECTOR_DESCRIPTION),
}));

/**
 * History Metadata Item Response
 *
 * The body of `GET /api/v1/meta/:type/:name/history`, mirrored member for
 * member from the implementation's return type
 * (`ObjectStackProtocolImplementation.historyMetaItem` returns
 * `{ events: MetadataEvent[] }`), in `seq` order — oldest first, the
 * opposite end of the log from the audit twin's newest-first trail.
 *
 * The event shape transcribes `MetadataEventSchema` from
 * `@objectstack/metadata-core` (ADR-0008 §2.4) — the spec cannot import that
 * package (dependency direction), so the shape is transcribed here the same
 * way the audit twin transcribed its event rows (#11678). Two deliberate
 * widenings against the source schema, both because a declared-surface
 * catch-up must not refuse bodies the shipped verb yields: `ref.type` is a
 * plain string rather than the static metadata-type registry enum (plugin
 * runtime-create types flow through this door and are registry-absent by
 * design — freezing the registry into this contract is the same drift the
 * #12038 1C ruling refused for the published-body route), and `ref.name`
 * carries no spelling regex.
 *
 * `{ events: [] }` is the honest answer for a genuinely empty change log AND
 * for a non-overlay metadata type (neither `allowEnvironmentOverlay` nor
 * `allowRuntimeCreate`): such types have no history by construction —
 * `saveMetaItem` refuses them outright (#5086) — and the implementation
 * answers `[]` rather than throwing so callers can treat "no history"
 * uniformly. It is NEVER the answer for a protocol that lacks the verb: the
 * REST door refuses 501 before the call.
 */
export const HistoryMetaItemResponseSchema = lazySchema(() => z.object({
  events: z.array(z.object({
    seq: z.number().int().nonnegative().describe(
      'Sequence number this write produced in the org log '
      + '(sys_metadata_history.event_seq) — the token the request\'s '
      + '`sinceSeq` filters on, and the same key the write-verb receipts '
      + '(`SaveMetaItemResponseSchema.seq` and siblings) carry.',
    ),
    op: z.enum(['create', 'update', 'delete', 'rename', 'publish', 'revert']).describe(
      'Which change-log operation the event records (ADR-0008 §2.4). Closed '
      + 'vocabulary, mirrored from the producer\'s own enum.',
    ),
    ref: z.object({
      org: z.string().describe(
        'Tenant/org partition the row lives in; `env` for the env-wide '
        + 'partition, `system` for built-ins.',
      ),
      type: z.string().describe(
        'Canonical singular metadata type key. A plain string by intent — '
        + 'plugin runtime-create types flow through this door and are '
        + 'registry-absent by design (see the schema-level note).',
      ),
      name: z.string().describe('Item machine name.'),
      version: z.string().optional().describe(
        'Optional version pin (content hash); omitted for HEAD.',
      ),
    }).describe('Which item the event is about.'),
    hash: z.string().nullable().describe(
      'Content hash of the body this event wrote; `null` when the event '
      + 'wrote none (`op="delete"`).',
    ),
    parentHash: z.string().nullable().describe(
      'Hash the written version was derived from; `null` for a first '
      + 'version.',
    ),
    version: z.number().int().positive().optional().describe(
      'Per-(org,type,name) monotonic lineage counter at this event — the '
      + 'token `rollbackMetaItem({ toVersion })` pins. Absent when the row '
      + 'recorded none.',
    ),
    previousName: z.string().optional().describe('Set on op="rename": the old machine name.'),
    actor: z.string().nullable().describe(
      'Who wrote this. `null` = system-initiated (boot sync, migration, '
      + 'scheduled job) — never a sentinel string: consumers that '
      + 'resolve this against `sys_user` must be able to tell "nobody" from '
      + '"a user id".',
    ),
    message: z.string().optional().describe('Optional commit message recorded with the write.'),
    ts: z.string().describe('When the write happened (ISO-8601 string).'),
    source: z.string().describe(
      'Which code path wrote the event: an open label the server stamps, not '
      + 'an enum an author or client picks from (e.g. `protocol.saveMetaItem`, '
      + '`protocol.publishMetaItem`, `migrate-stored`). The history row\'s '
      + 'stored value is passed through; `sys-metadata-repo` is the '
      + 'repository\'s own default and the answer for a row that stored none.',
    ),
  })).describe(
    'The durable change-log for the item, oldest first. See the '
    + 'schema-level note for what an empty array means — and what it never '
    + 'means.',
  ),
}));

// ==========================================
// Meta history / diagnostics family (#12038)
// ==========================================
//
// The response contracts for the previously-unbound `meta.*` history /
// diagnostics routes, ruled on 2026-08-27 (#12038, 1C · 2C · 3A · 4A · 5A).
// Every schema below is a DESCRIBE-ONLY TRANSCRIPTION of the return type its
// producer in `@objectstack/metadata-protocol` already declares inline —
// authoring one changes no wire byte. The route-ledger rows that name these
// schemas state which surface's envelope they describe (the dispatcher wraps
// `{ success, data }`; the REST server answers the payload bare — #12038
// survey §8.1); each schema here is the PAYLOAD, envelope-free, so one
// declaration is true on both surfaces.
//
// `meta.migrateStored` (`POST /meta/_migrate-stored`) is DELIBERATELY ABSENT
// (#12038 ruling 2C): its only named type, `StoredMigrationReport`, lives in
// `@objectstack/metadata-protocol` (`stored-migration.ts`), which
// `packages/client` cannot reach (its deps are core + spec only). A second
// declaration here would drift against the CLI that renders the same report,
// and moving the type is a cross-package architecture change with zero
// consumer pull. The route stays unbound, documented at its two ledger rows
// and in the SDK annotation.

/**
 * `GET /meta/:type/:name/published` — the published body of a metadata item
 * (ADR-0033).
 *
 * DELIBERATELY OPAQUE (#12038 ruling 1C). The route answers an arbitrary
 * metadata item body — the union over every registered metadata type — and
 * the layered producer feeding it declares that very field `z.unknown()` on
 * purpose (`GetMetaItemLayeredResponseSchema.overlay`, "LAYER 2 — the stored
 * customization row ALONE"). A discriminated union here would freeze this
 * contract against today's type registry; the body stays opaque by ruling,
 * not by omission. Two producers serve one route (the `state:'active'`
 * overlay row via `getMetaItemLayered`, else the legacy code/package
 * registry's `getPublished`) — opacity is also what keeps that fallback an
 * implementation detail rather than a declared union.
 */
export const GetPublishedMetaItemResponseSchema = lazySchema(() => z.unknown().describe(
  'The published metadata item body, opaque by ruling (1C). Shape is '
  + 'the item\'s own metadata-type schema, resolved at read time — never '
  + 'frozen into this contract.',
));

/**
 * `GET /meta/_drafts` — pending drafts (ADR-0033): metadata authored but not
 * yet published, which the active-only item lists hide.
 *
 * Transcribed from `listDrafts`'s declared return
 * (`@objectstack/metadata-protocol` `protocol.ts`).
 *
 * `label` is the one member read off the draft BODY: the only list of
 * draft-only items a client has is this one, so without it such an item can be
 * shown by its machine name alone. It is the body's own top-level `label`,
 * carried as authored. Every registered metadata type that declares a display
 * label spells it `label` at the top level, as a plain string or, on the UI
 * types, as an `I18nLabel` inline locale map — which the reader resolves the
 * way it resolves every other `I18nLabel`, since this route takes no locale.
 * `null` is the honest answer for a body that declares none; ⛔ never a
 * machine-name fallback, which would make "has a label" and "has none"
 * indistinguishable to the reader that has to choose between them.
 *
 * [#23073] `member` tells two drafts of one bundle apart: for a type whose
 * identity is a pair (`email_template`, `(name, locale)`), two languages of
 * one template are two drafts with one `type` and `name`. It is the row's
 * stored member, never read off the body, and it is the value the by-name
 * doors' `member` selector takes back.
 *
 * [#24298] Per-key provenance (which surface changed which key of the draft,
 * and when) is deliberately NOT on this row: it is
 * {@link GetMetaItemResponseSchema}'s `draftChanges`, on the strict draft read
 * Studio's properties load the item from. `updatedBy` here stays the row's
 * last actor, the same person for a copilot write and a hand edit.
 */
export const ListDraftsResponseSchema = lazySchema(() => z.object({
  drafts: z.array(z.object({
    type: z.string().describe('Metadata type name (canonical singular).'),
    name: z.string().describe('Item name.'),
    member: z.string().optional().describe(
      'The bundle member this draft is, for a metadata type whose identity is a pair (today only '
      + '`email_template`, identified by `(name, locale)`): its discriminator value (`zh-CN`), and the '
      + 'canonical member spelled out (`en-US`). Present on every draft of such a type, so two members of '
      + 'one name are two entries; absent for a type whose identity is its name alone. Pass it back as the '
      + 'by-name doors\' `member` selector (`?member=`) to read, publish or discard this draft.',
    ),
    label: I18nLabelSchema.nullable().describe(
      'The draft body\'s own top-level `label`, as authored: a plain string or an inline '
      + 'locale map (`I18nLabel`), resolved by the reader. `null` when the body declares '
      + 'none, or none this shape admits — never the item name standing in for it.',
    ),
    packageId: z.string().nullable().describe(
      'Package the draft is bound to, `null` for a package-less draft.',
    ),
    updatedAt: z.string().nullable().describe(
      'Last-touch timestamp of the draft row (ISO-8601 string), `null` when '
      + 'the row recorded none.',
    ),
    updatedBy: z.string().nullable().describe(
      'Who last touched the draft, `null` when the row recorded none.',
    ),
  })).describe('Every pending draft visible to the caller, one row per item.'),
}));

/**
 * `GET /meta/diagnostics` — the cross-type spec-validation sweep: every
 * metadata entry that fails its registered Zod schema. Powers governance
 * dashboards and doctor-style checks.
 *
 * Transcribed from `getMetaDiagnostics`'s declared return
 * (`@objectstack/metadata-protocol` `protocol.ts`). `diagnostics` is the
 * canonical `MetadataValidationResultSchema` from `@objectstack/spec/kernel`
 * — the same type the save path's 422 and the read decorators speak, and the
 * shape objectui's own `MetadataDiagnosticsSummary` independently re-declared
 * field-for-field (#12038 survey §3d).
 */
export const GetMetaDiagnosticsResponseSchema = lazySchema(() => z.object({
  entries: z.array(z.object({
    type: z.string().describe('Metadata type of the failing item.'),
    name: z.string().describe('Name of the failing item.'),
    diagnostics: MetadataValidationResultSchema.describe(
      'The spec-validation verdict for the item — the same '
      + '`MetadataValidationResult` the write path answers.',
    ),
  })).describe('One entry per item that failed validation (after filters).'),
  total: z.number().describe('Number of entries in this answer.'),
  scannedTypes: z.number().describe('How many metadata types the sweep visited.'),
  scannedItems: z.number().describe('How many items the sweep visited.'),
  stats: z.record(z.string(), z.object({
    count: z.number().describe('Items of this type present.'),
    locked: z.number().describe('Items of this type currently lock-protected.'),
    packages: z.array(z.string()).describe('Packages contributing items of this type.'),
  })).describe(
    'Per-type aggregate stats, keyed by metadata type — computed in the same '
    + 'sweep so a directory page renders tile counts and a package filter in '
    + 'one round-trip.',
  ),
}));

/**
 * `GET /meta/:type/:name/references` — reverse references: metadata items
 * that reference the addressed item. `{ references: [] }` on kernels without
 * reference tracking.
 *
 * Transcribed from `findReferencesToMeta`'s declared return
 * (`@objectstack/metadata-protocol` `protocol.ts`).
 */
export const FindReferencesToMetaResponseSchema = lazySchema(() => z.object({
  references: z.array(z.object({
    type: z.string().describe('Metadata type of the REFERRING item.'),
    name: z.string().describe('Name of the referring item.'),
    label: z.string().optional().describe('Display label of the referring item, when it has one.'),
    path: z.string().describe('Where inside the referring item the reference sits (dot path).'),
    kind: z.string().describe('What kind of reference this is (e.g. which key carries it).'),
  })).describe('Every found reference to the addressed item.'),
}));

/**
 * `POST /meta/:type/:name/rollback` — restore the body at a history version
 * as the new live row.
 *
 * Transcribed from `rollbackMetaItem`'s declared return
 * (`@objectstack/metadata-protocol` `protocol.ts`); objectui's
 * `metadata-client.ts` docblock independently documents the same five fields
 * (#12038 survey §3d).
 */
export const RollbackMetaItemResponseSchema = lazySchema(() => z.object({
  success: z.boolean().describe('Whether the rollback landed.'),
  version: z.string().describe(
    'The new live row\'s ADR-0008 optimistic-concurrency token — the same '
    + 'carrier `saveItem` returns; pass it back as `options.ifMatch`.',
  ),
  seq: z.number().describe('The new live row\'s history sequence number.'),
  restoredFromVersion: z.number().describe('Which history version was restored.'),
  message: z.string().optional().describe('Rollback note, when one was recorded.'),
}));

/**
 * `GET /meta/:type/:name/diff` — structural diff between two history
 * versions (`from`/`to`). An omitted `to` is the active version; an omitted
 * `from` is the nearest earlier version whose body differs from the `to`
 * side's (a deletion counts as an empty body).
 *
 * Transcribed from `diffMetaItem`'s declared return
 * (`@objectstack/metadata-protocol` `protocol.ts`).
 */
export const DiffMetaItemResponseSchema = lazySchema(() => z.object({
  type: z.string().describe('Metadata type of the diffed item.'),
  name: z.string().describe('Name of the diffed item.'),
  fromVersion: z.number().nullable().describe(
    'The older side\'s history version, `null` when that side is absent '
    + '(e.g. the item had no earlier version).',
  ),
  toVersion: z.number().nullable().describe(
    'The newer side\'s history version, `null` when that side is absent.',
  ),
  added: z.array(z.object({
    path: z.string().describe('Dot path of the added member.'),
    value: z.unknown().describe('The added value.'),
  })).describe('Members present in `to` and absent in `from`.'),
  removed: z.array(z.object({
    path: z.string().describe('Dot path of the removed member.'),
    value: z.unknown().describe('The removed value.'),
  })).describe('Members present in `from` and absent in `to`.'),
  changed: z.array(z.object({
    path: z.string().describe('Dot path of the changed member.'),
    from: z.unknown().describe('The older side\'s value.'),
    to: z.unknown().describe('The newer side\'s value.'),
  })).describe('Members present on both sides with different values.'),
}));

/**
 * Get Metadata Item with Cache Request
 * Get a specific metadata item with HTTP cache validation support
 */
export const GetMetaItemCachedRequestSchema = lazySchema(() => z.object({
  type: z.string().describe('Metadata type name'),
  name: z.string().describe('Item name'),
  cacheRequest: MetadataCacheRequestSchema.optional().describe('Cache validation parameters'),
  locale: z.string().optional().describe(
    'Resolved response locale. Folded into the ETag so a language switch '
    + 'never returns a stale-locale 304 — metadata is translated *after* the '
    + 'cache validator check (issue).',
  ),
}));

/**
 * Get Metadata Item with Cache Response
 * Uses MetadataCacheResponse from http-cache.zod.ts
 *
 * [#23316] …plus `registration`: the cached read is the DEFAULT door of
 * `GET /meta/flow/:name`, so the automation engine's verdict on a stored flow
 * rides it too, read live from the delegate read on every call. It is never
 * folded into `etag`, so a read that carries it is never answered
 * `notModified`: a 304 would pin the caller to the verdict it was served
 * before, which the validator cannot see change.
 */
export const GetMetaItemCachedResponseSchema = lazySchema(() => MetadataCacheResponseSchema.extend({
  registration: FlowRegistrationSchema.optional().describe(
    'The automation engine\'s verdict on the flow in `data`, read live on every call and never part of '
    + '`etag` (see `FlowRegistrationSchema`). Present only for a `flow` read answered by a process that '
    + 'runs an automation service; a read that carries it is never answered `notModified`. Absent '
    + 'otherwise, and absence means no engine judged it, never `registered`.',
  ),
}));

/**
 * Get UI View Request
 * Resolves the appropriate UI view for an object based on context.
 * Unlike getMetaItem, this does not require a specific View ID.
 */
export const GetUiViewRequestSchema = lazySchema(() => z.object({
  object: z.string().describe('Object name (snake_case)'),
  type: z.enum(['list', 'form']).describe('View type'),
}));

/**
 * Get UI View Response
 */
export const GetUiViewResponseSchema = lazySchema(() => ViewSchema);

// ==========================================
// Data Operations
// ==========================================

/**
 * Find Data Request
 * Defines a query to retrieve records from a specific object.
 * Supports filtering, sorting, pagination, and field selection.
 *
 * ## Two spellings, one semantics
 *
 * `query` declares its INPUT as the canonical QueryAST **or** its transport
 * spelling ({@link QueryTransportParamsSchema} — `$filter` / `$top` / `$skip` /
 * `$orderby` / `$select` / `$expand` and the plural `filters`), and its OUTPUT
 * as the AST plus the `count` flag: the transport keys are folded onto their
 * canonical slots by {@link QUERY_TRANSPORT_ALIAS_SLOTS} /
 * {@link QUERY_TRANSPORT_DOLLAR_ALIASES} at parse, and the folded bag is then
 * PARSED by the AST schema, so the output is constructed rather than asserted.
 * The transport form is the FLATTENED SPELLING of the same AST with a 1:1 alias
 * table — ⛔ never a second query semantics, and nothing is admitted into
 * `QuerySchema` itself.
 *
 * One semantics is a claim about VALUES too: every spelling of a slot accepts
 * one set of value shapes, each of which is lowered to the canonical member's
 * declared shape (`'50'` to `50`, a comma list to an array, the `FilterArray`
 * sugar through `parseFilterAST`) or REFUSED at the parse. A shape that would
 * need a parser the spec must not run — a JSON-encoded `$filter` string, an
 * OData sort expression, a non-numeric `$top` — fails rather than reaching a
 * consumer under the AST type; `$top: 'abc'` used to pass validation here and
 * reach the engine as `limit: null`, an unbounded read under a 200.
 *
 * This records what the door already accepted. `@objectstack/metadata-protocol`
 * has folded these spellings since #3795 while the slot declared the AST alone,
 * so every caller speaking them — objectui's published `QueryParams`, the
 * `GET /data/:object` querystring — was unverifiable at build time and
 * unrejected at runtime. A `$`-prefixed name the table does NOT carry is
 * refused at the boundary with `400 UNSUPPORTED_QUERY_PARAM`
 * ({@link QUERY_TRANSPORT_DOLLAR_PARAMS} is the quoted set).
 *
 * @example
 * {
 *   "object": "customers",
 *   "query": {
 *     "where": { "status": "active", "revenue": { "$gt": 10000 } },
 *     "orderBy": [{ "field": "name", "order": "desc" }],
 *     "limit": 10
 *   }
 * }
 * @example
 * // the same query in the transport spelling
 * { "object": "customers", "query": { "$filter": { "status": "active" }, "$top": 10 } }
 */
export const FindDataRequestSchema = lazySchema(() => z.object({
  object: z.string().describe('The unique machine name of the object to query (e.g. "account").'),
  query: QueryWithTransportSchema.optional().describe('Structured query definition (filter, sort, select, pagination) — the canonical QueryAST or its transport spelling.'),
}));

/**
 * Find Data Response
 * Returns a list of records matching the query criteria.
 */
export const FindDataResponseSchema = lazySchema(() => z.object({
  object: z.string().describe('The object name for the returned records.'),
  records: z.array(z.record(z.string(), z.unknown())).describe('The list of matching records.'),
  total: z.number().optional().describe('Total number of records matching the filter (if requested).'),
  nextCursor: z.string().optional().describe('Cursor for the next page of results (cursor-based pagination).'),
  hasMore: z.boolean().optional().describe('True if there are more records available (pagination).'),
}));

/**
 * HTTP Find Query Parameters
 * 
 * Canonical HTTP query parameter names for GET /data/:object list endpoints.
 * The canonical filter parameter is `filter` (singular). The plural `filters` is
 * accepted for backward compatibility but `filter` is the standard going forward.
 * 
 * This schema defines the allowlisted query parameters for HTTP GET list requests.
 * Server-side parsers (protocol.ts) should accept both `filter` and `filters` and
 * normalize to `filter` (singular) internally.
 * 
 * @example
 * GET /api/v1/data/contacts?filter={"status":"active"}&select=name,email&top=10&sort=name
 */
export const HttpFindQueryParamsSchema = lazySchema(() => z.object({
  /** @canonical Singular form — the standard going forward. JSON string of filter expression or AST. */
  filter: z.string().optional().describe('JSON-encoded filter expression (canonical, singular).'),
  /** @deprecated Use `filter` (singular). Accepted for backward compatibility. */
  filters: z.string().optional().describe('JSON-encoded filter expression (deprecated plural alias).'),
  select: z.string().optional().describe('Comma-separated list of fields to retrieve.'),
  sort: z.string().optional().describe('Sort expression (e.g. "name asc,created_at desc" or "-created_at").'),
  orderBy: z.string().optional().describe('Alias for sort (OData compatibility).'),
  top: z.coerce.number().optional().describe('Max records to return (limit).'),
  skip: z.coerce.number().optional().describe('Records to skip (offset).'),
  expand: z.string().optional().describe(
    'Comma-separated list of lookup/master_detail field names to expand. '
    + 'Resolved to populate array and passed to the engine for batch $in expansion.'
  ),
  search: z.string().optional().describe('Full-text search query.'),
  /** `?distinct` — REMOVED (#4286): the querystring spelling of `query.distinct`, same tombstone. */
  distinct: retiredKey(QUERY_DISTINCT_REMOVED),
  count: z.coerce.boolean().optional().describe('Include total count in response.'),
}));

/**
 * Get Data Request
 * Retrieval of a single record by its unique identifier.
 * Only `select` and `expand` are permitted as additional query parameters.
 * All other query parameters should be discarded to prevent parameter pollution.
 * 
 * @example
 * {
 *   "object": "contracts",
 *   "id": "cnt_123456",
 *   "select": ["name", "status", "amount"],
 *   "expand": ["owner", "account"]
 * }
 */
export const GetDataRequestSchema = lazySchema(() => z.object({
  object: z.string().describe('The object name.'),
  id: z.string().describe('The unique record identifier (primary key).'),
  select: z.array(z.string()).optional().describe('Fields to include in the response (allowlisted query param).'),
  expand: z.array(z.string()).optional().describe(
    'Lookup/master_detail field names to expand. '
    + 'The engine resolves these via batch $in queries, replacing foreign key IDs with full objects.'
  ),
}));

/**
 * Get Data Response
 */
export const GetDataResponseSchema = lazySchema(() => z.object({
  object: z.string().describe('The object name.'),
  id: z.string().describe('The record ID.'),
  record: z.record(z.string(), z.unknown()).describe('The complete record data.'),
}));

/**
 * Create Data Request
 * Creation of a new record.
 * 
 * @example
 * {
 *   "object": "leads",
 *   "data": {
 *     "first_name": "John",
 *     "last_name": "Doe",
 *     "company": "Acme Inc"
 *   }
 * }
 */
export const CreateDataRequestSchema = lazySchema(() => z.object({
  object: z.string().describe('The object name.'),
  data: z.record(z.string(), z.unknown()).describe('The dictionary of field values to insert.'),
}));

/**
 * One field-level finding from a validate-only run — the same
 * `{ field, code, message }` triple the engine's `ValidationError.fields`
 * carries, so a caller reads one vocabulary whether the verdict arrived from a
 * preview or from a rejected write.
 *
 * [#22726] It is also the element of every single-record write answer's
 * `warnings`, and an ADVISORY validation-rule hit additionally names its `rule`
 * and `severity` — both members taken from `ValidationAdvisoryEventSchema`
 * (`data/data-engine.zod.ts`), the event the engine reports the hit through,
 * so an event IS an issue and the write and its preview answer in one
 * vocabulary. Declared before the write answers that reference it: a schema
 * built eagerly (`OS_EAGER_SCHEMAS=1`) would otherwise read it before it exists.
 */
export const ValidateDataIssueSchema = lazySchema(() => z.object({
  field: z.string().describe('The field the finding is about (`_record` for an object-level rule).'),
  code: z.string().describe('Machine-readable finding code, e.g. `required`, `invalid_type`, `rule_violation`.'),
  message: z.string().describe('Human-readable message — a validation rule\'s author-written text where one exists.'),
  rule: ValidationAdvisoryEventSchema.shape.rule.optional().describe(
    'The `name` of the ADVISORY validation rule this finding reports. Present only on an advisory rule hit.',
  ),
  severity: ValidationAdvisoryEventSchema.shape.severity.optional().describe(
    'The advisory rule\'s declared severity, `warning` or `info`. Present only on an advisory rule hit.',
  ),
}));

/**
 * The `warnings` member every single-record write answer declares (#22726) —
 * one sentence, so the create, clone and update answers cannot drift apart.
 */
const WRITE_ANSWER_WARNINGS_DESCRIPTION =
  'The advisory validation-rule hits of THIS write: each `severity: \'warning\'` or `\'info\'` rule whose ' +
  'verdict on the written record was "violated", with its `rule` name, `severity`, `field`, `code` and ' +
  'author-written `message` — the same element the validate-only preview reports in a row\'s `warnings`. ' +
  'Advisory rules never block, so the write succeeded; this is the advisory to show the person who made it. ' +
  'Present ONLY when at least one advisory rule hit; a write with no hit omits the key. Hits of a nested write ' +
  'a hook or a flow made inside this one are not included, and a rule that could not be evaluated is not a hit.';

/**
 * Create Data Response
 */
export const CreateDataResponseSchema = lazySchema(() => z.object({
  object: z.string().describe('The object name.'),
  id: z.string().describe('The ID of the newly created record.'),
  record: z.record(z.string(), z.unknown()).describe('The created record, including server-generated fields (created_at, owner).'),
  droppedFields: z.array(DroppedFieldsEventSchema).optional().describe(
    'Write-observability: caller-supplied fields that were LEGALLY stripped ' +
    'before the record was written — a non-system create cannot seed a static `readonly` ' +
    'column (the strip runs inside `engine.insert`, after the `beforeInsert` hooks, ' +
    '`isSystem`-gated), so those keys are dropped and the field re-derives its ' +
    'default. Present ONLY when ≥1 field was dropped; the create still succeeded without ' +
    'them (status/success semantics unchanged). REST additionally surfaces this as the ' +
    '`X-ObjectStack-Dropped-Fields` response header. Optional — omit-when-empty keeps the ' +
    'shape backward-compatible for existing clients.'
  ),
  warnings: z.array(ValidateDataIssueSchema).optional().describe(WRITE_ANSWER_WARNINGS_DESCRIPTION),
}));

/**
 * Clone Data Response (#11924)
 *
 * The WHOLE body of `POST /data/:object/:id/clone` — the route answers BARE
 * (`res.status(201).json(result)`, no `{ success, data }` envelope) and relays
 * `@objectstack/metadata-protocol`'s `cloneData` return verbatim, so this
 * schema names the entire body where the route ledger references it.
 *
 * Declared AS PRODUCED (maintainer ruling 2026-08-25 on #11924: the shape is
 * stable and server-produced): `cloneData` builds exactly
 * `{ object, id, sourceId, record }` — the structural sibling of
 * {@link CreateDataResponseSchema} plus `sourceId`. A clone IS a create (the
 * copy runs the insert path: engine-owned columns re-derived, the static
 * `readonly` strip applied inside `engine.insert` for a non-system caller —
 * the 2026-09-03 ruling, #14147; the #3043 ingress copy is deleted — and
 * internal fields omitted from the response, #7823) — and since #15703 it
 * reports the engine's `onFieldsDropped` verdict as `droppedFields` exactly as
 * `createData` does (maintainer ruling 2026-09-08, option 1): the producer
 * passes the listener and the member is declared in the same change, so the
 * key stays one conformance can measure. A clone is the one create shape that
 * can carry a read-only column WITHOUT the caller typing it — the source row's
 * `approval_status: 'approved'` is copied before `overrides` are applied — so
 * this is the face where a silent strip was least discoverable.
 */
export const CloneDataResponseSchema = lazySchema(() => z.object({
  object: z.string().describe('The object name.'),
  id: z.string().describe('The ID of the newly created clone.'),
  sourceId: z.string().describe('The ID of the record the clone was copied from.'),
  record: z.record(z.string(), z.unknown()).describe(
    'The created clone, including server-generated fields. Engine-owned values '
    + '(injected system/audit columns, autonumbers, computed formula/summary fields) are '
    + 're-derived by the insert path rather than copied from the source; caller-supplied '
    + '`overrides` win over copied values.'
  ),
  droppedFields: z.array(DroppedFieldsEventSchema).optional().describe(
    'Write-observability: fields that were LEGALLY stripped before the clone was written — '
    + 'a non-system clone cannot seed a static `readonly` column, whether the value was '
    + 'COPIED from the source row or supplied through `overrides` (the strip runs inside '
    + '`engine.insert`, after the `beforeInsert` hooks, `isSystem`-gated, exactly as on '
    + '`createData`), so those keys are dropped and the field re-derives its default. '
    + 'Present ONLY when ≥1 field was dropped; the clone still succeeded without them '
    + '(status/success semantics unchanged). Carried in the 201 body only — this route '
    + 'relays the producer verbatim and sets no `X-ObjectStack-Dropped-Fields` header. '
    + 'Optional — omit-when-empty keeps the shape backward-compatible for existing clients.'
  ),
  warnings: z.array(ValidateDataIssueSchema).optional().describe(WRITE_ANSWER_WARNINGS_DESCRIPTION),
}));

/**
 * Validate Data Request (commit 18189983d — #4633 ruling D)
 *
 * Ask for the write path's verdict on candidate rows WITHOUT writing them.
 *
 * @example
 * {
 *   "object": "leads",
 *   "mode": "insert",
 *   "data": [{ "first_name": "John", "email": "not-an-email" }]
 * }
 */
export const ValidateDataRequestSchema = lazySchema(() => z.object({
  object: z.string().describe('The object name.'),
  data: z.union([
    z.record(z.string(), z.unknown()),
    z.array(z.record(z.string(), z.unknown())),
  ]).describe('A candidate record, or an array of them. Nothing is persisted.'),
  mode: z.enum(['insert', 'update']).optional().describe(
    "Which write the verdict should predict. `insert` (default) walks every declared field, so a " +
    "missing required field is a finding; `update` checks only the supplied keys, matching a PATCH. " +
    "An `update` row that carries its `id` is judged as the by-id update judges it: its rules read the " +
    "stored row that id names, merged with the supplied keys. The stored row is read with the caller's " +
    "own read access, so a row the caller cannot read is judged on the supplied keys alone, as a row " +
    "with no `id` is.",
  ),
}));

/**
 * Validate Data Response
 *
 * One entry per submitted row, in submission order.
 *
 * A row's `droppedFields` is set by the engine's `validate`, which runs the
 * write's computed-field strip (every context) and its strips of static
 * `readonly` and runtime-owned fields (`isSystem`-gated), records what each
 * takes from each row, and reports it on a row the verdict accepts;
 * `validateData` relays it. An `update`-mode preview does not run the
 * `readonlyWhen` or primary-key strips, which the update runs against its prior
 * record and its dispatch, so it can report fewer drops than the update it
 * predicts — including for a row whose stored row it reads (see `mode` on the
 * request).
 * The element IS {@link DroppedFieldsEventSchema} — the same shape and `reason`
 * vocabulary the write reports, ⛔ never a second enum — so a preview and the
 * write it predicts answer in one vocabulary, exactly as `errors` / `warnings`
 * share {@link ValidateDataIssueSchema} with a rejected write.
 *
 * [#22726] A row's `warnings` also carries the ADVISORY validation-rule hits of
 * the evaluation the write itself runs, appended after the admitted value
 * shapes: the same elements a create / update / clone answers as its own
 * `warnings`, so the preview fills the key the write fills, from the same
 * `evaluateValidationRules` call.
 */
export const ValidateDataResponseSchema = lazySchema(() => z.object({
  object: z.string().describe('The object name.'),
  mode: z.enum(['insert', 'update']).describe('The write mode the verdict was reached for.'),
  valid: z.boolean().describe('True when EVERY row is valid — the whole-set answer.'),
  results: z.array(z.object({
    valid: z.boolean().describe('True when this row would be accepted by the write path.'),
    errors: z.array(ValidateDataIssueSchema).describe('Findings that would REJECT this row. Empty when valid.'),
    warnings: z.array(ValidateDataIssueSchema).describe(
      'Findings the target deployment ADMITS rather than rejects; the row is valid, and the write would store it. ' +
      'Two populations, in this order: ADR-0104 value shapes admitted under a warn-first posture (the write logs ' +
      'the same complaint), then the hits of ADVISORY validation rules (`severity: \'warning\'` or `\'info\'`), ' +
      'each naming its `rule` and `severity` — the same elements the write answers as its own `warnings`. ' +
      'An advisory hit is reported only on a row the verdict accepts, as on the write, which answers a refused ' +
      'row with its error.',
    ),
    droppedFields: z.array(DroppedFieldsEventSchema).optional().describe(
      'Write-observability for the preview: caller-supplied fields the write would LEGALLY strip from THIS ' +
      'row, one event per reason, in the shape and reason vocabulary the write itself reports. A strip is ' +
      'not a finding: `valid` is unaffected, and the fields appear in neither `errors` nor `warnings`. ' +
      'Present only when at least one field would be dropped. A server that does not produce this report ' +
      'omits the key too, so an absent key alone does not prove nothing would be dropped.',
    ),
  })).describe('Per-row verdicts, in submission order.'),
  posture: z.object({
    valueShapeStrict: z.boolean().describe('True when this deployment rejects non-conforming value shapes (ADR-0104 self-certified).'),
    mediaValueShapeStrict: z.boolean().describe('The same, for media field value shapes.'),
  }).describe(
    'The ADR-0104 posture the verdict was reached under — reported because it is the difference between ' +
    '"this row is fine" and "this row is fine HERE". The same row can be an error on a self-certified ' +
    'deployment and an admitted warning on an un-migrated one, and a caller explaining a verdict needs to ' +
    'know which it got. An unconditionally-strict preview was considered and rejected (option B): it ' +
    'would fail rows on every un-migrated deployment that the write would have accepted.',
  ),
}));

/**
 * Update Data Request
 * Modification of an existing record.
 * 
 * @example
 * {
 *   "object": "tasks",
 *   "id": "tsk_001",
 *   "data": {
 *     "status": "completed",
 *     "percent_complete": 100
 *   }
 * }
 */
export const UpdateDataRequestSchema = lazySchema(() => z.object({
  object: z.string().describe('The object name.'),
  id: z.string().describe('The ID of the record to update.'),
  data: z.record(z.string(), z.unknown()).describe('The fields to update (partial update).'),
  expectedVersion: z.string().optional().describe(
    'Optimistic concurrency token (typically the `updated_at` value the client read). ' +
    'When provided, the server compares it against the current record version and ' +
    'returns 409 CONCURRENT_UPDATE if they differ. Optional — omit to skip the check. ' +
    'The quoted-empty entity-tag (`""`) is refused 400 VALIDATION_FAILED, not treated as omitted.'
  ),
}));

/**
 * Update Data Response
 */
export const UpdateDataResponseSchema = lazySchema(() => z.object({
  object: z.string().describe('Object name'),
  id: z.string().describe('Updated record ID'),
  record: z.record(z.string(), z.unknown()).describe('Updated record'),
  droppedFields: z.array(DroppedFieldsEventSchema).optional().describe(
    'Write-observability: caller-supplied fields the engine LEGALLY stripped ' +
    'from the write before persisting — static `readonly` or a TRUE `readonlyWhen` ' +
    'predicate. Present ONLY when ≥1 field was dropped; the update still succeeded ' +
    'without them (status/success semantics unchanged — stripping is legitimate, not an ' +
    'error). REST additionally surfaces this as the `X-ObjectStack-Dropped-Fields` response ' +
    'header. Optional — omit-when-empty keeps the shape backward-compatible for existing ' +
    'clients that only read `record`.'
  ),
  warnings: z.array(ValidateDataIssueSchema).optional().describe(WRITE_ANSWER_WARNINGS_DESCRIPTION),
}));

/**
 * Delete Data Request
 *
 * [#13852] The request contract of {@link DataProtocol.deleteData} — its
 * declared parameter type is the `DeleteDataRequest` alias below. That
 * protocol boundary is this schema's whole job: it is consumed statically, by
 * the compiler, and parsed at runtime nowhere in the tree. A grep that finds
 * "exported, documented, zero `safeParse` call sites" is reading the wrong
 * surface — #13852 is that grep, filed once already.
 *
 * It deliberately carries no REST-door `requestSchema` (#3899):
 * `DELETE /api/v1/data/:object/:id` reads no body — `object` and `id` are
 * path-bound, `expectedVersion` rides `?expectedVersion` / `If-Match` — so a
 * schema on that door would promise a validation nothing can violate. The
 * catalog entry in `plugin-rest-api.zod.ts` says so in place of the key, and
 * the pin in `plugin-rest-api.schema-refs.test.ts` ("requestSchema appears
 * only on body-carrying methods") goes red if one is added. ⛔ Do not wire
 * one, and do not retire this schema either — it types a shipped interface
 * method.
 *
 * Drift between this schema and that door is caught at COMPILE time, not by a
 * runtime parse: the door's request literal is typed against
 * `DeleteDataRequest` (`ServerScopedDataRequest` in
 * `packages/rest/src/rest-server.ts`, #15866 / PR #16071), so a field added
 * here as REQUIRED reddens that file at build, naming the route that would
 * otherwise have gone on not sending it.
 */
export const DeleteDataRequestSchema = lazySchema(() => z.object({
  object: z.string().describe('Object name'),
  id: z.string().describe('Record ID to delete'),
  expectedVersion: z.string().optional().describe(
    'Optimistic concurrency token (typically the `updated_at` value the client read). ' +
    'When provided, the server compares it against the current record version and ' +
    'returns 409 CONCURRENT_UPDATE if they differ. Optional — omit to skip the check. ' +
    'The quoted-empty entity-tag (`""`) is refused 400 VALIDATION_FAILED, not treated as omitted.'
  ),
}));

/**
 * Delete Data Response
 */
export const DeleteDataResponseSchema = lazySchema(() => z.object({
  object: z.string().describe('Object name'),
  id: z.string().describe('Deleted record ID'),
  success: z.boolean().describe('Whether deletion succeeded'),
}));

// ==========================================
// Global Cross-Object Search
// ==========================================

/**
 * One hit of the global cross-object search (#11924).
 *
 * ⚠️ NOT the per-object search-service hit. `SearchHit` / `SearchResult`
 * (`@objectstack/spec/contracts`, `search-service.ts`) contract the pluggable
 * `ISearchService.search` engine surface, whose hits carry `score` /
 * `document`. THIS shape is the `GET /api/v1/search` palette answer —
 * `object` / `id` / `title` / `snippet` / `record` — produced by
 * `@objectstack/metadata-protocol`'s `searchAll`. Binding the same-named
 * neighbour would typecheck and be false; the compile-time guard #8140 left in
 * `packages/client/src/return-type-precision.test.ts` pins the mismatch.
 */
export const SearchAllHitSchema = lazySchema(() => z.object({
  object: z.string().describe('Name of the object the hit belongs to.'),
  id: z.string().describe('ID of the matched record.'),
  title: z.string().describe(
    'Display title for the hit, resolved in order: the declared primary-title pointer '
    + '(`nameField`, ADR-0079; deprecated alias `displayNameField` still honored) → the '
    + 'object\'s deprecated `titleFormat` template → conventional name fields → first/last '
    + 'name → the record ID as a string.'
  ),
  snippet: z.string().optional().describe(
    'Excerpt cut around the first matched term in a searchable text column, ellipsized at '
    + 'both ends when truncated. ABSENT when no source column literally contains a term '
    + '(e.g. a pinyin companion match) — absence is a correct answer, not a miss.'
  ),
  record: z.record(z.string(), z.unknown()).describe(
    'The matched record as the engine\'s find path returns it (row-level security applied, '
    + 'internal fields already stripped). Object-specific — no cross-object field shape is '
    + 'promised beyond "a record of the named object".'
  ),
}));

/**
 * One PAGE hit of the global cross-object search (#13216).
 *
 * A published custom page has an end-user entry point in the ⌘K palette:
 * `searchAll` additionally sweeps the pages the caller's ordinary metadata
 * read door already serves (`getMetaItems({ type: 'page' })` — published
 * state only, org-scoped through the same registry-derived predicate the
 * REST `/meta` read doors use), so a page hit surfaces exactly what
 * `GET /api/v1/meta/page` would have answered the same caller — never more.
 * Opening the hit goes through the existing page routes/renderer, which is
 * where whatever protects the page applies — unchanged by this surface, and
 * NOT a page-level audience gate: a page has none. `page.assignedProfiles`
 * was the key that read as one, and it was removed (ADR-0090 D2 / ADR-0049)
 * precisely because nothing anywhere ever enforced it. What protects a page
 * is the permission sets on the DATA it shows. The search response is not a
 * second read door either way.
 *
 * NOT a member of {@link SearchAllHitSchema}'s array: page hits live in the
 * sibling `pages` array so an existing consumer iterating `hits` (every one
 * of which is a record with an `object`/`id` address) never receives an
 * element whose address vocabulary it predates. `kind` is the self-describing
 * discriminant for clients that flatten both arrays into one palette list.
 */
export const SearchAllPageHitSchema = lazySchema(() => z.object({
  kind: z.literal('page').describe(
    'Discriminant, always the literal `page` — kept on the hit (despite the dedicated array) so '
    + 'a client merging record and page hits into one palette list still holds a self-describing '
    + 'element.'
  ),
  name: z.string().describe(
    'Machine name of the page (`page.name`) — the address a client routes to; the same name the '
    + 'metadata read door serves the page under.'
  ),
  title: z.string().describe(
    'Display title: the page `label` resolved through the shared i18n label resolution '
    + '(exact tag → base language → regional sibling → `default` → `en` → any), falling back to '
    + 'the machine name when no label resolves.'
  ),
  snippet: z.string().optional().describe(
    'Excerpt cut around the first matched term in the page `description`, ellipsized at both '
    + 'ends when truncated — the same geometry as a record hit\'s snippet. ABSENT when the match '
    + 'is on the name or label only (the title already shows it) — absence is a correct answer, '
    + 'not a miss.'
  ),
  pageType: z.string().optional().describe(
    'The page\'s own declared `type` (`record` | `app` | `home` | …) when the served document '
    + 'carries one — a routing hint, deliberately typed as a plain string so a future page type '
    + 'cannot invalidate an already-produced search response.'
  ),
}));

/**
 * Global Cross-Object Search Response (#11924)
 *
 * The WHOLE body of `GET /api/v1/search` — the route answers BARE
 * (`res.json(result)`, no `{ success, data }` envelope) and relays
 * `@objectstack/metadata-protocol`'s `searchAll` return verbatim, so this
 * schema names the entire body where the route ledger references it.
 *
 * Declared AS PRODUCED (maintainer ruling 2026-08-25 on #11924: the shape is
 * stable and server-produced). One query sweeps every searchable,
 * API-enabled object the caller can read (ADR-0061 Tier 1: the server
 * resolves which fields to search from object metadata) — and, on an
 * unscoped sweep, the published pages the caller's metadata read door serves
 * (#13216, {@link SearchAllPageHitSchema}); an empty/blank `q`
 * short-circuits to `{ query: '', hits: [], pages: [], totalObjects: 0,
 * totalHits: 0, truncated: false }` without scanning.
 */
export const SearchAllResponseSchema = lazySchema(() => z.object({
  query: z.string().describe(
    'The TRIMMED query text the sweep ran with — empty string when the request carried '
    + 'none (the no-scan short-circuit).'
  ),
  hits: z.array(SearchAllHitSchema).describe(
    'Matched records across objects, in scan order, capped at the overall `limit` '
    + '(default 20, max 100) with at most `perObject` (default 5, max 25) per object.'
  ),
  pages: z.array(SearchAllPageHitSchema).describe(
    'Published pages whose name, label, or description matches every term (each term may match '
    + 'in a different field; matching folds case), in the served listing\'s order, capped at '
    + '`perObject` — the page store is swept as one more container, and more matching pages may '
    + 'exist beyond the cap. Produced ONLY on an unscoped sweep: a request that names `objects` '
    + 'asks for records of those objects and answers `pages: []`. The swept set is exactly what '
    + 'the caller\'s metadata read door (`GET /api/v1/meta/page`) serves — published state only, '
    + 'never drafts.'
  ),
  totalObjects: z.number().describe(
    'Number of objects the sweep actually SCANNED (searchable, API-enabled, with a '
    + 'resolvable search-field set) — not the number of objects with hits. An object '
    + 'whose table was never provisioned is skipped and not counted.'
  ),
  totalHits: z.number().describe(
    'Number of hits returned — equals `hits.length`. NOT a deployment-wide total-match '
    + 'count: matches beyond `limit` / `perObject` are not counted.'
  ),
  truncated: z.boolean().describe(
    'True when the sweep stopped at the overall `limit` — more matches may exist beyond '
    + 'the returned set.'
  ),
}));

// ==========================================
// Batch Operations
// ==========================================

/**
 * Batch Data Request
 */
export const BatchDataRequestSchema = lazySchema(() => z.object({
  object: z.string().describe('Object name'),
  request: BatchUpdateRequestSchema.describe('Batch operation request'),
}));

/**
 * Batch Data Response
 * Uses BatchUpdateResponse from batch.zod.ts
 */
export const BatchDataResponseSchema = lazySchema(() => BatchUpdateResponseSchema);

/**
 * Create Many Data Request
 */
export const CreateManyDataRequestSchema = lazySchema(() => z.object({
  object: z.string().describe('Object name'),
  records: z.array(z.record(z.string(), z.unknown())).describe('Array of records to create'),
}));

/**
 * Create Many Data Response
 */
export const CreateManyDataResponseSchema = lazySchema(() => z.object({
  object: z.string().describe('Object name'),
  records: z.array(z.record(z.string(), z.unknown())).describe('Created records'),
  count: z.number().describe('Number of records created'),
  // The per-row read below is maintainer ruling C (#14147): the static-`readonly` strip
  // moved into `engine.insert`, after `beforeInsert`, exempting keys a hook wrote
  // (`rowHookWrittenKeys`). The id stays in this comment, never in the `.describe()` —
  // that string is printed AT the customer, who has no tracker to resolve it.
  droppedFields: z.array(DroppedFieldsEventSchema).optional().describe(
    'Write-observability: caller-supplied `readonly` fields the in-engine create-side ' +
    'strip (`engine.insert`, `isSystem`-gated) removed before the rows were written. AGGREGATED across the batch ' +
    '(one event per object/reason with the UNION of dropped field names) rather than per-row, ' +
    'because this response is `{ object, records, count }` and has no per-row slot to hang a ' +
    'drop set on — a union is the only view it can represent. So read a name here as "at least ' +
    'one row dropped this field", NOT "every row dropped the same set": the strip runs INSIDE ' +
    '`engine.insert` after the `beforeInsert` hooks and exempts keys a hook itself wrote, ' +
    'tracked per row: rows where a hook stamped a protected key drop a different set from ' +
    'rows where it did not. Present ONLY when ≥1 field was dropped; the creates still succeeded ' +
    'without them (count/success unchanged). Optional — omit-when-empty keeps the shape ' +
    'backward-compatible. (The same reading applies to the partial-success bulk create, whose ' +
    'batch-level `droppedFields` names no row for the same reason. The paths that DO carry ' +
    'per-row `droppedFields` on each result are the bulk UPDATE and the mixed batch, where each ' +
    'row is its own engine call — see BatchOperationResultSchema.)'
  ),
}));

/**
 * Update Many Data Request
 *
 * [#3939] The wire body IS {@link UpdateManyRequestSchema} — one Zod source per
 * contract (Prime Directive #7). This adds only `object`, which the REST route
 * takes from the URL path and never from the body (#3933). The two used to be
 * hand-maintained copies that had already drifted apart: the batch.zod one
 * accepted `{}` rows, this one required `id` + `data`, and only this one was
 * ever enforced.
 */
export const UpdateManyDataRequestSchema = lazySchema(() => UpdateManyRequestSchema.extend({
  object: z.string().describe('Object name'),
}));

/**
 * Update Many Data Response
 * Uses BatchUpdateResponse for consistency
 */
export const UpdateManyDataResponseSchema = lazySchema(() => BatchUpdateResponseSchema);

/**
 * Delete Many Data Request
 *
 * [#3939] The wire body IS {@link DeleteManyRequestSchema}; this adds only the
 * `object` the REST route takes from the URL path (#3933). See
 * {@link UpdateManyDataRequestSchema} for why the copies were merged.
 */
export const DeleteManyDataRequestSchema = lazySchema(() => DeleteManyRequestSchema.extend({
  object: z.string().describe('Object name'),
}));

/**
 * Delete Many Data Response
 */
export const DeleteManyDataResponseSchema = lazySchema(() => BatchUpdateResponseSchema);

// ==========================================
// Package Management Operations
// ==========================================

/**
 * Re-export Package Management Request/Response schemas from kernel.
 * These define the contract for package lifecycle management:
 * - List installed packages (with filters)
 * - Get a specific package by ID
 * - Install a new package (from manifest)
 * - Uninstall a package
 * - Enable/Disable a package
 * 
 * Key distinction: Package (ManifestSchema) is the unit of installation.
 * An App (AppSchema) is a UI navigation entity within a package.
 * A package may contain 0, 1, or many apps.
 */
export {
  ListPackagesRequestSchema,
  ListPackagesResponseSchema,
  GetPackageRequestSchema,
  GetPackageResponseSchema,
  InstallPackageRequestSchema,
  InstallPackageResponseSchema,
  UninstallPackageRequestSchema,
  UninstallPackageResponseSchema,
  EnablePackageRequestSchema,
  EnablePackageResponseSchema,
  DisablePackageRequestSchema,
  DisablePackageResponseSchema,
};

// ==========================================
// View Management Operations — RETIRED
// ==========================================

// `ListViews` / `GetView` / `CreateView` / `UpdateView` / `DeleteView` —
// five methods and their ten Request/Response schemas — were REMOVED per
// ADR-0049 enforce-or-remove (commit f549a0d4a, protocol 17, maintainer ruling
// 2026-08-07). Route 3 of the retirement playbook: not one of the ten was a
// KEY on an authorable shape, nothing parsed them, and no route could reach the
// methods, so there is no tombstone to write and no source or `sys_metadata`
// row for a D2 conversion to rewrite. `RETIRED_DEFS_BY_MAJOR[17]` plus the D3
// `SemanticMigration` `view-management-protocol-retired` ARE the declaration.
//
// ## What it declared, and what serves it
//
// A viewId-addressed CRUD surface over views: list by object (+ optional
// list/form filter), read one, create, patch, delete. Measured on `origin/main`
// immediately before the removal, it had ZERO of the three things a protocol
// method needs:
//
//   - no implementation — `packages/metadata-protocol/src/protocol.ts` declares
//     no `listViews`/`getView`/`createView`/`updateView`/`deleteView`; its only
//     view resolver is `getUiView`;
//   - no route — `packages/rest/src/rest-server.ts` never mentions `viewId`, so
//     nothing viewId-addressed is reachable over HTTP at all;
//   - no caller — the only `ViewProtocol` mention outside this file was
//     `content/docs/kernel/services-checklist.mdx`, which already recorded the
//     five as declared-and-unrouted.
//
// Views are read and written today through surfaces that DO exist: the
// metadata routes (`/api/v1/meta/view/:name`, i.e. `getMetaItem` /
// `saveMetaItem` / `deleteMetaItem` with `type: 'view'`) for the stored
// definition, and `getUiView` (`GET /api/v1/ui/view/:object/:type`) for the
// resolved render-time view.
//
// ## Why this one was worth the removal rather than a note
//
// A declared surface that is name-identical and semantics-adjacent to a real
// one is not merely dead weight; it is an attractive nuisance in every grep.
// It had already cost once: #5948's issue body AND its 2026-08-07 maintainer
// ruling both read `GetViewResponseSchema` (this block, zero implementations)
// as the contract of `GET /ui/view/:object/:type`, whose declared response is
// `GetUiViewResponseSchema` — 250 lines up, one word different. The ruling's
// reasoning happened to survive the mix-up, which is the luck that makes this
// class of defect worth removing rather than annotating.
//
// If "read/write ONE view by id" becomes a real requirement, it returns through
// the ENFORCE route — implementation first, vocabulary second (ADR-0049).

// ==========================================
// Permission Operations
// ==========================================

export const CheckPermissionRequestSchema = lazySchema(() => z.object({
  object: z.string().describe('Object name to check permissions for'),
  action: z.enum(['create', 'read', 'edit', 'delete', 'transfer', 'restore', 'purge']).describe('Action to check'),
  recordId: z.string().optional().describe('Specific record ID (for record-level checks)'),
  field: z.string().optional().describe('Specific field name (for field-level checks)'),
}));

export const CheckPermissionResponseSchema = lazySchema(() => z.object({
  allowed: z.boolean().describe('Whether the action is permitted'),
  reason: z.string().optional().describe('Reason if denied'),
}));

export const GetObjectPermissionsRequestSchema = lazySchema(() => z.object({
  object: z.string().describe('Object name to get permissions for'),
}));

export const GetObjectPermissionsResponseSchema = lazySchema(() => z.object({
  object: z.string().describe('Object name'),
  permissions: ObjectPermissionSchema.describe('Object-level permissions'),
  fieldPermissions: z.record(z.string(), FieldPermissionSchema).optional().describe('Field-level permissions keyed by field name'),
}));

export const GetEffectivePermissionsRequestSchema = lazySchema(() => z.object({}));

export const GetEffectivePermissionsResponseSchema = lazySchema(() => z.object({
  // [#3391] The effective response carries the server-resolved API operation set
  // per object (`apiOperations`) — the single "effective" channel the frontend
  // consumes. Authoring `ObjectPermissionSchema` stays unextended.
  objects: z.record(z.string(), EffectiveObjectPermissionSchema).describe('Effective object permissions keyed by object name'),
  systemPermissions: z.array(z.string()).describe('Effective system-level permissions'),
}));

// ==========================================
// Workflow Operations — REMOVED (#4451, v17)
// ==========================================
// The Get/WorkflowState/Config/Transition schemas and the `WorkflowProtocol`
// interface were deleted: no code ever implemented any of the three methods,
// nothing ever registered the `workflow` service slot they notionally fronted
// (ADR-0115 Evidence 5 — "no code in this repository resolves either slot",
// verified across both repositories), and no HTTP surface ever mounted
// `/api/v1/workflow` (the pre-#3586 DEFAULT_DISPATCHER_ROUTES listed it among
// routes that never existed). The capability the wrappers promised is live
// elsewhere: record state machines are enforced by the `state_machine`
// validation rule (a flat `{ from: [to] }` transition table in the object's
// `validations`, `data/validation.zod.ts` — the XState `StateMachineSchema` was
// never authorable on the object after ADR-0020 and left the package in #21320),
// approvals are first-class flow nodes on the approvals runtime (ADR-0019 —
// decisions via `POST /approvals/requests/:id/{approve,reject}`), and
// record-triggered automation is lifecycle hooks + `record_change` flows.

// ==========================================
// Realtime Operations
// ==========================================

export const RealtimeConnectRequestSchema = lazySchema(() => z.object({
  transport: TransportProtocol.optional().describe('Preferred transport protocol'),
  channels: z.array(z.string()).optional().describe('Channels to subscribe to on connect'),
  token: z.string().optional().describe('Authentication token'),
}));

export const RealtimeConnectResponseSchema = lazySchema(() => z.object({
  connectionId: z.string().describe('Unique connection identifier'),
  transport: TransportProtocol.describe('Negotiated transport protocol'),
  url: z.string().optional().describe('WebSocket/SSE endpoint URL'),
}));

export const RealtimeDisconnectRequestSchema = lazySchema(() => z.object({
  connectionId: z.string().optional().describe('Connection ID to disconnect'),
}));

export const RealtimeDisconnectResponseSchema = lazySchema(() => z.object({
  success: z.boolean().describe('Whether disconnection succeeded'),
}));

export const RealtimeSubscribeRequestSchema = lazySchema(() => z.object({
  channel: z.string().describe('Channel name to subscribe to'),
  events: z.array(z.string()).optional().describe('Specific event types to listen for'),
  filter: z.record(z.string(), z.unknown()).optional().describe('Event filter criteria'),
}));

export const RealtimeSubscribeResponseSchema = lazySchema(() => z.object({
  subscriptionId: z.string().describe('Unique subscription identifier'),
  channel: z.string().describe('Subscribed channel name'),
}));

export const RealtimeUnsubscribeRequestSchema = lazySchema(() => z.object({
  subscriptionId: z.string().describe('Subscription ID to cancel'),
}));

export const RealtimeUnsubscribeResponseSchema = lazySchema(() => z.object({
  success: z.boolean().describe('Whether unsubscription succeeded'),
}));

export const SetPresenceRequestSchema = lazySchema(() => z.object({
  channel: z.string().describe('Channel to set presence in'),
  state: RealtimePresenceSchema.describe('Presence state to set'),
}));

export const SetPresenceResponseSchema = lazySchema(() => z.object({
  success: z.boolean().describe('Whether presence was set'),
}));

export const GetPresenceRequestSchema = lazySchema(() => z.object({
  channel: z.string().describe('Channel to get presence for'),
}));

export const GetPresenceResponseSchema = lazySchema(() => z.object({
  channel: z.string().describe('Channel name'),
  members: z.array(RealtimePresenceSchema).describe('Active members and their presence state'),
}));

// ==========================================
// Notification Operations
// ==========================================

export const RegisterDeviceRequestSchema = lazySchema(() => z.object({
  token: z.string().describe('Device push notification token'),
  platform: z.enum(['ios', 'android', 'web']).describe('Device platform'),
  deviceId: z.string().optional().describe('Unique device identifier'),
  name: z.string().optional().describe('Device friendly name'),
}));

export const RegisterDeviceResponseSchema = lazySchema(() => z.object({
  deviceId: z.string().describe('Registered device ID'),
  success: z.boolean().describe('Whether registration succeeded'),
}));

export const UnregisterDeviceRequestSchema = lazySchema(() => z.object({
  deviceId: z.string().describe('Device ID to unregister'),
}));

export const UnregisterDeviceResponseSchema = lazySchema(() => z.object({
  success: z.boolean().describe('Whether unregistration succeeded'),
}));

export const NotificationPreferencesSchema = lazySchema(() => z.object({
  email: z.boolean().default(true).describe('Receive email notifications'),
  push: z.boolean().default(true).describe('Receive push notifications'),
  inApp: z.boolean().default(true).describe('Receive in-app notifications'),
  digest: z.enum(['none', 'daily', 'weekly']).default('none').describe('Email digest frequency'),
  channels: z.record(z.string(), z.object({
    enabled: z.boolean().default(true).describe('Whether this channel is enabled'),
    email: z.boolean().optional().describe('Override email setting'),
    push: z.boolean().optional().describe('Override push setting'),
  })).optional().describe('Per-channel notification preferences'),
}));

export const GetNotificationPreferencesRequestSchema = lazySchema(() => z.object({}));

export const GetNotificationPreferencesResponseSchema = lazySchema(() => z.object({
  preferences: NotificationPreferencesSchema.describe('Current notification preferences'),
}));

export const UpdateNotificationPreferencesRequestSchema = lazySchema(() => z.object({
  preferences: NotificationPreferencesSchema.partial().describe('Preferences to update'),
}));

export const UpdateNotificationPreferencesResponseSchema = lazySchema(() => z.object({
  preferences: NotificationPreferencesSchema.describe('Updated notification preferences'),
}));

export const NotificationSchema = lazySchema(() => z.object({
  id: z.string().describe('Notification ID'),
  type: z.string().describe('Notification type'),
  title: z.string().describe('Notification title'),
  body: z.string().describe('Notification body text'),
  read: z.boolean().default(false).describe('Whether notification has been read'),
  data: z.record(z.string(), z.unknown()).optional().describe('Additional notification data'),
  actionUrl: z.string().optional().describe('URL to navigate to when clicked'),
  createdAt: z.string().datetime().describe('When notification was created'),
}));

// ==========================================
// Notification inbox listing — NOT paginated
// ==========================================

// `cursor` was declared on BOTH halves of `GET /api/v1/notifications` and
// honoured on neither, and `limit` declared a default the server has never
// applied. Both are removed per the maintainer ruling of 2026-08-07 (commit 90bbf2510,
// Option A), ruled together with the `unreadCount` fix (commit 17d095413) as one capability's two halves — a
// pagination capability is never half-deleted.
//
// ## What the route actually does
//
// It answers a WINDOW, never a page: `MessagingService.listInbox` reads the
// newest `limit` rows and stops. There is no continuation token, no `hasMore`,
// and no ordering key a caller could resume from — so `cursor` had nothing to
// carry even if something had read it. The request half was ignored by the
// domain (which reads `read` / `type` / `limit` and nothing else) and the
// response half was never emitted, so an SDK caller looping "until the cursor
// runs out" re-read page 1 forever, with no error and no 400.
//
// This is `data.query.cursor` (#4286, `query-cursor-retired`) one layer up,
// with the same verdict for the same reason: a caller-visible pagination
// parameter no engine implements is worse than inert, because it has a shipped
// producer. That one deleted `QueryBuilder.cursor()` with the key; this one
// deletes the `cursor` argument of `client.notifications.list()`.
//
// ## Why `limit` loses its default rather than gaining a truer number
//
// The ruling allowed either "declare the real default (50)" or "drop the
// default and describe it as server-decided". The second is taken because the
// FICTION IS THE MECHANISM, not just the number: nothing parses a query string
// through this schema (#3899 wired the catalog's `requestSchema` to the real
// entry for BODIES only), so `.default(...)` has never stamped anything onto
// anything. Re-spelling `20` as `50` would keep a declaration that does not
// execute and merely make it coincide with the server for as long as nobody
// moves the clamp. `.optional()` plus prose is true on both axes: the schema
// claims no behaviour it does not perform, and the server's window is
// described as the server's.
//
// Deliberately NOT declared: `.int()`, `.positive()` or `.max(200)`. The
// service CLAMPS an out-of-range limit (`Math.min(Math.max(limit ?? 50, 1),
// 200)`); it does not refuse one. A constraint here would declare a rejection
// the wire does not perform — the same declared-not-enforced defect in the
// opposite direction. ADR-0049, commit 90bbf2510.

/**
 * One prescription, two rejection sites — the `cursor` key was declared on both
 * halves of this route, so both tombstone it with the same string.
 *
 * Tombstoned rather than deleted for the ADR-0104 reason these schemas keep
 * paying for: neither is `.strict()`, so a bare deletion makes Zod SILENTLY
 * STRIP whatever the caller keeps sending — a clean parse and a parameter that
 * never takes effect, which is the very failure this issue is about, moved one
 * layer down. `retiredKey()` types the key as `never` (so `tsc` refuses it at
 * the authoring site) and raises this text at parse time.
 */
const NOTIFICATIONS_CURSOR_REMOVED =
  '`cursor` was removed from GET /api/v1/notifications in @objectstack/spec 17 '
  + '(ADR-0049) — it was declared on the request AND the response and honoured on '
  + 'neither: the server reads only `read`/`type`/`limit`, and no emit site ever wrote the '
  + 'response key, so a caller paginating by it re-read the first window forever with no '
  + 'error and no 400. Delete the key; the `cursor` argument of '
  + '`client.notifications.list()` was removed with it. This route is NOT paginated — it '
  + 'answers the newest `limit` notifications and stops, so ask for a bigger window '
  + '(`limit`, clamped by the server into 1..200) instead of a next page. A first-class '
  + 'inbox cursor, if ever built, will be a response-minted opaque token, not this key.';

export const ListNotificationsRequestSchema = lazySchema(() => z.object({
  read: z.boolean().optional().describe('Filter by read status'),
  type: z.string().optional().describe('Filter by notification type'),
  limit: z.number().optional().describe(
    'Maximum number of notifications to return — the newest N. Omitted leaves the window '
    + 'to the server, which is not a fixed part of this contract: the platform inbox '
    + 'answers 50 and clamps any requested value into 1..200 rather than refusing it. '
    + 'This endpoint is not paginated — there is no continuation token, so a larger '
    + 'window is the only way to see more.',
  ),
  cursor: retiredKey(NOTIFICATIONS_CURSOR_REMOVED),
}));

export const ListNotificationsResponseSchema = lazySchema(() => z.object({
  notifications: z.array(NotificationSchema).describe('List of notifications — the newest window, not a page'),
  unreadCount: z.number().describe('Total number of unread notifications'),
  cursor: retiredKey(NOTIFICATIONS_CURSOR_REMOVED),
}));

export const MarkNotificationsReadRequestSchema = lazySchema(() => z.object({
  ids: z.array(z.string()).describe('Notification IDs to mark as read'),
}));

export const MarkNotificationsReadResponseSchema = lazySchema(() => z.object({
  success: z.boolean().describe('Whether the operation succeeded'),
  readCount: z.number().describe('Number of notifications marked as read'),
}));

export const MarkAllNotificationsReadRequestSchema = lazySchema(() => z.object({}));

export const MarkAllNotificationsReadResponseSchema = lazySchema(() => z.object({
  success: z.boolean().describe('Whether the operation succeeded'),
  readCount: z.number().describe('Number of notifications marked as read'),
}));

// ==========================================
// AI Operations
// ==========================================
//
// THESE ARE THE SHAPES OF THE ROUTES THAT EXIST (#3718).
//
// What used to live here — `AiNlq*`, `AiSuggest*`, `AiInsights*` — described
// `/api/v1/ai/{nlq,suggest,insights}`, three endpoints **no repo has ever
// mounted**. They were declared here, registered in `DEFAULT_AI_ROUTES` (a
// table with no runtime consumer), typed as optional protocol methods nothing
// implements, and called by `client.ai.*`. Every call 404ed for the whole life
// of the namespace; the SDK's AI surface and the real one were disjoint sets.
//
// The AI service itself is a Cloud/EE package (`service-ai`, in the `cloud`
// repo) — this repo's dispatcher only proxies `/api/v1/ai/**` to whatever
// `buildAIRoutes()` mounted. With the service absent (the open-source
// default) the mount stays, so a request reaches a handler with nothing
// behind it and the answer is **501**, not 404 — 404 would mean the path does
// not exist, which for `/ai/*` is false. Two arms are narrower, and a caller
// branching on status needs both: an **anonymous** caller is refused **401**
// first (the 501 and the courtesy below are both capability disclosures), and
// `GET /ai/agents` answers **200** with an empty list (`{ agents: [] }` under
// the envelope's `data`) — a deliberate console courtesy. The 501 body is no
// local string: it comes from the shared `serviceUnavailableMessage`, the
// same sentence `discovery.services.ai` reports for the slot, so the two
// cannot drift into naming different remedies. So these schemas deliberately
// describe **the wire**, not a protocol this repo serves: they are the one
// shape `client.ai.*` and cloud's route handlers both read.
// The mounted table's reviewed dispositions live in `cloud`
// (`packages/service-ai/src/ai-route-ledger.ts`), which drives this SDK
// against the routes it really returns.

/**
 * One conversation message on the wire.
 *
 * Deliberately permissive about `content`: the AI routes accept a plain string
 * (legacy), a content-part array, and the Vercel AI SDK v6 `parts` form where
 * `content` may be absent entirely. `role` is the part the routes actually
 * validate, so it is the part constrained here — narrowing `content` further
 * would reject payloads the server accepts.
 */
export const AiMessageSchema = lazySchema(() => z.object({
  role: z.enum(['system', 'user', 'assistant', 'tool']).describe('Message role'),
  content: z.unknown().optional().describe('Message content: a string, or an array of content parts'),
  parts: z.array(z.unknown()).optional().describe('Vercel AI SDK v6 message parts (alternative to `content`)'),
}).passthrough()); // adapters carry extra per-message fields (id, createdAt, …)

/**
 * `POST /api/v1/ai/chat` — dual-mode. `stream: false` returns
 * {@link AiChatResponseSchema} as JSON; anything else streams the Vercel UI
 * Message Stream Protocol (SSE with JSON payloads).
 *
 * Flat `model`/`temperature`/`maxTokens` are the Vercel `useChat` shape and
 * take precedence over the same keys nested under `options`.
 */
export const AiChatRequestSchema = lazySchema(() => z.object({
  messages: z.array(AiMessageSchema).min(1).describe('Conversation messages (at least one)'),
  system: z.string().optional().describe('System prompt, prepended as a system message'),
  model: z.string().optional().describe('Model id override'),
  temperature: z.number().optional().describe('Sampling temperature'),
  maxTokens: z.number().int().positive().optional().describe('Maximum tokens to generate'),
  stream: z.boolean().optional().describe('false → JSON response; otherwise the UI Message Stream Protocol'),
  conversationId: z.string().optional().describe('Conversation to persist this turn into (auto-created when omitted)'),
  turnId: z.string().optional().describe('Stable per-turn idempotency key (ADR-0013 D1)'),
  options: z.record(z.string(), z.unknown()).optional().describe('Legacy nested request options'),
}));

/** JSON body of a non-streaming chat/completion turn — the `AIResult` shape. */
export const AiChatResponseSchema = lazySchema(() => z.object({
  content: z.string().describe('Generated text'),
  model: z.string().optional().describe('Model that produced it'),
  toolCalls: z.array(z.unknown()).optional().describe('Tool calls the model requested (Vercel `ToolCallPart`)'),
  usage: z.object({
    promptTokens: z.number().describe('Tokens consumed by the prompt'),
    completionTokens: z.number().describe('Tokens generated'),
    totalTokens: z.number().describe('prompt + completion'),
  }).optional().describe('Token usage'),
  conversationId: z.string().optional().describe('Conversation the turn was persisted into'),
}));

/** `POST /api/v1/ai/complete` — single-shot text completion. */
export const AiCompleteRequestSchema = lazySchema(() => z.object({
  prompt: z.string().describe('Prompt text'),
  options: z.record(z.string(), z.unknown()).optional().describe('Request options (model, temperature, maxTokens, …)'),
}));

/** `GET /api/v1/ai/models` — the environment's plan-filtered picker list (ADR-0028). */
export const AiModelsResponseSchema = lazySchema(() => z.object({
  /**
   * Objects when the service exposes the ADR-0028 allowlist; bare ids when it
   * falls back to the adapter's `listModels()`. Both shapes are live, so both
   * are declared rather than one being asserted and the other 404-by-parse.
   */
  models: z.array(z.union([
    z.string(),
    z.object({
      id: z.string().describe('Model id'),
      label: z.string().describe('Display label for the picker'),
      default: z.boolean().describe('Whether this is the environment default'),
    }),
  ])).describe('Models this system offers'),
  defaultModel: z.string().optional().describe('Default model id, when the service reports one'),
}));

/** A persisted AI conversation, as the `/ai/conversations` routes return it. */
export const AiConversationSchema = lazySchema(() => z.object({
  id: z.string().describe('Conversation id'),
  title: z.string().optional().describe('Title / summary'),
  agentId: z.string().optional().describe('Agent this conversation is bound to'),
  userId: z.string().optional().describe('Owning user'),
  messages: z.array(AiMessageSchema).describe('Message history'),
  createdAt: z.string().describe('Creation timestamp (ISO 8601)'),
  updatedAt: z.string().describe('Last update timestamp (ISO 8601)'),
  metadata: z.record(z.string(), z.unknown()).optional().describe('Conversation metadata'),
}));

/**
 * `POST /api/v1/ai/conversations`. `userId` is NOT accepted from the caller —
 * the route overwrites it with the authenticated actor.
 */
export const CreateAiConversationRequestSchema = lazySchema(() => z.object({
  title: z.string().optional().describe('Initial title'),
  agentId: z.string().optional().describe('Agent to bind the conversation to'),
  metadata: z.record(z.string(), z.unknown()).optional().describe('Conversation metadata'),
}));

/**
 * `GET /api/v1/ai/conversations` query — scoped to the authenticated user.
 *
 * [#19543, door ③] The list is NEWEST FIRST (maintainer ruling on that card:
 * 「Ruled: the list is newest first.」), and it pages by keyset: `cursor` is the
 * `id` of the last conversation the caller already holds — no opaque token is
 * minted, so a caller that has a page has its next cursor. The server half
 * (descending order, the flipped keyset, `hasMore` and the unknown-cursor
 * refusal) is objectstack-ai/cloud#2426; the ruling lets this declaration land
 * first.
 */
export const ListAiConversationsRequestSchema = lazySchema(() => z.object({
  agentId: z.string().optional().describe('Filter by agent'),
  limit: z.number().int().positive().optional().describe('Maximum conversations to return'),
  cursor: z.string().optional().describe(
    'The `id` of the last conversation on the previous page. The next page starts with the '
    + 'conversation created immediately before it, continuing newest first. Omit it to read '
    + 'the first page. An id that names no conversation of the caller is refused rather than '
    + 'read as the start of the list.',
  ),
}));

export const ListAiConversationsResponseSchema = lazySchema(() => z.object({
  conversations: z.array(AiConversationSchema).describe(
    'The caller\'s conversations, newest first — ordered by creation time, then `id`, both descending',
  ),
  // [#19543, door ③] REQUIRED, not optional: an optional flag lets a server
  // that never computes it stay spec-valid forever, and a caller cannot tell
  // "no further page" from "this server does not say". The ruling makes the
  // server compute it (objectstack-ai/cloud#2426, over-read by one row).
  // `nextCursor` is deliberately NOT declared: the ruling defines it as the
  // id of the last conversation on the page, which every caller already
  // holds in `conversations`, so a second field would only be a second place
  // for the same value to disagree.
  hasMore: z.boolean().describe(
    'Whether at least one more conversation follows this page. When `true`, send the `id` of '
    + 'the last conversation in `conversations` as `cursor` to read the next page.',
  ),
}));

/**
 * One frame of a streaming chat response.
 *
 * `POST /api/v1/ai/chat` (streaming mode) speaks the Vercel **UI Message
 * Stream Protocol**: SSE lines carrying JSON objects that always have a
 * `type` — `start`, `text-start`, `text-delta`, `tool-input-available`,
 * `tool-output-available`, `error`, `finish-step`, `finish` — terminated by a
 * literal `data: [DONE]`. `POST /api/v1/ai/chat/stream` uses the same SSE
 * envelope for raw `TextStreamPart` events. Only `type` is guaranteed across
 * both, so only `type` is declared; the rest of each frame passes through.
 */
export const AiStreamChunkSchema = lazySchema(() => z.object({
  type: z.string().describe('Frame type (text-delta, tool-input-available, finish, error, …)'),
}).passthrough());

/** `PATCH /api/v1/ai/conversations/:id` — at least one field is required. */
export const UpdateAiConversationRequestSchema = lazySchema(() => z.object({
  title: z.string().optional().describe('New title'),
  metadata: z.record(z.string(), z.unknown()).optional().describe('New metadata'),
}).refine(requiredOneOf(['title', 'metadata']), {
  message: 'at least one of title or metadata is required',
}));

// ── Named agents ──────────────────────────────────────────────────────────
//
// `/ai/agents` and `/ai/agents/:agentName/chat` were mounted long before the
// SDK could express them: `objectui` hand-built both URLs in five places
// because there was nothing to call. Typed from what the routes RETURN, not
// from what a client might like them to (#3718).

/** What an agent can do, derived server-side from its surface. */
export const AiAgentCapabilitiesSchema = lazySchema(() => z.object({
  authoring: z.boolean().describe('Authors app metadata (objects/views/flows)'),
  canvas: z.boolean().describe('Drives the Live Canvas split view (ADR-0037)'),
  debug: z.boolean().describe('Exposes the build-doctor debug drawer'),
  resume: z.boolean().describe('Turns resume durable multi-step runs (ADR-0013)'),
}));

/** One row of the `GET /api/v1/ai/agents` catalog. */
export const AiAgentSummarySchema = lazySchema(() => z.object({
  name: z.string().describe('Agent name — the `:agentName` path segment'),
  label: z.string().describe('Display label'),
  role: z.string().describe('Agent role'),
  capabilities: AiAgentCapabilitiesSchema.describe('Capability set implied by the agent surface'),
}));

/**
 * `GET /api/v1/ai/agents` — the **`data` payload**, not the whole body.
 *
 * The body is the platform envelope (`BaseResponseSchema`), and this schema is
 * what travels under `data`: `{ success: true, data: { agents: [...] } }`. It
 * was declared as the whole body until #4053 converted the route, and moving it
 * under `data` was a RELOCATION — the payload is unchanged, exactly as
 * `SettingsNamespacePayload` moved in #3843, not a flatten to the bare array the
 * way #3983 reshaped `/share-links`.
 *
 * That distinction is load-bearing, which is why it is recorded on the
 * declaration rather than only at the two producers. `unwrapResponse` returns
 * `data`, so `client.ai.agents.list()` reads `.agents` off this object; flattening
 * to `data: [...]` would make that read `undefined` → an empty catalog, which
 * `useAiSurfaceEnabled` turns into "hide the entire AI surface" — the same thing a
 * seat-less caller and a Community-Edition deployment correctly see, with no
 * error, no 403 and no log to tell them apart. `ai-agents-envelope.test.ts` pins
 * both halves.
 *
 * ACCESS-AWARE: the route returns only agents the CALLER may chat with
 * (ADR-0049), so an empty list is a legitimate answer for a seat-less user —
 * not an error, and not something to retry.
 */
export const AiAgentsResponseSchema = lazySchema(() => z.object({
  agents: z.array(AiAgentSummarySchema).describe('Agents this caller may chat with'),
}));

/**
 * `POST /api/v1/ai/agents/:agentName/chat`.
 *
 * Same dual-mode `stream` flag as `/ai/chat`: absent or `true` streams Vercel
 * Data Stream frames, `false` returns the JSON reply. The client sets it per
 * method rather than leaving it to the caller, so `agents.chat` cannot
 * accidentally return a stream body.
 */
export const AiAgentChatRequestSchema = lazySchema(() => z.object({
  messages: z.array(AiMessageSchema).min(1).describe('Conversation messages (at least one)'),
  context: z.record(z.string(), z.unknown()).optional().describe('Agent context (app, object, record, …)'),
  options: z.record(z.string(), z.unknown()).optional().describe('Request options (model, temperature, …)'),
}));

// ── HITL pending actions ──────────────────────────────────────────────────
//
// The approval queue an embedding app has to render. `objectui` ships a whole
// approval UI on these four routes over hand-built URLs.

/** Lifecycle of a proposed action. Mirrors `PendingActionStatus` in contracts. */
export const AiPendingActionStatusSchema = lazySchema(() =>
  z.enum(['pending', 'approved', 'executed', 'failed', 'rejected']));

/**
 * One queued action, as the routes return it — the persisted row, snake_case
 * because that is the wire shape, not a style choice.
 */
export const AiPendingActionSchema = lazySchema(() => z.object({
  id: z.string().describe('Pending action id'),
  object_name: z.string().describe('Object the action targets'),
  action_name: z.string().describe('Action name'),
  tool_name: z.string().describe('Tool that would execute it'),
  tool_input: z.string().describe('Serialized tool input'),
  status: AiPendingActionStatusSchema.describe('Lifecycle status'),
  result: z.string().optional().describe('Serialized result, once executed'),
  error: z.string().optional().describe('Failure message, when status is failed'),
  rejection_reason: z.string().optional().describe('Reason given at rejection'),
  conversation_id: z.string().optional().describe('Conversation that proposed it'),
  message_id: z.string().optional().describe('Message that proposed it'),
  proposed_by: z.string().optional().describe('Actor that proposed it'),
  decided_by: z.string().optional().describe('Actor that approved or rejected it'),
  proposed_at: z.string().describe('Proposal timestamp (ISO 8601)'),
  decided_at: z.string().optional().describe('Decision timestamp (ISO 8601)'),
}));

/**
 * `GET /api/v1/ai/pending-actions` query.
 *
 * Only the three the ROUTE reads. `AIService.listPendingActions` also accepts
 * `objectName`, but the route never forwards it, so declaring it here would
 * type a filter that silently does nothing.
 */
export const ListAiPendingActionsRequestSchema = lazySchema(() => z.object({
  status: AiPendingActionStatusSchema.optional().describe('Filter by status'),
  conversationId: z.string().optional().describe('Filter by proposing conversation'),
  limit: z.number().int().positive().optional().describe('Max rows (server default 100)'),
}));

export const ListAiPendingActionsResponseSchema = lazySchema(() => z.object({
  items: z.array(AiPendingActionSchema).describe('Queued actions, newest first'),
  total: z.number().describe('Number of rows returned (not a total across pages)'),
}));

/**
 * `POST /api/v1/ai/pending-actions/:id/approve` — approve AND execute.
 *
 * `status: 'failed'` is a 200 with a reason, not an HTTP error: the approval
 * succeeded, the execution did not. A caller that only checks `res.ok` will
 * report a failed write as a success.
 */
export const ApproveAiPendingActionResponseSchema = lazySchema(() => z.object({
  status: z.enum(['executed', 'failed']).describe('Outcome of executing the approved action'),
  result: z.unknown().optional().describe('Tool result, when executed'),
  error: z.string().optional().describe('Failure reason, when failed'),
}));

/** `POST /api/v1/ai/pending-actions/:id/reject` — never executes anything. */
export const RejectAiPendingActionResponseSchema = lazySchema(() => z.object({
  status: z.literal('rejected').describe('Always "rejected"'),
  id: z.string().describe('The rejected action id'),
}));

// ==========================================
// i18n Operations
// ==========================================

export const GetLocalesRequestSchema = lazySchema(() => z.object({}));

/**
 * `GET /api/v1/i18n/locales` — the available locale set.
 *
 * `label` is the locale CODE, echoed back. Every descriptor on every serving
 * surface comes from one helper — `toLocaleDescriptors`
 * (`system/i18n-resolver.ts`), shared by the runtime dispatcher's `/i18n`
 * domain and `service-i18n`'s autonomous route — and it sets `label` to the
 * code, because nothing in the tree carries a locale name to set it from.
 *
 * This describe used to read "Display name of the locale" while no producer
 * ever wrote one: the declared-not-enforced shape ADR-0049 is about, one field
 * wide. A client that trusted it rendered `th` where `ไทย` belongs — which is
 * what objectui#4039 hit, and why the console routes around the field
 * entirely: its language menu reads `code` alone off this body and names
 * locales from its own built-in table plus `Intl.DisplayNames`
 * (`apps/console/src/loadLocales.ts`). So #7634 made the declaration state the
 * convention it actually ships, and `i18n-resolver.test.ts` pins both halves —
 * the values the producer emits, and this text promising them.
 *
 * Naming a locale for a UI stays the client's job: `Intl.DisplayNames` is in
 * every runtime that matters, and *which* language to name it in (its own, or
 * the requester's `Accept-Language`) is a caller's choice the server cannot
 * make for it. Serving real names would put CLDR data behind an endpoint for
 * something every client can already compute, and no consumer asks for it.
 */
export const GetLocalesResponseSchema = lazySchema(() => z.object({
  locales: z.array(z.object({
    code: z.string().describe('BCP-47 locale code (e.g., en-US, zh-CN)'),
    label: z.string().describe(
      'Locale label. Equals `code` on every serving surface today — the client names locales for its UI',
    ),
    isDefault: z.boolean().default(false).describe('Whether this is the default locale'),
  })).describe('Available locales'),
}));

/**
 * `locale` is the whole request — the endpoint returns that locale's full
 * bundle, and there is no server-side filter to ask for.
 *
 * This once declared `namespace` and `keys` filters. Neither serving surface
 * ever read them: the dispatcher domain body takes `parts[1]`/`query.locale`
 * and service-i18n takes `req.params.locale`, so both returned the whole
 * bundle while the SDK dutifully put both on the query string. A caller who
 * passed `keys` to shrink the payload shrank nothing and was told nothing —
 * Prime Directive #10's declared ≠ enforced, the shape #1475 trimmed out of
 * the validation-rule types. Removed rather than implemented (#3676): no
 * caller in this repo or objectui passed either one, `II18nService`
 * (`contracts/i18n-service.ts`) takes only `locale` so a filter could only be
 * a post-filter on an already-materialized bundle — which is precisely not
 * the server-side work `keys` reads as saving — and against the nested
 * `TranslationData` shape #3778 settled on, a flat `keys: string[]` has no
 * defined meaning at all. Re-adding an optional filter is additive and
 * non-breaking the day a consumer actually needs one; a declared-but-unread
 * field is the exemplar the next author copies.
 */
export const GetTranslationsRequestSchema = lazySchema(() => z.object({
  locale: z.string().describe('BCP-47 locale code'),
}));

/**
 * The served document is the MERGE of every loaded bundle — each platform
 * package's own contribution at `kernel:ready` plus the app's
 * `stack.translations` — so it carries the platform-only `settings` group and
 * is typed against the platform face, not the per-app one
 * (`system/translation.zod.ts`).
 */
export const GetTranslationsResponseSchema = lazySchema(() => z.object({
  locale: z.string().describe('Locale code'),
  translations: PlatformTranslationDataSchema.describe('Translation data'),
}));

export const GetFieldLabelsRequestSchema = lazySchema(() => z.object({
  object: z.string().describe('Object name'),
  locale: z.string().describe('BCP-47 locale code'),
}));

export const GetFieldLabelsResponseSchema = lazySchema(() => z.object({
  object: z.string().describe('Object name'),
  locale: z.string().describe('Locale code'),
  labels: z.record(z.string(), z.object({
    label: z.string().describe('Translated field label'),
    help: z.string().optional().describe('Translated help text'),
    options: z.record(z.string(), z.string()).optional().describe('Translated option labels'),
  })).describe('Field labels keyed by field name'),
}));

// ==========================================
// Protocol Interface Schema
// ==========================================

/**
 * TypeScript Types
 * Derived from Zod schemas using z.infer
 */
export type GetDiscoveryRequest = z.input<typeof GetDiscoveryRequestSchema>;
export type GetDiscoveryResponse = z.input<typeof GetDiscoveryResponseSchema>;
export type GetMetaTypesRequest = z.input<typeof GetMetaTypesRequestSchema>;
export type GetMetaTypesResponse = z.input<typeof GetMetaTypesResponseSchema>;
export type GetMetaItemsRequest = z.input<typeof GetMetaItemsRequestSchema>;
export type FlowRegistrationRefusal = z.input<typeof FlowRegistrationRefusalSchema>;
export type FlowRegistration = z.input<typeof FlowRegistrationSchema>;
export type GetMetaItemsResponse = z.input<typeof GetMetaItemsResponseSchema>;
export type GetMetaItemRequest = z.input<typeof GetMetaItemRequestSchema>;
export type GetMetaItemResponse = z.input<typeof GetMetaItemResponseSchema>;
export type GetMetaItemLayeredRequest = z.input<typeof GetMetaItemLayeredRequestSchema>;
export type GetMetaItemLayeredResponse = z.input<typeof GetMetaItemLayeredResponseSchema>;
/**
 * One #4463 runtime authoring-gate finding. The SINGLE declaration of the shape;
 * `@objectstack/metadata-protocol` re-exports this rather than declaring its own
 * (#4717), so the 422 `issues[]` and the 2xx `advisories[]` cannot drift apart.
 */
export type RuntimeAuthoringIssue = z.input<typeof RuntimeAuthoringIssueSchema>;
export type SaveMetaItemRequest = z.input<typeof SaveMetaItemRequestSchema>;
export type SaveMetaItemResponse = z.input<typeof SaveMetaItemResponseSchema>;
/** The 409 `METADATA_CONFLICT` body of the `/meta/:type/:name` write doors (#22114). */
export type MetadataConflictError = z.input<typeof MetadataConflictErrorSchema>;
/** Post-parse shape of {@link MetadataConflictError} — defaults applied, transforms run (ADR-0122). */
export type MetadataConflictErrorParsed = z.infer<typeof MetadataConflictErrorSchema>;
export type PublishMetaItemRequest = z.input<typeof PublishMetaItemRequestSchema>;
export type PublishMetaItemResponse = z.input<typeof PublishMetaItemResponseSchema>;
/**
 * The batch publish door's response — `POST /packages/:id/publish-drafts`
 * (#9406). `probes` is `unknown` by declaration, not by omission: the #9406
 * ruling stages it opaque until a consumer needs a field of it.
 */
export type PublishPackageDraftsResponse = z.input<typeof PublishPackageDraftsResponseSchema>;
export type DeleteMetaItemRequest = z.input<typeof DeleteMetaItemRequestSchema>;
export type DeleteMetaItemResponse = z.input<typeof DeleteMetaItemResponseSchema>;
export type AuditMetaItemRequest = z.input<typeof AuditMetaItemRequestSchema>;
export type AuditMetaItemResponse = z.input<typeof AuditMetaItemResponseSchema>;
export type HistoryMetaItemRequest = z.input<typeof HistoryMetaItemRequestSchema>;
export type HistoryMetaItemResponse = z.input<typeof HistoryMetaItemResponseSchema>;
/** Opaque by ruling (#12038 1C) — see {@link GetPublishedMetaItemResponseSchema}. */
export type GetPublishedMetaItemResponse = z.input<typeof GetPublishedMetaItemResponseSchema>;
/** Post-parse shape of {@link GetPublishedMetaItemResponse} — defaults applied, transforms run (ADR-0122). */
export type GetPublishedMetaItemResponseParsed = z.infer<typeof GetPublishedMetaItemResponseSchema>;
export type ListDraftsResponse = z.input<typeof ListDraftsResponseSchema>;
/** Post-parse shape of {@link ListDraftsResponse} — defaults applied, transforms run (ADR-0122). */
export type ListDraftsResponseParsed = z.infer<typeof ListDraftsResponseSchema>;
export type GetMetaDiagnosticsResponse = z.input<typeof GetMetaDiagnosticsResponseSchema>;
/** Post-parse shape of {@link GetMetaDiagnosticsResponse} — defaults applied, transforms run (ADR-0122). */
export type GetMetaDiagnosticsResponseParsed = z.infer<typeof GetMetaDiagnosticsResponseSchema>;
export type FindReferencesToMetaResponse = z.input<typeof FindReferencesToMetaResponseSchema>;
/** Post-parse shape of {@link FindReferencesToMetaResponse} — defaults applied, transforms run (ADR-0122). */
export type FindReferencesToMetaResponseParsed = z.infer<typeof FindReferencesToMetaResponseSchema>;
export type RollbackMetaItemResponse = z.input<typeof RollbackMetaItemResponseSchema>;
/** Post-parse shape of {@link RollbackMetaItemResponse} — defaults applied, transforms run (ADR-0122). */
export type RollbackMetaItemResponseParsed = z.infer<typeof RollbackMetaItemResponseSchema>;
export type DiffMetaItemResponse = z.input<typeof DiffMetaItemResponseSchema>;
/** Post-parse shape of {@link DiffMetaItemResponse} — defaults applied, transforms run (ADR-0122). */
export type DiffMetaItemResponseParsed = z.infer<typeof DiffMetaItemResponseSchema>;
export type GetMetaItemCachedRequest = z.input<typeof GetMetaItemCachedRequestSchema>;
export type GetMetaItemCachedResponse = z.input<typeof GetMetaItemCachedResponseSchema>;
/** Post-parse shape of {@link GetMetaItemCachedResponse} — defaults applied, transforms run (ADR-0122). */
export type GetMetaItemCachedResponseParsed = z.infer<typeof GetMetaItemCachedResponseSchema>;
export type GetUiViewRequest = z.input<typeof GetUiViewRequestSchema>;
export type GetUiViewResponse = z.input<typeof GetUiViewResponseSchema>;
/** Post-parse shape of {@link GetUiViewResponse} — defaults applied, transforms run (ADR-0122). */
export type GetUiViewResponseParsed = z.infer<typeof GetUiViewResponseSchema>;

type AnalyticsQueryRequest = z.infer<typeof AnalyticsQueryRequestSchema>;
type AnalyticsResultResponse = z.infer<typeof AnalyticsResultResponseSchema>;
type GetAnalyticsMetaRequest = z.infer<typeof GetAnalyticsMetaRequestSchema>;
type GetAnalyticsMetaResponse = z.infer<typeof AnalyticsMetadataResponseSchema>;

export type AutomationTriggerRequest = z.input<typeof AutomationTriggerRequestSchema>;
export type AutomationTriggerResponse = z.input<typeof AutomationTriggerResponseSchema>;
export type AutomationActionsResponse = z.input<typeof AutomationActionsResponseSchema>;
/** Post-parse shape of {@link AutomationActionsResponse} — defaults applied, transforms run (ADR-0122). */
export type AutomationActionsResponseParsed = z.infer<typeof AutomationActionsResponseSchema>;

export type FindDataRequest = z.input<typeof FindDataRequestSchema>;
/** Post-parse shape of {@link FindDataRequest} — defaults applied, transforms run (ADR-0122). */
export type FindDataRequestParsed = z.infer<typeof FindDataRequestSchema>;
export type FindDataResponse = z.input<typeof FindDataResponseSchema>;
export type GetDataRequest = z.input<typeof GetDataRequestSchema>;
export type GetDataResponse = z.input<typeof GetDataResponseSchema>;
export type CreateDataRequest = z.input<typeof CreateDataRequestSchema>;
export type CreateDataResponse = z.input<typeof CreateDataResponseSchema>;
/** The `POST /data/:object/:id/clone` body — see {@link CloneDataResponseSchema} (#11924). */
export type CloneDataResponse = z.input<typeof CloneDataResponseSchema>;
export type ValidateDataIssue = z.input<typeof ValidateDataIssueSchema>;
export type ValidateDataRequest = z.input<typeof ValidateDataRequestSchema>;
export type ValidateDataResponse = z.input<typeof ValidateDataResponseSchema>;
export type UpdateDataRequest = z.input<typeof UpdateDataRequestSchema>;
export type UpdateDataResponse = z.input<typeof UpdateDataResponseSchema>;
export type DeleteDataRequest = z.input<typeof DeleteDataRequestSchema>;
export type DeleteDataResponse = z.input<typeof DeleteDataResponseSchema>;
/**
 * The `GET /api/v1/search` body and its hit element (#11924). ⚠️ Distinct from
 * the per-object `SearchResult` / `SearchHit` in `@objectstack/spec/contracts`
 * — see {@link SearchAllHitSchema} for the trap.
 */
export type SearchAllHit = z.input<typeof SearchAllHitSchema>;
/** One published-page hit of the same body (#13216) — see {@link SearchAllPageHitSchema}. */
export type SearchAllPageHit = z.input<typeof SearchAllPageHitSchema>;
export type SearchAllResponse = z.input<typeof SearchAllResponseSchema>;

export type BatchDataRequest = z.input<typeof BatchDataRequestSchema>;
/** Post-parse shape of {@link BatchDataRequest} — defaults applied, transforms run (ADR-0122). */
export type BatchDataRequestParsed = z.infer<typeof BatchDataRequestSchema>;
export type BatchDataResponse = z.input<typeof BatchDataResponseSchema>;
/** Post-parse shape of {@link BatchDataResponse} — defaults applied, transforms run (ADR-0122). */
export type BatchDataResponseParsed = z.infer<typeof BatchDataResponseSchema>;
export type CreateManyDataRequest = z.input<typeof CreateManyDataRequestSchema>;
export type CreateManyDataResponse = z.input<typeof CreateManyDataResponseSchema>;
export type UpdateManyDataRequest = z.input<typeof UpdateManyDataRequestSchema>;
/** Post-parse shape of {@link UpdateManyDataRequest} — defaults applied, transforms run (ADR-0122). */
export type UpdateManyDataRequestParsed = z.infer<typeof UpdateManyDataRequestSchema>;
export type UpdateManyDataResponse = z.input<typeof UpdateManyDataResponseSchema>;
/** Post-parse shape of {@link UpdateManyDataResponse} — defaults applied, transforms run (ADR-0122). */
export type UpdateManyDataResponseParsed = z.infer<typeof UpdateManyDataResponseSchema>;
export type DeleteManyDataRequest = z.input<typeof DeleteManyDataRequestSchema>;
/** Post-parse shape of {@link DeleteManyDataRequest} — defaults applied, transforms run (ADR-0122). */
export type DeleteManyDataRequestParsed = z.infer<typeof DeleteManyDataRequestSchema>;
export type DeleteManyDataResponse = z.input<typeof DeleteManyDataResponseSchema>;
/** Post-parse shape of {@link DeleteManyDataResponse} — defaults applied, transforms run (ADR-0122). */
export type DeleteManyDataResponseParsed = z.infer<typeof DeleteManyDataResponseSchema>;

// Permission Types
export type CheckPermissionRequest = z.input<typeof CheckPermissionRequestSchema>;
export type CheckPermissionResponse = z.input<typeof CheckPermissionResponseSchema>;
export type GetObjectPermissionsRequest = z.input<typeof GetObjectPermissionsRequestSchema>;
export type GetObjectPermissionsResponse = z.input<typeof GetObjectPermissionsResponseSchema>;
/** Post-parse shape of {@link GetObjectPermissionsResponse} — defaults applied, transforms run (ADR-0122). */
export type GetObjectPermissionsResponseParsed = z.infer<typeof GetObjectPermissionsResponseSchema>;
export type GetEffectivePermissionsRequest = z.input<typeof GetEffectivePermissionsRequestSchema>;
export type GetEffectivePermissionsResponse = z.input<typeof GetEffectivePermissionsResponseSchema>;

// Workflow Types — removed with the schemas (#4451, v17); see the block comment
// at "Workflow Operations — REMOVED" above.

// Realtime Types
export type RealtimeConnectRequest = z.input<typeof RealtimeConnectRequestSchema>;
export type RealtimeConnectResponse = z.input<typeof RealtimeConnectResponseSchema>;
export type RealtimeDisconnectRequest = z.input<typeof RealtimeDisconnectRequestSchema>;
export type RealtimeDisconnectResponse = z.input<typeof RealtimeDisconnectResponseSchema>;
export type RealtimeSubscribeRequest = z.input<typeof RealtimeSubscribeRequestSchema>;
export type RealtimeSubscribeResponse = z.input<typeof RealtimeSubscribeResponseSchema>;
export type RealtimeUnsubscribeRequest = z.input<typeof RealtimeUnsubscribeRequestSchema>;
export type RealtimeUnsubscribeResponse = z.input<typeof RealtimeUnsubscribeResponseSchema>;
export type SetPresenceRequest = z.input<typeof SetPresenceRequestSchema>;
export type SetPresenceResponse = z.input<typeof SetPresenceResponseSchema>;
export type GetPresenceRequest = z.input<typeof GetPresenceRequestSchema>;
export type GetPresenceResponse = z.input<typeof GetPresenceResponseSchema>;

// Notification Types
export type RegisterDeviceRequest = z.input<typeof RegisterDeviceRequestSchema>;
export type RegisterDeviceResponse = z.input<typeof RegisterDeviceResponseSchema>;
export type UnregisterDeviceRequest = z.input<typeof UnregisterDeviceRequestSchema>;
export type UnregisterDeviceResponse = z.input<typeof UnregisterDeviceResponseSchema>;
export type NotificationPreferences = z.input<typeof NotificationPreferencesSchema>;
/** Post-parse shape of {@link NotificationPreferences} — defaults applied, transforms run (ADR-0122). */
export type NotificationPreferencesParsed = z.infer<typeof NotificationPreferencesSchema>;
export type GetNotificationPreferencesRequest = z.input<typeof GetNotificationPreferencesRequestSchema>;
export type GetNotificationPreferencesResponse = z.input<typeof GetNotificationPreferencesResponseSchema>;
/** Post-parse shape of {@link GetNotificationPreferencesResponse} — defaults applied, transforms run (ADR-0122). */
export type GetNotificationPreferencesResponseParsed = z.infer<typeof GetNotificationPreferencesResponseSchema>;
export type UpdateNotificationPreferencesRequest = z.input<typeof UpdateNotificationPreferencesRequestSchema>;
/** Post-parse shape of {@link UpdateNotificationPreferencesRequest} — defaults applied, transforms run (ADR-0122). */
export type UpdateNotificationPreferencesRequestParsed = z.infer<typeof UpdateNotificationPreferencesRequestSchema>;
export type UpdateNotificationPreferencesResponse = z.input<typeof UpdateNotificationPreferencesResponseSchema>;
/** Post-parse shape of {@link UpdateNotificationPreferencesResponse} — defaults applied, transforms run (ADR-0122). */
export type UpdateNotificationPreferencesResponseParsed = z.infer<typeof UpdateNotificationPreferencesResponseSchema>;
export type Notification = z.input<typeof NotificationSchema>;
/** Post-parse shape of {@link Notification} — defaults applied, transforms run (ADR-0122). */
export type NotificationParsed = z.infer<typeof NotificationSchema>;
export type ListNotificationsRequest = z.input<typeof ListNotificationsRequestSchema>;
/** Post-parse shape of {@link ListNotificationsRequest} — defaults applied, transforms run (ADR-0122). */
export type ListNotificationsRequestParsed = z.infer<typeof ListNotificationsRequestSchema>;
export type ListNotificationsResponse = z.input<typeof ListNotificationsResponseSchema>;
/** Post-parse shape of {@link ListNotificationsResponse} — defaults applied, transforms run (ADR-0122). */
export type ListNotificationsResponseParsed = z.infer<typeof ListNotificationsResponseSchema>;
export type MarkNotificationsReadRequest = z.input<typeof MarkNotificationsReadRequestSchema>;
export type MarkNotificationsReadResponse = z.input<typeof MarkNotificationsReadResponseSchema>;
export type MarkAllNotificationsReadRequest = z.input<typeof MarkAllNotificationsReadRequestSchema>;
export type MarkAllNotificationsReadResponse = z.input<typeof MarkAllNotificationsReadResponseSchema>;

// AI Types
export type AiMessage = z.input<typeof AiMessageSchema>;
export type AiChatRequest = z.input<typeof AiChatRequestSchema>;
export type AiChatResponse = z.input<typeof AiChatResponseSchema>;
export type AiStreamChunk = z.input<typeof AiStreamChunkSchema>;
export type AiCompleteRequest = z.input<typeof AiCompleteRequestSchema>;
export type AiModelsResponse = z.input<typeof AiModelsResponseSchema>;
export type AiConversation = z.input<typeof AiConversationSchema>;
export type CreateAiConversationRequest = z.input<typeof CreateAiConversationRequestSchema>;
export type ListAiConversationsRequest = z.input<typeof ListAiConversationsRequestSchema>;
export type ListAiConversationsResponse = z.input<typeof ListAiConversationsResponseSchema>;
export type UpdateAiConversationRequest = z.input<typeof UpdateAiConversationRequestSchema>;
export type AiAgentCapabilities = z.input<typeof AiAgentCapabilitiesSchema>;
export type AiAgentSummary = z.input<typeof AiAgentSummarySchema>;
export type AiAgentsResponse = z.input<typeof AiAgentsResponseSchema>;
export type AiAgentChatRequest = z.input<typeof AiAgentChatRequestSchema>;
export type AiPendingActionStatus = z.input<typeof AiPendingActionStatusSchema>;
export type AiPendingAction = z.input<typeof AiPendingActionSchema>;
export type ListAiPendingActionsRequest = z.input<typeof ListAiPendingActionsRequestSchema>;
export type ListAiPendingActionsResponse = z.input<typeof ListAiPendingActionsResponseSchema>;
export type ApproveAiPendingActionResponse = z.input<typeof ApproveAiPendingActionResponseSchema>;
export type RejectAiPendingActionResponse = z.input<typeof RejectAiPendingActionResponseSchema>;

// i18n Types
export type GetLocalesRequest = z.input<typeof GetLocalesRequestSchema>;
export type GetLocalesResponse = z.input<typeof GetLocalesResponseSchema>;
/** Post-parse shape of {@link GetLocalesResponse} — defaults applied, transforms run (ADR-0122). */
export type GetLocalesResponseParsed = z.infer<typeof GetLocalesResponseSchema>;
export type GetTranslationsRequest = z.input<typeof GetTranslationsRequestSchema>;
export type GetTranslationsResponse = z.input<typeof GetTranslationsResponseSchema>;
export type GetFieldLabelsRequest = z.input<typeof GetFieldLabelsRequestSchema>;
export type GetFieldLabelsResponse = z.input<typeof GetFieldLabelsResponseSchema>;

// Package Management Types (re-exported from kernel for convenience)
export type { 
  ListPackagesRequest,
  ListPackagesResponse,
  GetPackageRequest,
  GetPackageResponse,
  InstallPackageRequest,
  InstallPackageResponse,
  UninstallPackageRequest,
  UninstallPackageResponse,
  EnablePackageRequest,
  EnablePackageResponse,
  DisablePackageRequest,
  DisablePackageResponse,
  InstalledPackage,
  PackageStatus,
};

/**
 * Zod-inferred protocol type (for runtime validation only).
 * Depend on the narrowest per-domain contract (e.g. `DataProtocol`).
 */

/**
 * ObjectStack Protocol Interface
 * 
 * Properly typed interface for implementing the ObjectStack API protocol.
 * Per-domain Zod schemas are used for runtime validation,
 * while this interface provides compile-time type safety for implementations.
 */
// ─────────────────────────────────────────────────────────────────────────────
// Protocol contracts, segmented per domain (ADR-0076 D9).
//
// The historical `ObjectStackProtocol` union of these per-domain contracts was
// and is shape-identical to the historical flat interface — a back-compat alias.
// New code should depend on the narrowest slice it needs (e.g. `DataProtocol`).
// Per ADR-0076 D9 (rev.7) the union is transitional; the end-state dissolves it
// in favour of independent domain protocols + the discovery `services` registry.
// ─────────────────────────────────────────────────────────────────────────────

/** Business-data CRUD + batch operations (thin wire-normalizers over the engine). */
export interface DataProtocol {
  // Data Operations (core)
  findData(request: FindDataRequest): Promise<FindDataResponse>;
  getData(request: GetDataRequest): Promise<GetDataResponse>;
  createData(request: CreateDataRequest): Promise<CreateDataResponse>;
  updateData(request: UpdateDataRequest): Promise<UpdateDataResponse>;
  deleteData(request: DeleteDataRequest): Promise<DeleteDataResponse>;

  /**
   * Validate-only (commit 18189983d — #4633 ruling D): the write path's verdict on
   * candidate rows, with nothing persisted.
   *
   * Declared optional because it is additive to a shipped contract, not
   * because it is aspirational — `metadata-protocol` implements it in the same
   * change that declares it. That is a ruling clause, not a style note:
   * `BatchOptions.validateOnly` was retired in #4052 as a dry-run flag that
   * "promised a dry-run" while every batch surface persisted regardless, so a
   * caller previewing a mutation had it EXECUTED. A second declared-and-unmet
   * validation promise is the one outcome this operation must not become.
   *
   * The verdict honours the deployment's real ADR-0104 posture, so it predicts
   * what THIS deployment would do — see `ValidateDataResponseSchema.posture`.
   */
  validateData?(request: ValidateDataRequest): Promise<ValidateDataResponse>;

  // Batch Operations (optional)
  batchData?(request: BatchDataRequest): Promise<BatchDataResponse>;
  createManyData?(request: CreateManyDataRequest): Promise<CreateManyDataResponse>;
  updateManyData?(request: UpdateManyDataRequest): Promise<UpdateManyDataResponse>;
  deleteManyData?(request: DeleteManyDataRequest): Promise<DeleteManyDataResponse>;
}

/** Discovery + metadata (sys_metadata) management. */
export interface MetadataProtocol {
  // Discovery & Metadata (core)
  getDiscovery(request?: GetDiscoveryRequest): Promise<GetDiscoveryResponse>;
  getMetaTypes(request?: GetMetaTypesRequest): Promise<GetMetaTypesResponse>;
  getMetaItems(request: GetMetaItemsRequest): Promise<GetMetaItemsResponse>;
  getMetaItem(request: GetMetaItemRequest): Promise<GetMetaItemResponse>;
  saveMetaItem(request: SaveMetaItemRequest): Promise<SaveMetaItemResponse>;
  /**
   * Promote the pending DRAFT overlay to the live (`active`) row — the write
   * sibling of `saveMetaItem` and the verb behind
   * `POST /api/v1/meta/:type/:name/publish`, i.e. the second half of Studio's
   * designer save-then-publish loop (ADR-0033 two-step: `?mode=draft` stages
   * a body, this makes it live). Declared optional like its `deleteMetaItem`
   * / `getMetaItemLayered` siblings: additive to a shipped contract, with the
   * implementation (`@objectstack/metadata-protocol`) predating the
   * declaration. Commit cccbe51bf (maintainer ruling 2026-08-22, option B) promotes
   * what was an ADR-0076 D9 server-only extension into a declared optional
   * member, closing the half-declared door #7294 left: the response side was
   * declared there while the request and this member were not — so the
   * request literal at the one HTTP call site had nothing checking it.
   */
  publishMetaItem?(request: PublishMetaItemRequest): Promise<PublishMetaItemResponse>;
  /**
   * Delete a metadata customization overlay row. Per ADR-0005 this is the
   * "reset to artifact factory default" semantic — it removes a sys_metadata
   * row (if present) so subsequent reads fall through to the compiled
   * artifact. Whitelisted to view + dashboard in project-kernel mode.
   */
  deleteMetaItem?(request: DeleteMetaItemRequest): Promise<DeleteMetaItemResponse>;
  getMetaItemCached?(request: GetMetaItemCachedRequest): Promise<GetMetaItemCachedResponse>;
  /**
   * Three-layer diagnostic read (`GET /api/v1/meta/:type/:name/layers`) —
   * packaged baseline, tenant overlay row and merged result side by side; see
   * {@link GetMetaItemLayeredResponseSchema} for the shape and its #5882
   * route-separation rationale. A declared-surface catch-up, not a new
   * capability: `metadata-protocol` has shipped this verb since the layered
   * route landed. Declared optional like its `getMetaItemCached` /
   * `deleteMetaItem` siblings — additive to a shipped contract, with the
   * implementation predating the declaration.
   */
  getMetaItemLayered?(request: GetMetaItemLayeredRequest): Promise<GetMetaItemLayeredResponse>;
  /**
   * ADR-0010 §3.6 compliance trail read (`GET /api/v1/meta/:type/:name/audit`)
   * — recent `sys_metadata_audit` rows for one item, newest first, so Studio's
   * 审计日志 / Audit log tab can show who tried what and whether a lock
   * blocked it. Declared optional like its `deleteMetaItem` /
   * `getMetaItemLayered` siblings: additive to a shipped contract, with the
   * implementation (`@objectstack/metadata-protocol`) predating the
   * declaration. Promotes what was an ADR-0076 D9 server-only extension into
   * a declared optional member (the maintainer-ruled pattern of commit cccbe51bf,
   * 2026-08-22 option B, carried one door over) — before this, the REST audit
   * door reached the verb through a runtime cast and its request literal was
   * compiled against nothing. A host without the verb is CONFORMING: the REST
   * door feature-detects and answers 501 before the call (#9426 — a missing
   * capability is never reported as an empty trail).
   */
  auditMetaItem?(request: AuditMetaItemRequest): Promise<AuditMetaItemResponse>;
  /**
   * Durable change-log read (`GET /api/v1/meta/:type/:name/history`) — the
   * `sys_metadata_history` events for one item, oldest first, that Studio's
   * History tab renders as a timeline (the audit member above serves the
   * sibling 审计日志 / Audit log tab; ADR-0008 §2.4 is the event contract).
   * Declared optional like its `auditMetaItem` / `deleteMetaItem` /
   * `getMetaItemLayered` siblings: additive to a shipped contract, with the
   * implementation (`@objectstack/metadata-protocol`) predating the
   * declaration. Promotes what was an ADR-0076 D9 server-only extension into
   * a declared optional member (the maintainer-ruled pattern of commit cccbe51bf,
   * 2026-08-22 option B, carried one door over exactly as #11678 carried it
   * to the audit twin) — before this, the REST history door reached the verb
   * through a runtime cast and its request literal was compiled against
   * nothing. A host without the verb is CONFORMING: the REST door
   * feature-detects and answers 501 before the call. A host WITH the verb
   * answers `{ events: [] }` for a non-overlay type — no history exists by
   * construction — which is a declared, honest body, never a capability
   * signal.
   */
  historyMetaItem?(request: HistoryMetaItemRequest): Promise<HistoryMetaItemResponse>;
  getUiView?(request: GetUiViewRequest): Promise<GetUiViewResponse>;
}

/** Analytics (optional). */
export interface AnalyticsProtocol {
  analyticsQuery?(request: AnalyticsQueryRequest): Promise<AnalyticsResultResponse>;
  getAnalyticsMeta?(request: GetAnalyticsMetaRequest): Promise<GetAnalyticsMetaResponse>;
}

/** Automation (optional). */
export interface AutomationProtocol {
  triggerAutomation?(request: AutomationTriggerRequest): Promise<AutomationTriggerResponse>;
}

/** Package lifecycle (optional). */
export interface PackageProtocol {
  listPackages?(request: ListPackagesRequest): Promise<ListPackagesResponse>;
  getPackage?(request: GetPackageRequest): Promise<GetPackageResponse>;
  installPackage?(request: InstallPackageRequest): Promise<InstallPackageResponse>;
  uninstallPackage?(request: UninstallPackageRequest): Promise<UninstallPackageResponse>;
  enablePackage?(request: EnablePackageRequest): Promise<EnablePackageResponse>;
  disablePackage?(request: DisablePackageRequest): Promise<DisablePackageResponse>;
}

// `ViewProtocol` (`listViews` / `getView` / `createView` / `updateView` /
// `deleteView`) was REMOVED at protocol 17 — see the "View Management
// Operations — RETIRED" note above (commit f549a0d4a). No host implemented it and no route
// reached it; view read/write is `MetadataProtocol` (`getMetaItem` /
// `saveMetaItem` / `deleteMetaItem` with `type: 'view'`) plus `getUiView`.

/** Permissions (optional). */
export interface PermissionProtocol {
  checkPermission?(request: CheckPermissionRequest): Promise<CheckPermissionResponse>;
  getObjectPermissions?(request: GetObjectPermissionsRequest): Promise<GetObjectPermissionsResponse>;
  getEffectivePermissions?(request: GetEffectivePermissionsRequest): Promise<GetEffectivePermissionsResponse>;
}

// `WorkflowProtocol` (optional sub-protocol) was removed here (#4451, v17):
// no implementation of any of its three methods ever existed. See the
// "Workflow Operations — REMOVED" block comment above.

/** Realtime / presence (optional). */
export interface RealtimeProtocol {
  realtimeConnect?(request: RealtimeConnectRequest): Promise<RealtimeConnectResponse>;
  realtimeDisconnect?(request: RealtimeDisconnectRequest): Promise<RealtimeDisconnectResponse>;
  realtimeSubscribe?(request: RealtimeSubscribeRequest): Promise<RealtimeSubscribeResponse>;
  realtimeUnsubscribe?(request: RealtimeUnsubscribeRequest): Promise<RealtimeUnsubscribeResponse>;
  setPresence?(request: SetPresenceRequest): Promise<SetPresenceResponse>;
  getPresence?(request: GetPresenceRequest): Promise<GetPresenceResponse>;
}

/** Notifications (optional). */
export interface NotificationProtocol {
  registerDevice?(request: RegisterDeviceRequest): Promise<RegisterDeviceResponse>;
  unregisterDevice?(request: UnregisterDeviceRequest): Promise<UnregisterDeviceResponse>;
  getNotificationPreferences?(request: GetNotificationPreferencesRequest): Promise<GetNotificationPreferencesResponse>;
  updateNotificationPreferences?(request: UpdateNotificationPreferencesRequest): Promise<UpdateNotificationPreferencesResponse>;
  listNotifications?(request: ListNotificationsRequest): Promise<ListNotificationsResponse>;
  markNotificationsRead?(request: MarkNotificationsReadRequest): Promise<MarkNotificationsReadResponse>;
  markAllNotificationsRead?(request: MarkAllNotificationsReadRequest): Promise<MarkAllNotificationsReadResponse>;
}

// `AiProtocol` is GONE (#3718).
//
// It declared exactly three optional methods — `aiNlq?` / `aiSuggest?` /
// `aiInsights?` — and no service in any repo implemented one. Nothing
// dispatched through it either: `/api/v1/ai/**` is proxied straight to the
// route handlers `service-ai` (Cloud/EE, in the `cloud` repo) builds, never
// through a protocol object. An interface whose every member is optional and
// unimplemented does not describe a server — it only makes one look declared.
//
// The real server-side contract for AI is `IAIService` +
// `IAIConversationService` in `@objectstack/spec/contracts` (`ai-service.ts`),
// which `service-ai` actually implements. The wire shapes those routes speak
// are the `Ai*` schemas above.

/** Localization (optional). */
export interface I18nProtocol {
  getLocales?(request: GetLocalesRequest): Promise<GetLocalesResponse>;
  getTranslations?(request: GetTranslationsRequest): Promise<GetTranslationsResponse>;
  getFieldLabels?(request: GetFieldLabelsRequest): Promise<GetFieldLabelsResponse>;
}