@objectstack/types 16.1.0 → 17.0.0-rc.1

package/dist/index.d.mts

@@ -1,3 +1,66 @@
+import { TenancyPosture } from '@objectstack/spec/security';
+import { ErrorCode, ApiError } from '@objectstack/spec/api';
+
+/**
+ * Degraded-boot reporting, shared by every subsystem that can be told to boot
+ * without a datasource it needs.
+ *
+ * Two of them exist today and they opt in through the *same* operator flag
+ * (`OS_ALLOW_DRIVER_CONNECT_FAILURE`, see {@link resolveAllowDriverConnectFailure}):
+ *
+ *  - `ObjectQLEngine.init()` — a boot-registered driver whose `connect()`
+ *    rejected (framework#3741).
+ *  - `DatasourceConnectionService` — a declared datasource that objects bind to
+ *    explicitly, or an `external` one with `validation.onMismatch:'fail'`,
+ *    that could not be connected (framework#3758).
+ *
+ * They live in different packages but owe the operator the same thing: the
+ * degraded state must be impossible to miss.
+ */
+/**
+ * Emit the degraded-boot banner on a channel the host cannot accidentally
+ * silence.
+ *
+ * `OS_ALLOW_DRIVER_CONNECT_FAILURE` only justifies itself if the state it opts
+ * into is impossible to miss — and a logger-only banner is missable, because
+ * the logger answers to a level the operator sets. `Logger.write()` returns
+ * before emitting anything when the record is below `config.level`, so at
+ * `--log-level error`, `fatal`, or `silent` this `warn` never reaches ANY
+ * stream. A production host running at `error` is exactly the deployment this
+ * flag exists for, and is exactly where the banner would vanish. Writing to
+ * stderr as well is the same belt-and-braces the kernel already uses for
+ * plugin startup failures.
+ *
+ * A second reason used to be load-bearing and no longer is: `os serve` blanked
+ * ALL of stdout while the kernel booted, and `Logger` routes `warn` to stdout,
+ * so a boot-phase banner was swallowed at every level. That was framework#4012
+ * and is fixed — the boot window buffers and replays `warn`-and-above instead
+ * of discarding it. Do not re-derive this helper's necessity from the
+ * boot-quiet capture; the level filter is what keeps it alive.
+ *
+ * Best-effort and never throws: falls back to `console.error`, then to silence
+ * on runtimes that have neither (the logger still carries the structured
+ * record either way).
+ */
+declare function emitDegradedBootBanner(message: string): void;
+
+/**
+ * Environment-variable helpers shared across `@objectstack/*` packages.
+ *
+ * The framework standardises on `OS_*` prefixed env vars (see AGENTS.md
+ * "Environment Variables" section). Some historical names predate this
+ * convention — `AUTH_SECRET`, `ROOT_DOMAIN`, `OBJECTSTACK_*`, …
+ *
+ * To migrate without breaking user `.env` files mid-release, call
+ * {@link readEnvWithDeprecation} at every legacy read site:
+ *
+ *   const v = readEnvWithDeprecation('OS_AUTH_SECRET', 'AUTH_SECRET');
+ *
+ * If only the legacy name is set, the value is still returned but a
+ * one-shot `console.warn` fires (per-process per-variable) telling
+ * operators to rename it.
+ */
+
 /**
  * Read an env var, preferring the canonical `OS_*` name and falling
  * back to one or more legacy aliases.
@@ -45,6 +108,28 @@ declare function readEnvWithDeprecation(preferred: string, legacy: string | read
  * result must be stable for the process lifetime.
  */
 declare function resolveMultiOrgEnabled(): boolean;
