@tier0/sdk-v2 0.0.0-stage → 0.2.1

package/dist/esm/controls.d.ts

@@ -0,0 +1,93 @@
+import { type HttpClient, type ClientConfig } from './openapi/client.js';
+import { type CloudTransportConfig } from './cloud-transport.js';
+/** Cloud Control contracts are independent of generated OpenAPI / Enterprise flow types. */
+export type ControlJSON = null | boolean | number | string | ControlJSON[] | {
+    [key: string]: ControlJSON;
+};
+export interface PublicControl {
+    code: string;
+    name: string;
+    description: string;
+    contractVersion: string;
+    inputSchema: Record<string, ControlJSON>;
+    outputSchema: Record<string, ControlJSON>;
+    sideEffect: 'read' | 'write';
+    idempotency: 'none' | 'optional' | 'required';
+    timeoutMs: number;
+    status: string;
+}
+export interface ControlDiscoverOptions {
+    page?: number;
+    size?: number;
+    search?: string;
+}
+export interface ControlDiscoverResponse {
+    total: number;
+    list: PublicControl[];
+}
+/** Shared HTTP settings; UNS v2 options never affect Control execution or headers. */
+export interface ControlTransportConfig extends CloudTransportConfig {
+}
+export interface CloudClientConfig extends ClientConfig, ControlTransportConfig {
+}
+export declare const DEFAULT_CONTROL_TRANSPORT_TIMEOUT_MS = 60000;
+export interface ControlInvokeOptions {
+    /** Stable caller-owned key for one business intent, at most 128 UTF-8 bytes. Never generated or retried by the SDK. */
+    idempotencyKey?: string;
+}
+export interface ControlInvokeResponse<Result = ControlJSON> {
+    code: string;
+    contractVersion: string;
+    result: Result;
+    runID: string;
+    status: string;
+    /** True only when the server explicitly reports an idempotent replay. */
+    replayed: boolean;
+}
+export interface ControlErrorInfo {
+    /** HTTP status, absent when no HTTP response was received. */
+    status?: number;
+    /** Gateway string errorCode, or an SDK-local CONTROL_* transport/protocol code. */
+    errorCode: string;
+    runID?: string;
+    contractVersion?: string;
+    runStatus?: string;
+    replayed?: boolean;
+}
+/** No Control error is automatically retried, including authentication failures. */
+export declare class ControlError extends Error {
+    readonly status?: number;
+    readonly errorCode: string;
+    readonly runID?: string;
+    readonly contractVersion?: string;
+    readonly runStatus?: string;
+    readonly replayed?: boolean;
+    readonly retryable = false;
+    constructor(message: string, info: ControlErrorInfo);
+}
+/** Execution may have happened. Reconcile run information; any deliberate replay must reuse the same key. */
+export declare class ControlResultUnknownError extends ControlError {
+    readonly outcomeUnknown = true;
+    constructor(info: ControlErrorInfo);
+}
+export interface ControlHandle<Input = ControlJSON, Result = ControlJSON> {
+    describe(): Promise<PublicControl>;
+    /**
+     * One POST only. Input is opaque business JSON, including fields named streamId,
+     * entryId, deploymentVersion or timeoutMs. Only the server chooses binding/version/timeout.
+     * Generic types are caller assertions; the server validates the contract schemas.
+     */
+    invoke(input: Input, options?: ControlInvokeOptions): Promise<ControlInvokeResponse<Result>>;
+}
+export declare class ControlsClient {
+    private readonly transport;
+    constructor(resolveClient?: () => HttpClient, config?: ControlTransportConfig);
+    private post;
+    /** Discover visible contracts; defaults and authorization are resolved by the server. */
+    discover(options?: ControlDiscoverOptions): Promise<ControlDiscoverResponse>;
+    use<Input = ControlJSON, Result = ControlJSON>(selector: {
+        code: string;
+    }): ControlHandle<Input, Result>;
+}
+/** Uses configureClient()/TIER0_API_HOST/TIER0_API_KEY, resolved for every call. */
+export declare const controls: ControlsClient;

package/dist/esm/controls.js

