@objectstack/types 17.0.0-rc.0 → 17.0.0-rc.2

package/dist/index.d.mts

@@ -1,4 +1,5 @@
 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
@@ -21,12 +22,21 @@ import { TenancyPosture } from '@objectstack/spec/security';
  * 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: `os serve`
- * swallows ALL of stdout while the kernel boots (its "boot-quiet" capture), and
- * `Logger` routes `warn` to stdout, so the one message that matters would be
- * invisible in exactly the situation it exists for. Writing to stderr as well
- * is the same belt-and-braces the kernel already uses for plugin startup
- * failures.
+ * 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
@@ -152,6 +162,23 @@ declare function resolveAllowDegradedTenancy(): boolean;
  * 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?".
  *
@@ -235,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).
@@ -284,7 +343,7 @@ declare function _resetEnvDeprecationWarnings(): void;
  *
  * ObjectStack has more than one HTTP boundary. `@objectstack/rest` guards the
  * REST data routes inside `mapDataError`; the dispatcher-plugin routes
- * (`/analytics`, `/packages`, `/i18n`, `/storage`, `/automation`, …) exit
+ * (`/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:
@@ -323,6 +382,100 @@ declare const INTERNAL_ERROR_MESSAGE = "Internal server error";
  */
 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
@@ -339,6 +492,129 @@ declare function looksLikeInternalErrorLeak(message: string | undefined | null):
  */
 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>;
@@ -353,4 +629,4 @@ interface RuntimePlugin {
     onStart?: (ctx: RuntimeContext) => void | Promise<void>;
 }
 
-export { type IKernel, INTERNAL_ERROR_MESSAGE, type RuntimeContext, type RuntimePlugin, _resetEnvDeprecationWarnings, emitDegradedBootBanner, isMcpServerEnabled, isModuleNotFoundError, looksLikeInternalErrorLeak, readEnvWithDeprecation, resolveAllowDegradedTenancy, resolveAllowDriverConnectFailure, resolveMcpStdioAutoStart, resolveMultiOrgEnabled, resolveOrgLimit, resolveSandboxTimeoutMs, resolveSearchPinyinEnabled, resolveTenancyPosture };
+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 };