+/**
+ * [ADR-0105 D1] Resolve the deployment's REQUESTED tenancy posture —
+ * `single` | `group` | `isolated`.
+ *
+ * `OS_TENANCY_POSTURE` is the canonical knob and generalizes the boolean
+ * `OS_MULTI_ORG_ENABLED` it supersedes:
+ *
+ * - set → that posture (the legacy spelling `multi` normalizes to `isolated`)
+ * - unset → derived from `OS_MULTI_ORG_ENABLED`: `true` ⇒ `isolated`, else `single`
+ *
+ * so every existing deployment keeps its current posture with no config change.
+ *
+ * An unrecognized value THROWS rather than falling back. A typo'd posture that
+ * quietly resolved to `single` would silently remove the organization wall —
+ * the deployment-layer form of the "declared but unenforced" defect ADR-0049
+ * forbids, and the same reasoning behind ADR-0093 D5's refusal to boot into
+ * undeclared degradation.
+ *
+ * This resolves what the operator ASKED FOR. Whether the posture is actually
+ * enforced is the `tenancy` service's answer (`isolationActive` / `degraded`).
+ */
+declare function resolveTenancyPosture(): TenancyPosture;
 /**
  * Escape hatch for the degraded-tenancy boot guard (ADR-0093 D5).
  *
@@ -57,6 +142,43 @@ declare function resolveMultiOrgEnabled(): boolean;
  * an unset flag means "fail fast".
  */
 declare function resolveAllowDegradedTenancy(): boolean;
+/**
+ * Escape hatch for the driver-connect boot guard (framework#3741).
+ *
+ * `ObjectQLEngine.init()` connects every boot-registered driver and, by
+ * default, refuses to boot when any of them fails — a server whose database is
+ * unreachable must not report itself started and then 500 every request with an
+ * error that reads nothing like "the database is down". Failing there is also
+ * what gives a driver the ability to REFUSE STARTUP at all: any fatal startup
+ * check a driver wants to run (licence, server version, incompatible
+ * configuration, missing capability) can simply throw from `connect()`.
+ *
+ * Setting this to a truthy value (`true`/`1`/`on`/`yes`, case-insensitive)
+ * boots anyway, in an explicitly degraded state that is logged loudly at
+ * startup. Every query routed to a failed driver fails until the datasource
+ * becomes reachable — the underlying clients do re-establish connections on
+ * their own (framework#3759) — but the boot-time schema sync those drivers
+ * missed is never re-run, so their tables may simply not exist afterwards.
+ * Defaults OFF — an unset flag means "fail fast".
+ */
+declare function resolveAllowDriverConnectFailure(): boolean;
+/**
+ * Escape hatch for plugin-dev's production boot guard (ADR-0115 D6, #3900).
+ *
+ * `DevPlugin.init()` refuses to run under `NODE_ENV=production`: the stack it
+ * assembles is built around an auth secret published inside the npm package and
+ * an in-memory driver with persistence off, neither of which a production
+ * deployment should acquire by accident. Setting this to a truthy value
+ * (`true`/`1`/`on`/`yes`, case-insensitive) boots anyway, in an explicitly
+ * degraded state that is branded in the boot log and on the ready banner.
+ * Defaults OFF — an unset flag means "fail fast".
+ *
+ * Lives here rather than as a bare `process.env[…] === '1'` inside plugin-dev so
+ * that the whole `OS_ALLOW_*` family answers to one truthy vocabulary: the
+ * strict `=== '1'` it replaced fails CLOSED on `OS_ALLOW_DEV_PLUGIN=true`, which
+ * is safe but reads to an operator as the flag being broken.
+ */
+declare function resolveAllowDevPlugin(): boolean;
 /**
  * SINGLE decision point for "is the MCP HTTP surface (`/api/v1/mcp`) on?".
  *
@@ -140,14 +262,46 @@ declare function resolveOrgLimit(): number | undefined;
  *   3. No env var and no `zh-*` locale → off. OSS / non-Chinese deployments
  *      never load `pinyin-pro` and pay zero compute cost.
  *
- * Hosts that know the stack's i18n config (the CLI `serve` boot path) resolve
- * once with locales and stamp the decision back into the env, so downstream
- * consumers constructed without config access (per-engine SchemaRegistry)
- * read the same answer via the no-arg form.
+ * Hosts that know the stack's i18n config — the CLI `serve` boot path AND the
+ * standalone artifact boot (`createStandaloneStack`, which `os migrate`
+ * plan/apply and embedders go through) — resolve once with locales and stamp
+ * the decision back into the env via {@link stampSearchPinyinEnabled}, so
+ * downstream consumers constructed without config access (per-engine
+ * SchemaRegistry) read the same answer via the no-arg form (#3955).
  */
 declare function resolveSearchPinyinEnabled(opts?: {
     locales?: readonly string[];
 }): boolean;