@@ -0,0 +1,163 @@
+import { getClient } from './openapi/client.js';
+import { CloudTransport, CloudTransportError, DEFAULT_CLOUD_TRANSPORT_TIMEOUT_MS } from './cloud-transport.js';
+export const DEFAULT_CONTROL_TRANSPORT_TIMEOUT_MS = DEFAULT_CLOUD_TRANSPORT_TIMEOUT_MS;
+/** No Control error is automatically retried, including authentication failures. */
+export class ControlError extends Error {
+    status;
+    errorCode;
+    runID;
+    contractVersion;
+    runStatus;
+    replayed;
+    retryable = false;
+    constructor(message, info) {
+        super(message);
+        this.name = 'ControlError';
+        this.status = info.status;
+        this.errorCode = info.errorCode;
+        this.runID = info.runID;
+        this.contractVersion = info.contractVersion;
+        this.runStatus = info.runStatus;
+        this.replayed = info.replayed;
+    }
+}
+/** Execution may have happened. Reconcile run information; any deliberate replay must reuse the same key. */
+export class ControlResultUnknownError extends ControlError {
+    outcomeUnknown = true;
+    constructor(info) {
+        super('Control result is unknown; execution may have occurred. Do not automatically retry.', info);
+        this.name = 'ControlResultUnknownError';
+    }
+}
+function record(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function keys(value, allowed) {
+    if (!record(value) || Reflect.ownKeys(value).some(key => typeof key !== 'string' || !allowed.includes(key))) {
+        throw new TypeError('Tier0 SDK: unsupported Control option.');
+    }
+}
+function json(value, seen = new Set()) {
+    if (value === null || typeof value === 'string' || typeof value === 'boolean')
+        return true;
+    if (typeof value === 'number')
+        return Number.isFinite(value);
+    if (typeof value !== 'object' || seen.has(value))
+        return false;
+    if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {
+        return false;
+    }
+    seen.add(value);
+    const valid = (Array.isArray(value) ? Array.from(value) : Object.values(value)).every(item => json(item, seen));
+    seen.delete(value);
+    return valid;
+}
+function definition(value) {
+    if (!record(value))
+        return false;
+    return ['code', 'name', 'description', 'contractVersion', 'status'].every(key => typeof value[key] === 'string') &&
+        value.code !== '' && value.contractVersion !== '' && record(value.inputSchema) && record(value.outputSchema) &&
+        ['read', 'write'].includes(value.sideEffect) &&
+        ['none', 'optional', 'required'].includes(value.idempotency) &&
+        typeof value.timeoutMs === 'number' && Number.isSafeInteger(value.timeoutMs) && value.timeoutMs > 0;
+}
+function runInfo(value) {
+    if (!record(value))
+        return {};
+    return {
+        runID: typeof value.runID === 'string' ? value.runID : undefined,
+        contractVersion: typeof value.contractVersion === 'string' ? value.contractVersion : undefined,
+        runStatus: typeof value.status === 'string' ? value.status : undefined,
+        replayed: typeof value.replayed === 'boolean' ? value.replayed : undefined,
+    };
+}
+export class ControlsClient {
+    transport;
+    constructor(resolveClient = getClient, config = {}) {
+        this.transport = new CloudTransport(resolveClient, config);
+    }
+    async post(path, body, invoked) {
+        let response;
+        try {
+            response = await this.transport.post(path, body);
+        }
+        catch (error) {
+            if (!(error instanceof CloudTransportError))
+                throw error;
+            const info = { status: error.status, errorCode: `CONTROL_${error.kind}` };
+            if (invoked)
+                throw new ControlResultUnknownError(info);
+            const message = error.kind === 'TRANSPORT_TIMEOUT' ? 'Control HTTP transport deadline exceeded.' :
+                error.kind === 'PROTOCOL_ERROR' ? 'Invalid Control response.' : 'Control transport failed.';
+            throw new ControlError(message, info);
+        }
+        const { value, status, ok } = response;
+        if (!ok) {
+            const error = record(value) ? value : {};
+            const valid = typeof error.errorCode === 'string' && typeof error.message === 'string';
+            const info = {
+                ...runInfo(value), status,
+                errorCode: valid ? error.errorCode : 'CONTROL_PROTOCOL_ERROR',
+            };
+            if (info.errorCode === 'CONTROL_RESULT_UNKNOWN' || (invoked && !valid)) {
+                throw new ControlResultUnknownError(info);
+            }
+            throw new ControlError(valid ? error.message : 'Invalid Control error response.', info);
+        }
+        return { value, status };
+    }
+    /** Discover visible contracts; defaults and authorization are resolved by the server. */
+    async discover(options = {}) {
+        keys(options, ['page', 'size', 'search']);
+        if ((options.page !== undefined && (!Number.isSafeInteger(options.page) || options.page < 1)) ||
+            (options.size !== undefined && (!Number.isSafeInteger(options.size) || options.size < 1 || options.size > 200)) ||
+            (options.search !== undefined && typeof options.search !== 'string')) {
+            throw new TypeError('Tier0 SDK: invalid Control discovery options.');
+        }
+        const { value, status } = await this.post('/openapi/v1/controls/discover', options, false);
+        if (!record(value) || !Number.isSafeInteger(value.total) || value.total < 0 ||
+            !Array.isArray(value.list) || !value.list.every(definition)) {
+            throw new ControlError('Invalid Control discovery response.', { status, errorCode: 'CONTROL_PROTOCOL_ERROR' });
+        }
+        return value;
+    }
+    use(selector) {
+        keys(selector, ['code']);
+        const code = selector.code;
+        if (typeof code !== 'string' || code.length > 128 || !/^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/.test(code)) {
+            throw new TypeError('Tier0 SDK: invalid Control code.');
+        }
+        const path = `/openapi/v1/controls/${encodeURIComponent(code)}`;
+        return {
+            describe: async () => {
+                const { value, status } = await this.post(`${path}/describe`, {}, false);
+                if (!definition(value) || value.code !== code) {
+                    throw new ControlError('Invalid Control description.', { status, errorCode: 'CONTROL_PROTOCOL_ERROR' });
+                }
+                return value;
+            },
+            invoke: async (input, options = {}) => {
+                keys(options, ['idempotencyKey']);
+                const key = options.idempotencyKey;
+                if (key !== undefined && (typeof key !== 'string' || !key || key.trim() !== key || new TextEncoder().encode(key).length > 128)) {
+                    throw new TypeError('Tier0 SDK: invalid Control idempotency key.');
+                }
+                if (!json(input))
+                    throw new TypeError('Tier0 SDK: Control input must be JSON.');
+                const { value, status } = await this.post(`${path}/invoke`, {
+                    input, ...(key === undefined ? {} : { idempotencyKey: key }),
+                }, true);
+                if (!record(value) || value.code !== code || typeof value.contractVersion !== 'string' || !value.contractVersion ||
+                    !Object.prototype.hasOwnProperty.call(value, 'result') || typeof value.runID !== 'string' || !value.runID ||
+                    typeof value.status !== 'string' || !value.status || ['accepted', 'queued', 'pending', 'running'].includes(value.status) ||
+                    typeof value.replayed !== 'boolean') {
+                    throw new ControlResultUnknownError({ ...runInfo(value), status, errorCode: 'CONTROL_PROTOCOL_ERROR' });
+                }
+                return value;
+            },
+        };
+    }
+}
+/** Uses configureClient()/TIER0_API_HOST/TIER0_API_KEY, resolved for every call. */
+export const controls = new ControlsClient();
+//# sourceMappingURL=controls.js.map

package/dist/esm/controls.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"controls.js","sourceRoot":"","sources":["../../src/controls.ts"],"names":[],"mappings":"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","sourcesContent":["import { getClient, type HttpClient, type ClientConfig } from './openapi/client.js';\nimport { CloudTransport, CloudTransportError, DEFAULT_CLOUD_TRANSPORT_TIMEOUT_MS, type CloudTransportConfig } from './cloud-transport.js';\n\n/** Cloud Control contracts are independent of generated OpenAPI / Enterprise flow types. */\nexport type ControlJSON = null | boolean | number | string | ControlJSON[] | { [key: string]: ControlJSON };\n\nexport interface PublicControl {\n  code: string;\n  name: string;\n  description: string;\n  contractVersion: string;\n  inputSchema: Record<string, ControlJSON>;\n  outputSchema: Record<string, ControlJSON>;\n  sideEffect: 'read' | 'write';\n  idempotency: 'none' | 'optional' | 'required';\n  timeoutMs: number;\n  status: string;\n}\n\nexport interface ControlDiscoverOptions {\n  page?: number;\n  size?: number;\n  search?: string;\n}\n\nexport interface ControlDiscoverResponse {\n  total: number;\n  list: PublicControl[];\n}\n\n/** Shared HTTP settings; UNS v2 options never affect Control execution or headers. */\nexport interface ControlTransportConfig extends CloudTransportConfig {}\n\nexport interface CloudClientConfig extends ClientConfig, ControlTransportConfig {}\n\nexport const DEFAULT_CONTROL_TRANSPORT_TIMEOUT_MS = DEFAULT_CLOUD_TRANSPORT_TIMEOUT_MS;\n\nexport interface ControlInvokeOptions {\n  /** Stable caller-owned key for one business intent, at most 128 UTF-8 bytes. Never generated or retried by the SDK. */\n  idempotencyKey?: string;\n}\n\nexport interface ControlInvokeResponse<Result = ControlJSON> {\n  code: string;\n  contractVersion: string;\n  result: Result;\n  runID: string;\n  status: string;\n  /** True only when the server explicitly reports an idempotent replay. */\n  replayed: boolean;\n}\n\nexport interface ControlErrorInfo {\n  /** HTTP status, absent when no HTTP response was received. */\n  status?: number;\n  /** Gateway string errorCode, or an SDK-local CONTROL_* transport/protocol code. */\n  errorCode: string;\n  runID?: string;\n  contractVersion?: string;\n  runStatus?: string;\n  replayed?: boolean;\n}\n\n/** No Control error is automatically retried, including authentication failures. */\nexport class ControlError extends Error {\n  readonly status?: number;\n  readonly errorCode: string;\n  readonly runID?: string;\n  readonly contractVersion?: string;\n  readonly runStatus?: string;\n  readonly replayed?: boolean;\n  readonly retryable = false;\n\n  constructor(message: string, info: ControlErrorInfo) {\n    super(message);\n    this.name = 'ControlError';\n    this.status = info.status;\n    this.errorCode = info.errorCode;\n    this.runID = info.runID;\n    this.contractVersion = info.contractVersion;\n    this.runStatus = info.runStatus;\n    this.replayed = info.replayed;\n  }\n}\n\n/** Execution may have happened. Reconcile run information; any deliberate replay must reuse the same key. */\nexport class ControlResultUnknownError extends ControlError {\n  readonly outcomeUnknown = true;\n\n  constructor(info: ControlErrorInfo) {\n    super('Control result is unknown; execution may have occurred. Do not automatically retry.', info);\n    this.name = 'ControlResultUnknownError';\n  }\n}\n\nfunction record(value: unknown): value is Record<string, unknown> {\n  return value !== null && typeof value === 'object' && !Array.isArray(value);\n}\n\nfunction keys(value: unknown, allowed: string[]): void {\n  if (!record(value) || Reflect.ownKeys(value).some(key => typeof key !== 'string' || !allowed.includes(key))) {\n    throw new TypeError('Tier0 SDK: unsupported Control option.');\n  }\n}\n\nfunction json(value: unknown, seen = new Set<unknown>()): boolean {\n  if (value === null || typeof value === 'string' || typeof value === 'boolean') return true;\n  if (typeof value === 'number') return Number.isFinite(value);\n  if (typeof value !== 'object' || seen.has(value)) return false;\n  if (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) {\n    return false;\n  }\n  seen.add(value);\n  const valid = (Array.isArray(value) ? Array.from(value) : Object.values(value)).every(item => json(item, seen));\n  seen.delete(value);\n  return valid;\n}\n\nfunction definition(value: unknown): value is PublicControl {\n  if (!record(value)) return false;\n  return ['code', 'name', 'description', 'contractVersion', 'status'].every(key => typeof value[key] === 'string') &&\n    value.code !== '' && value.contractVersion !== '' && record(value.inputSchema) && record(value.outputSchema) &&\n    ['read', 'write'].includes(value.sideEffect as string) &&\n    ['none', 'optional', 'required'].includes(value.idempotency as string) &&\n    typeof value.timeoutMs === 'number' && Number.isSafeInteger(value.timeoutMs) && value.timeoutMs > 0;\n}\n\nfunction runInfo(value: unknown): Partial<ControlErrorInfo> {\n  if (!record(value)) return {};\n  return {\n    runID: typeof value.runID === 'string' ? value.runID : undefined,\n    contractVersion: typeof value.contractVersion === 'string' ? value.contractVersion : undefined,\n    runStatus: typeof value.status === 'string' ? value.status : undefined,\n    replayed: typeof value.replayed === 'boolean' ? value.replayed : undefined,\n  };\n}\n\nexport interface ControlHandle<Input = ControlJSON, Result = ControlJSON> {\n  describe(): Promise<PublicControl>;\n  /**\n   * One POST only. Input is opaque business JSON, including fields named streamId,\n   * entryId, deploymentVersion or timeoutMs. Only the server chooses binding/version/timeout.\n   * Generic types are caller assertions; the server validates the contract schemas.\n   */\n  invoke(input: Input, options?: ControlInvokeOptions): Promise<ControlInvokeResponse<Result>>;\n}\n\nexport class ControlsClient {\n  private readonly transport: CloudTransport;\n\n  constructor(resolveClient: () => HttpClient = getClient, config: ControlTransportConfig = {}) {\n    this.transport = new CloudTransport(resolveClient, config);\n  }\n\n  private async post(path: string, body: unknown, invoked: boolean): Promise<{ value: unknown; status: number }> {\n    let response: Awaited<ReturnType<CloudTransport['post']>>;\n    try {\n      response = await this.transport.post(path, body);\n    } catch (error) {\n      if (!(error instanceof CloudTransportError)) throw error;\n      const info = { status: error.status, errorCode: `CONTROL_${error.kind}` };\n      if (invoked) throw new ControlResultUnknownError(info);\n      const message = error.kind === 'TRANSPORT_TIMEOUT' ? 'Control HTTP transport deadline exceeded.' :\n        error.kind === 'PROTOCOL_ERROR' ? 'Invalid Control response.' : 'Control transport failed.';\n      throw new ControlError(message, info);\n    }\n    const { value, status, ok } = response;\n    if (!ok) {\n      const error = record(value) ? value : {};\n      const valid = typeof error.errorCode === 'string' && typeof error.message === 'string';\n      const info: ControlErrorInfo = {\n        ...runInfo(value), status,\n        errorCode: valid ? error.errorCode as string : 'CONTROL_PROTOCOL_ERROR',\n      };\n      if (info.errorCode === 'CONTROL_RESULT_UNKNOWN' || (invoked && !valid)) {\n        throw new ControlResultUnknownError(info);\n      }\n      throw new ControlError(valid ? error.message as string : 'Invalid Control error response.', info);\n    }\n    return { value, status };\n  }\n\n  /** Discover visible contracts; defaults and authorization are resolved by the server. */\n  async discover(options: ControlDiscoverOptions = {}): Promise<ControlDiscoverResponse> {\n    keys(options, ['page', 'size', 'search']);\n    if ((options.page !== undefined && (!Number.isSafeInteger(options.page) || options.page < 1)) ||\n        (options.size !== undefined && (!Number.isSafeInteger(options.size) || options.size < 1 || options.size > 200)) ||\n        (options.search !== undefined && typeof options.search !== 'string')) {\n      throw new TypeError('Tier0 SDK: invalid Control discovery options.');\n    }\n    const { value, status } = await this.post('/openapi/v1/controls/discover', options, false);\n    if (!record(value) || !Number.isSafeInteger(value.total) || (value.total as number) < 0 ||\n        !Array.isArray(value.list) || !value.list.every(definition)) {\n      throw new ControlError('Invalid Control discovery response.', { status, errorCode: 'CONTROL_PROTOCOL_ERROR' });\n    }\n    return value as unknown as ControlDiscoverResponse;\n  }\n\n  use<Input = ControlJSON, Result = ControlJSON>(selector: { code: string }): ControlHandle<Input, Result> {\n    keys(selector, ['code']);\n    const code = selector.code;\n    if (typeof code !== 'string' || code.length > 128 || !/^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/.test(code)) {\n      throw new TypeError('Tier0 SDK: invalid Control code.');\n    }\n    const path = `/openapi/v1/controls/${encodeURIComponent(code)}`;\n    return {\n      describe: async () => {\n        const { value, status } = await this.post(`${path}/describe`, {}, false);\n        if (!definition(value) || value.code !== code) {\n          throw new ControlError('Invalid Control description.', { status, errorCode: 'CONTROL_PROTOCOL_ERROR' });\n        }\n        return value;\n      },\n      invoke: async (input, options = {}) => {\n        keys(options, ['idempotencyKey']);\n        const key = options.idempotencyKey;\n        if (key !== undefined && (typeof key !== 'string' || !key || key.trim() !== key || new TextEncoder().encode(key).length > 128)) {\n          throw new TypeError('Tier0 SDK: invalid Control idempotency key.');\n        }\n        if (!json(input)) throw new TypeError('Tier0 SDK: Control input must be JSON.');\n        const { value, status } = await this.post(`${path}/invoke`, {\n          input, ...(key === undefined ? {} : { idempotencyKey: key }),\n        }, true);\n        if (!record(value) || value.code !== code || typeof value.contractVersion !== 'string' || !value.contractVersion ||\n            !Object.prototype.hasOwnProperty.call(value, 'result') || typeof value.runID !== 'string' || !value.runID ||\n            typeof value.status !== 'string' || !value.status || ['accepted', 'queued', 'pending', 'running'].includes(value.status) ||\n            typeof value.replayed !== 'boolean') {\n          throw new ControlResultUnknownError({ ...runInfo(value), status, errorCode: 'CONTROL_PROTOCOL_ERROR' });\n        }\n        return value as unknown as ControlInvokeResponse<Result>;\n      },\n    };\n  }\n}\n\n/** Uses configureClient()/TIER0_API_HOST/TIER0_API_KEY, resolved for every call. */\nexport const controls = new ControlsClient();\n"]}