+/**
+ * The locales a stack's `i18n` config declares — `defaultLocale`,
+ * `fallbackLocale`, then `supportedLocales`. Accepts the config loosely typed
+ * (`unknown`) so any boot path can pass whatever its stack config or compiled
+ * artifact carries without importing spec schemas; non-string entries and a
+ * non-object config collapse to `[]`.
+ */
+declare function collectConfiguredLocales(i18n: unknown): string[];
+/**
+ * Resolve the pinyin-search decision from a stack's `i18n` config and stamp a
+ * positive result back into `OS_SEARCH_PINYIN_ENABLED` (#2486, #3955).
+ *
+ * Every boot path that SEES the stack config must stamp, because consumers
+ * constructed later without config access (each engine's `SchemaRegistry`
+ * provisioning the `__search` companion column, the `plugin-pinyin-search`
+ * gate) read the decision through the no-arg
+ * {@link resolveSearchPinyinEnabled}. A boot path that skips the stamp
+ * computes a schema view WITHOUT the companion columns — which is how
+ * `os migrate` came to flag the dev runtime's live `__search` columns as
+ * destructive orphans (#3955). Call sites: the CLI `serve`/`dev` boot
+ * (`objectstack.config.ts`) and `createStandaloneStack` (compiled artifact —
+ * `os migrate plan`/`apply`, embedders).
+ *
+ * An explicit `OS_SEARCH_PINYIN_ENABLED` always wins — the resolver reads it
+ * before consulting locales, so the stamp only materializes the
+ * locale-derived default. Only a positive decision is written: "unset" and
+ * "off" read identically through the no-arg resolver, and leaving the var
+ * untouched keeps a later boot free to re-derive from ITS config.
+ */
+declare function stampSearchPinyinEnabled(i18n: unknown): boolean;
 /**
  * SINGLE decision point for a sandbox script-runner DEFAULT (ms), resolved from
  * the environment (framework#3259 / ADR-0102).
@@ -184,6 +338,144 @@ declare function resolveSandboxTimeoutMs(kind: 'hook' | 'action' | 'wallCeiling'
  */
 declare function _resetEnvDeprecationWarnings(): void;
 
+/**
+ * Shared "does this error message leak server internals?" heuristic (#3867).
+ *
+ * ObjectStack has more than one HTTP boundary. `@objectstack/rest` guards the
+ * REST data routes inside `mapDataError`; the dispatcher-plugin routes
+ * (`/analytics`, `/packages`, `/i18n`, `/automation`, …) exit
+ * through `errorResponseBase`. Before #3867 only the first of those sanitised
+ * anything, so a driver error raised under `/analytics/query` reached the
+ * client verbatim — a real SQL statement in the response body:
+ *
+ * ```
+ * {"success":false,"error":{"message":"SELECT  FROM \"sqlite_sequence\" - near \"FROM\": syntax error","code":500}}
+ * ```
+ *
+ * "Do not ship driver internals to clients" is a property of the HTTP
+ * boundary, not of one router, so the predicate lives here — the package both
+ * `@objectstack/rest` and `@objectstack/runtime` already depend on — and each
+ * boundary applies it in its own envelope. One heuristic, one place to widen
+ * when a new dialect's phrasing shows up.
+ *
+ * Deliberately a *heuristic over the message*, not a driver taxonomy: these
+ * errors arrive as plain `Error`s from a half-dozen dialects with no shared
+ * shape. It is applied only where the outcome is already a 5xx, so a false
+ * positive costs a caller nothing but detail on a response that was a server
+ * fault anyway — while the full text still reaches server logs and the
+ * error reporter.
+ */
+/** Generic replacement text for a message that trips {@link looksLikeInternalErrorLeak}. */
+declare const INTERNAL_ERROR_MESSAGE = "Internal server error";
+/**
+ * Whether `message` looks like a raw SQL statement or driver/engine dump that
+ * must not be returned to an API client.
+ *
+ * Matches: dialect error codes (`SQLSTATE`, `sqlite_*`), bare statements
+ * (a message that *starts* as `SELECT`/`INSERT INTO`/`UPDATE`/`DELETE FROM` —
+ * drivers prefix the offending SQL to their message), and constraint-violation
+ * dumps, which name physical tables and columns.
+ *
+ * Does NOT match ordinary business or validation messages, which is why the
+ * statement forms are anchored with `startsWith`: a legitimate message may
+ * *mention* "update" without being one.
+ */
+declare function looksLikeInternalErrorLeak(message: string | undefined | null): boolean;
+
+/**
+ * Seek-based (keyset) pagination for the batch walks that read a whole object.
+ *
+ * # Why this exists rather than `limit`/`offset`
+ *
+ * A background walk that pages with a growing `offset` — rebuild an index,
+ * verify file references, backfill a projection — is wrong in two ways that a
+ * seek fixes at once.
+ *
+ * **It can skip rows.** `LIMIT n OFFSET k` is a slice of an arrangement, and
+ * the arrangement has to be the *same* one on every page for the slices to
+ * partition the set. Drivers now guarantee that for a single read
+ * (objectstack#4363), but not across a walk that *mutates as it goes*: a
+ * backfill that updates each page, or a rebuild that deletes, changes the very
+ * set the next offset counts into. Rows shift past the cursor and are never
+ * visited. For a verifier that decides which files are still referenced, or an
+ * index rebuild that deletes what it did not see, a skipped row is not a slow
+ * page — it is a wrong answer that looks like a clean run. A seek predicate
+ * carries the position *in the data* instead of counting from the start, so an
+ * update cannot move a row past it and a delete cannot shift one under it.
+ *
+ * **It is quadratic.** The database must produce and discard every skipped row
+ * to honor an offset, so walking n rows in pages of p costs O(n²/p). On a
+ * 2M-row table the last pages were measured at ~1.1 s each against ~0.09 s for
+ * the first. A seek starts each page at the cursor, so every page costs the
+ * same: O(n) for the walk, and index-served throughout.
+ *
+ * # What it requires
+ *
+ * A column that is **unique and orderable** — `id` by default, which every
+ * object this driver-managed platform creates carries. An object without one
+ * (a federated table, ADR-0015) cannot be walked this way; callers that scan
+ * arbitrary registry objects already skip what they cannot read, and that is
+ * the correct outcome here too rather than a silent partial scan.
+ *
+ * # Shape
+ *
+ * `read` is the caller's own query — this owns the loop, the cursor and the
+ * `where` merge, and nothing else. Deliberately one implementation rather than
+ * the six hand-rolled copies it replaces: the cursor merge is the part that is
+ * easy to get subtly wrong (an object whose own `where` already constrains the
+ * key), and six copies of it drift silently.
+ *
+ * @example
+ * const walk = keysetWalk<Row>(
+ *   (q) => engine.find('sys_approval_request', { ...q, fields: ['id'], context: SYSTEM_CTX }),
+ *   { where: { status: 'pending' }, pageSize: 500 },
+ * );
+ * for await (const page of walk.pages()) { … }
+ * if (walk.truncated) { … }
+ */
+/** The query a {@link keysetWalk} hands its reader: the caller's `where`, narrowed by the cursor. */
+interface KeysetPageQuery {
+    /** The caller's `where`, AND-ed with the seek predicate once the walk has a cursor. */
+    where?: unknown;
+    /** Always ascending on the key column — the walk's order IS the seek order. */
+    orderBy: Array<{
+        field: string;
+        order: 'asc';
+    }>;
+    /** Page size. */
+    limit: number;
+}
+interface KeysetWalkOptions {
+    /** The caller's filter, applied to every page. */
+    where?: unknown;
+    /** Rows per page. */
+    pageSize: number;
+    /**
+     * Stop after this many rows and set {@link KeysetWalk.truncated}. Omit for an
+     * unbounded walk. A cap is not a failure — it is how a scan bounds its own
+     * cost — but it must be reported, or a partial scan reads as a complete one.
+     */
+    max?: number;
+    /** Unique, orderable column to seek on. Defaults to `id`. */
+    key?: string;
+}
+interface KeysetWalk<T> {
+    /** Pages, in key order, until the source is exhausted or `max` is reached. */
+    pages(): AsyncGenerator<T[]>;
+    /** Rows yielded so far. */
+    readonly scanned: number;
+    /** True when `max` stopped the walk before the source was exhausted. */
+    readonly truncated: boolean;
+}
+/**
+ * Walk an object by seeking past the last key rather than counting from the
+ * start. See the module comment for why every batch scan should.
+ *
+ * `read` receives a {@link KeysetPageQuery} and returns the page; the caller
+ * owns everything else about the query (projection, context, object name).
+ */
+declare function keysetWalk<T extends Record<string, unknown>>(read: (query: KeysetPageQuery) => Promise<T[]>, options: KeysetWalkOptions): KeysetWalk<T>;
+
 /**
  * True when a dynamic `import()` / `require.resolve()` failed because the
  * module is simply NOT INSTALLED — as opposed to the module being present but
@@ -200,6 +492,129 @@ declare function _resetEnvDeprecationWarnings(): void;
  */
 declare function isModuleNotFoundError(err: unknown): boolean;
 