package/dist/esm/data/bootstrap.d.ts

@@ -0,0 +1,70 @@
+import type { DataCall } from './call.js';
+import type { CollectionDefinition } from './define.js';
+import { DataError } from './error.js';
+export type DataEnvironment = 'preview' | 'deployed';
+export interface EnsureWarning {
+    code: string;
+    path?: string;
+    message?: string;
+}
+export interface EnsureNote {
+    path: string;
+    reason?: string;
+    message?: string;
+}
+export interface EnsureResult {
+    alias: string;
+    collectionId: string;
+    revision: number;
+    status: 'created' | 'unchanged' | 'widened';
+    ignored?: EnsureNote[];
+    warnings?: EnsureWarning[];
+    indexStatus?: unknown[];
+}
+export interface EnsureConflict {
+    alias: string;
+    collectionId?: string;
+    path?: string;
+    reason?: string;
+    current?: string;
+    declared?: string;
+}
+export interface EnsureState {
+    appId?: string;
+    results: EnsureResult[];
+    /** Lower-cased alias → collection ID. */
+    collectionIds: Map<string, string>;
+    /** Declarations that conflicted in a deployment (served with their existing ID, if any). */
+    conflicts: EnsureConflict[];
+}
+export interface Logger {
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+export interface BootstrapConfig {
+    call: DataCall;
+    collections: readonly CollectionDefinition[];
+    environment: DataEnvironment;
+    logger: Logger;
+}
+/** Wait before replaying seed chunk attempt n+1: n × this. */
+export declare const SEED_RETRY_MS = 1000;
+/** At most one self-healing rebuild per client in this window. */
+export declare const REBUILD_INTERVAL_MS = 30000;
+/**
+ * Whether a record call failed because the collection ID it used is gone or
+ * no longer granted, by UNS's stable `data.reason` code. Archive and Preview
+ * purge also remove the App grant, so most stale IDs answer
+ * COLLECTION_NOT_GRANTED or COLLECTION_NOT_FOUND. APP_PERMISSION_MISSING (the
+ * key lacks e.g. `uns.delete`) and APP_GRANT_REVOKED are not stale IDs.
+ */
+export declare function isStaleCollectionError(error: unknown): boolean;
+export declare function createBootstrap(config: BootstrapConfig): {
+    ensure: () => Promise<EnsureState>;
+    resolve: (definition: CollectionDefinition) => Promise<string>;
+    recover: <R>(fn: () => Promise<R>, options?: {
+        retry?: boolean;
+    }) => Promise<R>;
+    rebuild: (before: EnsureState, cause: DataError) => Promise<boolean>;
+};

package/dist/esm/data/bootstrap.js

@@ -0,0 +1,286 @@
+/**
+ * First-access bootstrap: one batched `ensure` of every declared collection.
+ *
+ * - ensure only creates or widens; storage never narrows from here, so old
+ *   and new code may cold-start in any order.
+ * - The result is memoized per client, i.e. per server process; a client
+ *   built from edited declarations ensures again.
+ *   Failures are not memoized: a later call retries (an imported App may
+ *   answer "hosted App is not ready").
+ * - Seed documents are inserted only for collections ensure reports as
+ *   `created`: fixed `_id`s, atomic chunks of 200 with a stable idempotency
+ *   key per chunk, so a failed chunk (outcome unknown, or marked safe to
+ *   resend) is replayed after a short wait instead of duplicated. Seed writes
+ *   never carry a data subject.
+ * - Preview throws on SCHEMA_CONFLICT and warnings so the worker sees them;
+ *   a deployment logs them and keeps serving with the IDs it has.
+ * - Self-healing: a Preview reset hard-deletes collections, and a worker or
+ *   admin may archive one, while this process still holds the old IDs. A
+ *   record call that fails with `data.reason` COLLECTION_NOT_FOUND or
+ *   COLLECTION_NOT_GRANTED drops the memo, ensures again (seeding what is created)
+ *   and retries the call once, but only when a collection ID actually
+ *   changed. Rebuilds are limited to one per REBUILD_INTERVAL_MS per client;
+ *   APP_GRANT_REVOKED is never retried (ensure itself reports it).
+ * - `ignored` notes never fail a request. ensure never writes annotations, so
+ *   an edited `.describe()` or collection description comes back as
+ *   ANNOTATION_NOT_APPLIED; it is logged as a warning pointing at
+ *   schema:replace, which is the only way to change stored annotations.
+ */
+import { createHash } from 'node:crypto';
+import { MAX_ATOMIC_ITEMS } from './collection.js';
+import { ACCESS_REASONS, DataError } from './error.js';
+import { compileCollection, validateDocument } from './schema.js';
+const SEED_ATTEMPTS = 3;
+/** Wait before replaying seed chunk attempt n+1: n × this. */
+export const SEED_RETRY_MS = 1_000;
+/** At most one self-healing rebuild per client in this window. */
+export const REBUILD_INTERVAL_MS = 30_000;
+/**
+ * Whether a record call failed because the collection ID it used is gone or
+ * no longer granted, by UNS's stable `data.reason` code. Archive and Preview
+ * purge also remove the App grant, so most stale IDs answer
+ * COLLECTION_NOT_GRANTED or COLLECTION_NOT_FOUND. APP_PERMISSION_MISSING (the
+ * key lacks e.g. `uns.delete`) and APP_GRANT_REVOKED are not stale IDs.
+ */
+export function isStaleCollectionError(error) {
+    return (error instanceof DataError &&
+        (error.reason === ACCESS_REASONS.notGranted || error.reason === ACCESS_REASONS.notFound));
+}
+function sameCollectionIds(a, b) {
+    if (a.collectionIds.size !== b.collectionIds.size)
+        return false;
+    for (const [alias, id] of a.collectionIds) {
+        if (b.collectionIds.get(alias) !== id)
+            return false;
+    }
+    return true;
+}
+/** Idempotency key of one seed chunk (UNS keys are at most 96 characters). */
+function seedChunkKey(collectionId, chunk) {
+    return `seed-${createHash('sha256').update(collectionId).digest('hex').slice(0, 40)}-${chunk}`;
+}
+/** What to do about each SCHEMA_CONFLICT reason (CloudAppCollectionConflict.reason). */
+const CONFLICT_HINTS = {
+    TYPE_CONFLICT: "a field's type cannot change; use a new field name and backfill with updateMany",
+    LIMIT_EXCEEDED: 'the joined schema exceeds a UNS limit (depth, properties, enum values or indexes); split the structure',
+    OPEN_OBJECT: 'every object must be closed; declare it with z.object',
+    ALIAS_IN_USE: 'the alias belongs to another collection; pick another alias',
+    NAME_IN_USE: 'the name belongs to another collection; pick another alias',
+    INVALID_INDEX: 'fix the index declaration',
+    JOIN_UNSUPPORTED: 'the stored schema holds a node the declaration cannot widen (e.g. enum values outside its range); repair it with schema:replace via the tier0 MCP',
+    DATA_RULE_FIELD: 'an employee data rule (ownerField / stateField) uses this field; keep it required with the same type, or ask a workspace admin to change the rule',
+};
+function describeConflicts(conflicts) {
+    return conflicts
+        .map((conflict) => {
+        const where = `${conflict.alias}${conflict.path ? `.${conflict.path}` : ''}`;
+        const types = conflict.current || conflict.declared ? ` (stored ${conflict.current ?? '?'}, declared ${conflict.declared ?? '?'})` : '';
+        const hint = conflict.reason && CONFLICT_HINTS[conflict.reason] ? ` — ${CONFLICT_HINTS[conflict.reason]}` : '';
+        return `  - ${where}: ${conflict.reason ?? 'conflict'}${types}${hint}`;
+    })
+        .join('\n');
+}
+function notePath(alias, note) {
+    return note.path ? `${alias}.${note.path}` : alias;
+}
+function describeWarnings(results) {
+    return results
+        .flatMap((result) => (result.warnings ?? []).map((warning) => `  - ${result.alias}${warning.path ? `.${warning.path}` : ''}: ${warning.code}${warning.message ? ` — ${warning.message}` : ''}`))
+        .join('\n');
+}
+export function createBootstrap(config) {
+    const { call, collections, environment, logger } = config;
+    let pending = null;
+    let lastRebuild = Number.NEGATIVE_INFINITY;
+    async function requestEnsure(items) {
+        // ensure is App-level work: it never carries the employee data subject.
+        return call('appCollectionsEnsure', { collections: items });
+    }
+    async function insertSeedChunk(collectionId, chunk, documents) {
+        for (let attempt = 1;; attempt += 1) {
+            try {
+                await call('recordInsertMany', {
+                    collectionId,
+                    documents,
+                    ordered: true,
+                    atomic: true,
+                    idempotencyKey: seedChunkKey(collectionId, chunk),
+                });
+                return;
+            }
+            catch (error) {
+                // The chunk key is stable, so replaying is safe even when the outcome is unknown: a chunk
+                // that did commit replays its receipt. Wait first, so a write still running can finish.
+                if (!(error instanceof DataError) || !(error.outcomeUnknown || error.retry.safe) || attempt >= SEED_ATTEMPTS)
+                    throw error;
+                await new Promise((resolve) => setTimeout(resolve, SEED_RETRY_MS * attempt));
+            }
+        }
+    }
+    async function writeSeeds(results) {
+        for (const result of results) {
+            if (result.status !== 'created')
+                continue;
+            const definition = collections.find((candidate) => candidate.alias.toLowerCase() === result.alias.toLowerCase());
+            const seed = definition?.seed;
+            if (!definition || !seed || seed.length === 0)
+                continue;
+            try {
+                const documents = seed.map((document) => {
+                    const { id, data } = validateDocument(definition, document);
+                    return { id, data };
+                });
+                for (let start = 0; start < documents.length; start += MAX_ATOMIC_ITEMS) {
+                    await insertSeedChunk(result.collectionId, start / MAX_ATOMIC_ITEMS, documents.slice(start, start + MAX_ATOMIC_ITEMS));
+                }
+                logger.info(`[data] seeded ${documents.length} record(s) into "${result.alias}"`);
+            }
+            catch (error) {
+                // The collection exists now; a later ensure reports "unchanged" and
+                // never re-seeds, so the failure must be visible in the server log.
+                logger.error(`[data] seed for new collection "${result.alias}" failed; it keeps the chunks written so far:`, error);
+            }
+        }
+    }
+    async function run(payload) {
+        const conflicts = [];
+        let remaining = payload;
+        let response = { results: [] };
+        while (remaining.length > 0) {
+            try {
+                response = await requestEnsure(remaining);
+                break;
+            }
+            catch (error) {
+                if (!(error instanceof DataError) || error.code !== 'SCHEMA_CONFLICT')
+                    throw error;
+                const reported = Array.isArray(error.details.conflicts) ? error.details.conflicts : [];
+                const summary = describeConflicts(reported);
+                if (environment === 'preview') {
+                    throw new DataError({
+                        message: `The collection declarations conflict with the stored collection schemas; nothing was changed:\n${summary}`,
+                        status: 409,
+                        code: 'SCHEMA_CONFLICT',
+                        upstreamStatus: error.upstreamStatus,
+                        requestId: error.requestId,
+                        execution: error.execution,
+                        attempts: error.attempts,
+                        details: error.details,
+                    });
+                }
+                // A deployment keeps serving: drop the conflicting declarations (the
+                // whole batch was rejected) and ensure the rest again.
+                const conflicting = new Set(reported.map((conflict) => conflict.alias.toLowerCase()));
+                const next = remaining.filter((item) => !conflicting.has(item.alias.toLowerCase()));
+                if (next.length === remaining.length)
+                    throw error;
+                logger.error(`[data] ensure: declarations conflict with stored schemas; serving them unchanged:\n${summary}`);
+                conflicts.push(...reported);
+                remaining = next;
+            }
+        }
+        const results = response.results ?? [];
+        const collectionIds = new Map();
+        for (const conflict of conflicts) {
+            if (conflict.collectionId)
+                collectionIds.set(conflict.alias.toLowerCase(), conflict.collectionId);
+        }
+        for (const result of results) {
+            collectionIds.set(result.alias.toLowerCase(), result.collectionId);
+            const notes = result.ignored ?? [];
+            const annotations = notes.filter((note) => note.reason === 'ANNOTATION_NOT_APPLIED');
+            const wider = notes.filter((note) => note.reason !== 'ANNOTATION_NOT_APPLIED');
+            if (wider.length > 0) {
+                logger.info(`[data] "${result.alias}" storage is wider than this declaration (or has retired parts); ignored: ` +
+                    wider.map((note) => `${note.path || '(root)'} ${note.reason ?? ''}`.trim()).join(', '));
+            }
+            if (annotations.length > 0) {
+                // A hint, not an error: storage keeps its annotations and serves as before.
+                logger.warn(`[data] ensure does not change stored titles/descriptions; not applied: ${annotations.map((note) => notePath(result.alias, note)).join(', ')}. ` +
+                    `Apply them with schema:replace via the tier0 MCP, using compileCollection(...) of the declaration as the body.`);
+            }
+        }
+        await writeSeeds(results);
+        const warnings = describeWarnings(results);
+        if (warnings) {
+            if (environment === 'preview') {
+                throw new DataError({
+                    message: `Collections were ensured with warnings:\n${warnings}\n` +
+                        'REQUIRED_NOT_ENFORCED: make the field optional again or narrow explicitly with schema:replace via the tier0 MCP. ' +
+                        'INDEX_BUILD_FAILED: fix the duplicate or invalid data, then the next ensure retries the index.',
+                    status: 500,
+                    code: 'SCHEMA_WARNINGS',
+                    // ensure did apply; only the warnings fail the Preview request.
+                    execution: 'committed',
+                    details: { results },
+                });
+            }
+            logger.warn(`[data] ensure warnings:\n${warnings}`);
+        }
+        return { appId: response.appId, results, collectionIds, conflicts };
+    }
+    /** Ensures every declaration once per client; a failure is forgotten so the next call retries. */
+    function ensure() {
+        pending ??= Promise.resolve()
+            .then(() => run(collections.map(compileCollection)))
+            .catch((error) => {
+            pending = null;
+            throw error;
+        });
+        return pending;
+    }
+    /**
+     * Re-ensures after `before` turned out stale. Joins a rebuild already in
+     * flight; otherwise rebuilds at most once per REBUILD_INTERVAL_MS. Resolves
+     * whether any collection ID changed; ensure errors (APP_GRANT_REVOKED, …)
+     * propagate.
+     */
+    async function rebuild(before, cause) {
+        const current = ensure();
+        const latest = await current;
+        if (latest !== before)
+            return !sameCollectionIds(before, latest);
+        if (pending !== current)
+            return !sameCollectionIds(before, await ensure());
+        const now = Date.now();
+        if (now - lastRebuild < REBUILD_INTERVAL_MS)
+            return false;
+        lastRebuild = now;
+        logger.warn(`[data] a collection ID is no longer usable (${cause.code}: ${cause.message}); ensuring collections again`);
+        pending = null;
+        return !sameCollectionIds(before, await ensure());
+    }
+    /**
+     * Runs one data call; when it fails on a stale collection ID, rebuilds and
+     * runs it once more if an ID changed. `retry: false` (calls continuing a
+     * cursor or resumeAfter token of the old collection) only rebuilds.
+     */
+    async function recover(fn, options = {}) {
+        const before = await ensure();
+        try {
+            return await fn();
+        }
+        catch (error) {
+            if (!isStaleCollectionError(error))
+                throw error;
+            const changed = await rebuild(before, error);
+            if (!changed || options.retry === false)
+                throw error;
+            return fn();
+        }
+    }
+    async function resolve(definition) {
+        const state = await ensure();
+        const id = state.collectionIds.get(definition.alias.toLowerCase());
+        if (!id) {
+            throw new DataError({
+                message: `Collection "${definition.alias}" is unavailable: ensure did not return it (see the server log).`,
+                status: 503,
+                code: 'COLLECTION_UNAVAILABLE',
+            });
+        }
+        return id;
+    }
+    return { ensure, resolve, recover, rebuild };
+}
+//# sourceMappingURL=bootstrap.js.map