+/**
+ * The ONE writer for the declared REST response envelope (#3973).
+ *
+ * `BaseResponseSchema` (`packages/spec/src/api/contract.zod.ts`) declares one
+ * envelope for every REST body the platform emits:
+ *
+ *     { success: true,  data }
+ *     { success: false, error: { code, message } }
+ *
+ * The schema declares it once. Until this file, the code that *wrote* it was
+ * copied per route module — seven `sendOk` / `sendError` pairs after #3843 and
+ * #3983 converted the last drifting one, so the envelope's shape lived in
+ * fourteen places rather than one.
+ *
+ * ## Why a shared builder rather than seven agreeing copies
+ *
+ * `scripts/check-route-envelope.mjs` proves the copies agree today, and that is
+ * exactly why this is a cleanup and not a bug fix. But a guard proves agreement;
+ * it does not create it. An eighth module starts by copying the pair again —
+ * which is not hypothetical, it is the observed history: `share-link-routes.ts`
+ * was found by the repo-wide scan already drifting, and its drift had broken
+ * `client.shareLinks.create()` / `.list()` through `unwrapResponse` (#3983).
+ *
+ * ## Why here
+ *
+ * Placement was the open question in #3973, not design. `packages/spec` is
+ * schemas-only (Prime Directive #2), and the callers span `packages/rest`, four
+ * `services/*` and one `plugins/*`, which rules out anything that depends on
+ * them. `@objectstack/types` depends on nothing but `@objectstack/spec`, so
+ * every caller can reach it, and it is where the repo already puts a helper the
+ * HTTP boundaries share: {@link looksLikeInternalErrorLeak} lives one file over
+ * for the same reason, and made the same argument first — "do not ship driver
+ * internals to clients" is a property of the boundary, not of one router.
+ *
+ * Writing the declared envelope is the same kind of property.
+ *
+ * ## What this does NOT change
+ *
+ * Every byte on the wire. The seven pairs were already identical modulo the
+ * optional `status` and `extra` parameters unioned below; this file is their
+ * union, and each module's driven conformance suite still parses its real
+ * bodies against the real spec schemas.
+ *
+ * The dispatcher surface (`packages/runtime/src/domains/*`) is deliberately not
+ * a caller: those handlers RETURN `{ status, body }` for a central sender rather
+ * than writing to a response, so they are already consolidated behind their own
+ * `deps.success` / `deps.error` helpers and audited by the other half of
+ * `check-route-envelope.mjs`.
+ */
+
+/**
+ * The only thing an envelope builder needs from a response object.
+ *
+ * Structural on purpose, so this file depends on no HTTP contract at all:
+ * `IHttpResponse` (`@objectstack/spec/contracts`) satisfies it, and so does the
+ * `any`-typed `res` the three older route modules still carry. That is what lets
+ * a package import the builders without also importing a server abstraction.
+ */
+interface EnvelopeResponse {
+    status(code: number): EnvelopeResponse;
+    json(body: unknown): unknown;
+}
+/**
+ * Emit a success body in the DECLARED envelope — `{ success: true, data }`.
+ *
+ * `data` carries the route's payload; it is not spread. A payload duplicated
+ * into a stray top-level key (`{ success: true, data: link, link }`) parses
+ * clean against `BaseResponseSchema` and is still drift — that shipped on
+ * `/share-links` for as long as nobody looked (#4038), which is why
+ * `envelopeViolations` exists beside the schema and why there is one `data`
+ * slot here rather than a spread.
+ *
+ * `status` defaults to 200 and is set explicitly even then. Five of the seven
+ * modules already did that; the two that called `res.json(...)` bare are
+ * unaffected, because the default they were relying on is the value now passed.
+ */
+declare function sendOk(res: EnvelopeResponse, data: unknown, status?: number): void;
+/**
+ * Emit an error in the DECLARED envelope — `{ success: false, error: { code,
+ * message } }`, with `code` a semantic STRING and `message` a field OF `error`
+ * rather than a sibling of it.
+ *
+ * Both halves of that sentence were once wrong somewhere: `error` was a bare
+ * string in `service-storage` and `admin-routes` (so `body.error.message` read
+ * `undefined`), and `code` was the human message in `package-routes` (#3675 →
+ * #3689 → #3843).
+ *
+ * ## `code` is the closed ADR-0112 vocabulary, not `string`
+ *
+ * All seven copies typed this parameter `string`, so an invented code was caught
+ * only at runtime, by a conformance suite parsing a driven body against
+ * `ApiErrorSchema` — i.e. only on the routes a test happened to drive. `ErrorCode`
+ * is `StandardErrorCode ∪ ERROR_CODE_LEDGER` (`error-code-ledger.zod.ts`), the
+ * same union that schema validates against, so consolidating here moves the check
+ * to compile time for every call site at once. It cost no call-site churn: every
+ * code the seven modules emit was already registered.
+ *
+ * A new code is registered in `ERROR_CODE_LEDGER` under its owning package —
+ * and if the condition is generic (not found / permission / validation), the
+ * standard catalog is used instead of registering a synonym for it.
+ *
+ * ## `extra` is `ApiError`'s own optional fields, not a `Record`
+ *
+ * Merged into `error`, and typed as exactly what `ApiErrorSchema` declares
+ * beside `code` and `message` — `details`, `category`, `requestId`, `httpStatus`.
+ * `details` is the slot for structured context: `package-routes` puts a partial
+ * delete's per-item failures there, `settings-routes` the whole
+ * `SettingsActionResult`.
+ *
+ * This started as `Record<string, unknown>`, because `settings-routes` also hung
+ * `namespace` / `key` / `reason` / `fields` beside `code`, which the schema does
+ * not declare. Those bodies passed every gate anyway — `ApiErrorSchema` is a
+ * plain `z.object`, so unknown keys were STRIPPED rather than rejected, and
+ * `envelopeViolations` inspects only the body's top level — making them
+ * conformant *by stripping* rather than by declaration. #4224 moved that module's
+ * four branches onto `details`, which is what lets the parameter close here.
+ *
+ * Closing it at the shared builder is the part that lasts: an undeclared sibling
+ * is now a compile error in every module at once, rather than a key that quietly
+ * evaporates at the schema boundary in whichever module reintroduces it.
+ */
+declare function sendError(res: EnvelopeResponse, status: number, code: ErrorCode, message: string, extra?: Pick<ApiError, 'category' | 'httpStatus' | 'details' | 'requestId'>): void;
+
 interface IKernel {
     ql?: any;
     start(): Promise<void>;
@@ -214,4 +629,4 @@ interface RuntimePlugin {
     onStart?: (ctx: RuntimeContext) => void | Promise<void>;
 }
 
-export { type IKernel, type RuntimeContext, type RuntimePlugin, _resetEnvDeprecationWarnings, isMcpServerEnabled, isModuleNotFoundError, readEnvWithDeprecation, resolveAllowDegradedTenancy, resolveMcpStdioAutoStart, resolveMultiOrgEnabled, resolveOrgLimit, resolveSandboxTimeoutMs, resolveSearchPinyinEnabled };
+export { type EnvelopeResponse, type IKernel, INTERNAL_ERROR_MESSAGE, type KeysetPageQuery, type KeysetWalk, type KeysetWalkOptions, type RuntimeContext, type RuntimePlugin, _resetEnvDeprecationWarnings, collectConfiguredLocales, emitDegradedBootBanner, isMcpServerEnabled, isModuleNotFoundError, keysetWalk, looksLikeInternalErrorLeak, readEnvWithDeprecation, resolveAllowDegradedTenancy, resolveAllowDevPlugin, resolveAllowDriverConnectFailure, resolveMcpStdioAutoStart, resolveMultiOrgEnabled, resolveOrgLimit, resolveSandboxTimeoutMs, resolveSearchPinyinEnabled, resolveTenancyPosture, sendError, sendOk, stampSearchPinyinEnabled };