@deepraxis/sdk 0.1.0-dev.95813a3 → 0.1.0-dev.a5cf3ce

package/dist/helpers/application-publish.d.ts

@@ -1,5 +1,5 @@
 import type { Praxis } from '../core/client.js';
-import type { ApplicationAssetsConfig, ApplicationBinding } from '../generated/types.gen.js';
+import type { ApplicationAssetsConfig, ApplicationBinding, ApplicationVersion } from '../generated/types.gen.js';
 export type AssetsConfig = ApplicationAssetsConfig;
 export interface PublishInput {
     /** 应用名；存在同名应用时复用。 */
@@ -20,16 +20,32 @@ export interface PublishInput {
     bindings?: ApplicationBinding[];
     /** 静态资源路由配置，原样传递。 */
     assets_config?: AssetsConfig;
+    /** Register an upload session to plan changes; do not upload content or publish. Requires an existing application. */
+    dryRun?: boolean;
+    /** Preserve current paths omitted from files. Defaults to false (whole-site replacement). */
+    keepExisting?: boolean;
     /** 是否等待部署完成，默认 true。 */
     wait?: boolean;
     /** 部署等待上限（毫秒），默认 120000。超时不会撤销部署。 */
     timeout_ms?: number;
 }
 export interface PublishResult {
+    /** True when a static-only publication matches the active version. */
+    unchanged?: boolean;
+    /** Current version when unchanged or planning an existing deployment. */
+    version?: ApplicationVersion;
+    /** dryRun compares against the active version; counts are distinct content hashes. */
+    plan?: {
+        added: string[];
+        changed: string[];
+        removed: string[];
+        upload_hashes: number;
+        existing_hashes: number;
+    };
     url: string;
     worker_id: string;
-    version_id: string;
-    deployment_id: string;
+    version_id: string | null;
+    deployment_id: string | null;
     status: string;
     created: boolean;
     /** 本次上传的不同内容 hash 数量。 */
@@ -37,5 +53,9 @@ export interface PublishResult {
     /** 服务端已存在的不同内容 hash 数量。 */
     reused: number;
 }
-/** Publish through the public SDK resources, including content-addressed incremental uploads. */
+/** Publish with whole-site replacement by default; keepExisting preserves omitted paths.
+ * dryRun registers an idempotent upload session (stores its manifest), but uploads no content and does not publish.
+ * The platform does not support gradual rollout. Roll back using workers.deployments.create with
+ * strategy: 'percentage', versions: [{ version_id: previousVersionId, percentage: 100 }], while artifacts are retained.
+ */
 export declare function publish(client: Pick<Praxis, 'application'>, input: PublishInput): Promise<PublishResult>;

package/dist/helpers/application-publish.js

@@ -8,8 +8,16 @@ function base64(bytes) {
     }
     return btoa(chunks.join(''));
 }
-/** Publish through the public SDK resources, including content-addressed incremental uploads. */
+/** Publish with whole-site replacement by default; keepExisting preserves omitted paths.
+ * dryRun registers an idempotent upload session (stores its manifest), but uploads no content and does not publish.
+ * The platform does not support gradual rollout. Roll back using workers.deployments.create with
+ * strategy: 'percentage', versions: [{ version_id: previousVersionId, percentage: 100 }], while artifacts are retained.
+ */
 export async function publish(client, input) {
+    const rolloutFields = ['gradual', 'gradualRollout', 'gradual_rollout', 'canary', 'rollout', 'percentage', 'percent', 'traffic', 'traffic_percentage', 'strategy', 'versions'];
+    if (Object.keys(input).some(key => rolloutFields.includes(key) || /percentage|percent|canary|gradual|rollout|灰度/i.test(key))) {
+        throw new PraxisError({ code: 'INVALID_PARAMS', message: '平台不支持灰度 (gradual rollout is not supported). Roll back with praxis.application.workers.deployments.create({ path: { worker_id }, body: { strategy: "percentage", versions: [{ version_id: previousVersionId, percentage: 100 }] } }); the previous version artifacts must still be retained.' });
+    }
     const timeout = input.timeout_ms ?? 120_000;
     if (!Number.isFinite(timeout) || timeout < 0)
         throw new RangeError('timeout_ms must be non-negative and finite');
@@ -21,7 +29,7 @@ export async function publish(client, input) {
     const files = Object.entries(input.files);
     if (files.length > 100_000)
         throw new PraxisError({ code: 'LIMIT_EXCEEDED', message: 'At most 100000 asset paths can be published' });
-    const manifest = {};
+    let manifest = {};
     const contents = new Map();
     for (const [path, content] of files) {
         const normalized = path.startsWith('/') ? path : `/${path}`;
@@ -44,9 +52,51 @@ export async function publish(client, input) {
         }
     }
     const created = !worker;
+    if (!worker && input.dryRun)
+        throw new PraxisError({ code: 'NOT_FOUND', message: '请先创建应用 (create the application before dryRun)' });
     worker ??= await workers.create({ body: { name: input.name, subdomain: { enabled: true } } });
     const path = { worker_id: worker.id };
+    let currentVersion;
+    let currentDeployment;
+    let previous = {};
+    if (worker.praxis?.current_deployment_id) {
+        currentDeployment = await workers.deployments.retrieve({ path: { ...path, deployment_id: worker.praxis.current_deployment_id } });
+        const active = currentDeployment.versions[0];
+        if (!active)
+            throw new PraxisError({ code: 'INVALID_RESPONSE', message: 'Current deployment has no version' });
+        currentVersion = await workers.versions.retrieve({ path: { ...path, version_id: active.version_id } });
+        previous = (await workers.versions.assets.retrieveManifest({ path: { ...path, version_id: active.version_id } })).manifest;
+    }
+    // Keep the stored path order: the service hashes JSON.stringify(manifest), including property order.
+    // Reordered input with identical paths must still hash to the active version's manifest_hash.
+    manifest = {
+        ...Object.fromEntries(Object.entries(previous).filter(([key]) => input.keepExisting || Object.hasOwn(manifest, key))),
+        ...manifest,
+    };
+    if (Object.keys(manifest).length > 100_000)
+        throw new PraxisError({ code: 'LIMIT_EXCEEDED', message: 'At most 100000 asset paths can be published' });
+    const added = Object.keys(manifest).filter(key => !Object.hasOwn(previous, key));
+    const changed = Object.keys(manifest).filter(key => previous[key] && (previous[key].hash !== manifest[key].hash || previous[key].size !== manifest[key].size));
+    const removed = Object.keys(previous).filter(key => !Object.hasOwn(manifest, key));
+    const digest = new Uint8Array(await crypto.subtle.digest('SHA-256', new TextEncoder().encode(JSON.stringify(manifest))));
+    const manifestHash = Array.from(digest, byte => byte.toString(16).padStart(2, '0')).join('');
+    const staticOnly = !['main', 'bindings', 'compatibility_date', 'compatibility_flags', 'assets_config'].some(key => Object.hasOwn(input, key));
+    const unchanged = staticOnly && !!currentVersion && manifestHash === currentVersion.praxis.assets_manifest?.manifest_hash;
+    const hashes = new Set(Object.values(manifest).map(entry => entry.hash));
+    const currentResult = { url: worker.subdomain.url, worker_id: worker.id, version_id: currentVersion?.id ?? null,
+        deployment_id: currentDeployment?.id ?? null, status: currentDeployment?.praxis.status ?? 'draft', created,
+        ...(currentVersion ? { version: currentVersion } : {}), unchanged, uploaded: 0, reused: hashes.size };
+    if (unchanged && !input.dryRun)
+        return currentResult;
+    // dryRun intentionally registers the content-addressed session manifest, but never uploads or publishes.
     const session = await workers.assetsUploadSession.create({ path, body: { manifest } });
+    if (input.dryRun) {
+        const missing = new Set(session.buckets.flat());
+        if ([...missing].some(hash => !hashes.has(hash)))
+            throw new PraxisError({ code: 'INVALID_RESPONSE', message: 'Upload session requested an unknown hash' });
+        return { ...currentResult, reused: hashes.size - missing.size,
+            plan: { added, changed, removed, upload_hashes: missing.size, existing_hashes: hashes.size - missing.size } };
+    }
     let jwt = session.buckets.length ? null : session.jwt;
     const uploaded = new Set();
     for (const bucket of session.buckets) {
@@ -112,5 +162,5 @@ export async function publish(client, input) {
     }
     return { url: worker.subdomain.url, worker_id: worker.id, version_id: result.version.id,
         deployment_id: deployment.id, status: deployment.praxis.status, created,
-        uploaded: uploaded.size, reused: contents.size - uploaded.size };
+        uploaded: uploaded.size, reused: hashes.size - uploaded.size };
 }

package/dist/helpers/database-count.d.ts

@@ -0,0 +1,17 @@
+import type { Transport } from '../core/transport.js';
+export interface CountInput {
+    /** Database ID from database list/create; not its display name. */
+    database_id: string;
+    /** Existing table name or ID from the database table APIs. */
+    table: string;
+    /** PostgREST query filters, as in databaseSelect; omitted means all rows. */
+    filters?: Record<string, string>;
+    /** exact counts within budget (default); filtered planned returns null; estimated may return null over budget. Unfiltered counts are exact in every mode. */
+    count?: 'exact' | 'planned' | 'estimated';
+}
+export interface CountResult {
+    /** Matching total, or null when the server reports an unknown total. */
+    count: number | null;
+}
+/** Count matching rows without retrieving row data. */
+export declare function count(transport: Pick<Transport, 'requestWithResponse'>, input: CountInput): Promise<CountResult>;

package/dist/helpers/database-count.js

@@ -0,0 +1,11 @@
+import { databaseHead } from "../generated/sdk.gen.js";
+/** Count matching rows without retrieving row data. */
+export async function count(transport, input) {
+    const { response } = await transport.requestWithResponse(databaseHead, {
+        path: { database_id: input.database_id, table: input.table },
+        query: input.filters,
+        headers: { Prefer: `count=${input.count ?? 'exact'}` },
+    });
+    const total = response.headers.get('Content-Range')?.split('/')[1];
+    return { count: total === undefined || total === '*' ? null : Number(total) };
+}

package/dist/index.d.ts

@@ -7,3 +7,5 @@ export { parseSSE } from './core/sse.js';
 export type { SSEEvent, SSEOptions } from './core/sse.js';
 export { publish } from './helpers/application-publish.js';
 export type { PublishInput, PublishResult, AssetsConfig } from './helpers/application-publish.js';
+export { count } from './helpers/database-count.js';
+export type { CountInput, CountResult } from './helpers/database-count.js';

package/dist/index.js

@@ -3,3 +3,4 @@ export { PraxisError, PraxisConnectionError, PraxisTimeoutError } from "./core/e
 export { Page } from "./core/pagination.js";
 export { parseSSE } from "./core/sse.js";
 export { publish } from "./helpers/application-publish.js";
+export { count } from "./helpers/database-count.js";

package/dist/operations.generated.d.ts

@@ -140,6 +140,12 @@ export declare const operations: readonly [{
             readonly type: "object";
             readonly required: false;
             readonly description: "Praxis extension: switchable model ids on /agent/v1 only. The default model must be included. When omitted, only the default model is selectable.";
+        }, {
+            readonly name: "preset";
+            readonly type: "string";
+            readonly enum: readonly ["minimal", "data-editor", "full"];
+            readonly required: false;
+            readonly description: "Optional tool preset. minimal enables read, glob, grep and ask_user_question; data-editor also enables write and edit; full uses the default toolset with always_allow. Explicit tools override matching preset entries. codemode requires bash and is absent from data-editor.";
         }];
     };
 }, {
@@ -268,6 +274,12 @@ export declare const operations: readonly [{
             readonly type: "object";
             readonly required: false;
             readonly description: "Praxis extension: switchable model ids on /agent/v1 only. The default model must be included. When omitted, only the default model is selectable.";
+        }, {
+            readonly name: "preset";
+            readonly type: "string";
+            readonly enum: readonly ["minimal", "data-editor", "full"];
+            readonly required: false;
+            readonly description: "Optional tool preset. minimal enables read, glob, grep and ask_user_question; data-editor also enables write and edit; full uses the default toolset with always_allow. Explicit tools override matching preset entries. codemode requires bash and is absent from data-editor.";
         }];
     };
 }, {
@@ -420,6 +432,20 @@ export declare const operations: readonly [{
         readonly sdkName: "external_user_id";
     }];
     readonly query: readonly [];
+}, {
+    readonly resource: "agent.agents.unarchive";
+    readonly method: "create";
+    readonly summary: "Unarchive Agent";
+    readonly description: "Restore an archived agent without creating a configuration version. Already active agents are unchanged. Missing or inaccessible agents return 404. Use the returned agent id to create new sessions.";
+    readonly http: "POST";
+    readonly path: "/agent/v1/agents/{agent_id}/unarchive";
+    readonly streaming: "no";
+    readonly pagination: false;
+    readonly pathParams: readonly [{
+        readonly name: "agent_id";
+        readonly sdkName: "agent_id";
+    }];
+    readonly query: readonly [];
 }, {
     readonly resource: "agent.agents.versions";
     readonly method: "list";
@@ -582,7 +608,7 @@ export declare const operations: readonly [{
     readonly resource: "agent.computers";
     readonly method: "connect";
     readonly summary: "Connect computer";
-    readonly description: "Resume the computer and issue a sandbox connection.\n\nOwn-face extension: Managed Agents has no persistent Computer connection. Returns the public SDK sandbox_id, envd_access_token and template_id, plus the machine tier the computer is on now (light or heavy) and the lease that keeps it there (lease_id, lease_expires_at; lease_id is null when no lease exists). Keep the lease while the connection stays open: renew it about every 20 seconds (POST .../leases/{lease_id}/renew) and release it on close (DELETE .../leases/{lease_id}). An unrenewed lease simply expires, and the full machine is reclaimed only after that. Archived computers remain accessible; foreign or absent computers return 404. Never cache credentials.";
+    readonly description: "Resume the computer and issue a sandbox connection.\n\nOwn-face extension: Managed Agents has no persistent Computer connection. Returns the public SDK sandbox_id, envd_access_token and template_id, plus the machine tier the computer is on now (light or heavy) and the lease that keeps it there (lease_id, lease_expires_at; lease_id is null when no lease exists). Keep the lease while the connection stays open: renew it about every 20 seconds (POST .../leases/{lease_id}/renew) and release it on close (DELETE .../leases/{lease_id}). An unrenewed lease simply expires, and the full machine is reclaimed only after that. Archived computers remain accessible; foreign or absent computers return 404. Never cache credentials.\n\nConnect to a computer with a caller-held lease. Omit the body or send {} to request light: the lightweight shell, or the heavy instance while it is running. Send {\"need\":\"heavy\"} to request full Linux for interactive programs; files are synchronized before the heavy connection is returned with tier heavy. Heavy running time counts toward the daily budget in seconds. Renew the lease while using the connection and release it with DELETE when finished. If the daily budget is exhausted, 429 COMPUTER_BUDGET_EXHAUSTED allows you to continue with need light.";
     readonly http: "POST";
     readonly path: "/agent/v1/computers/{computer_id}/connect";
     readonly streaming: "no";
@@ -592,6 +618,16 @@ export declare const operations: readonly [{
         readonly sdkName: "computer_id";
     }];
     readonly query: readonly [];
+    readonly body: {
+        readonly required: false;
+        readonly fields: readonly [{
+            readonly name: "need";
+            readonly type: "string";
+            readonly enum: readonly ["light", "heavy"];
+            readonly required: false;
+            readonly description: "Defaults to light. light uses the lightweight shell, or the heavy instance while it is running. heavy requests a full Linux computer for interactive programs; heavy running time counts toward the daily budget in seconds.";
+        }];
+    };
 }, {
     readonly resource: "agent.computers.files";
     readonly method: "list";
@@ -1485,6 +1521,20 @@ export declare const operations: readonly [{
             readonly description: "Praxis extension: explicit session thinking effort; null inherits the pinned agent default, then the model default. none disables thinking only when model.thinking.can_disable is true. Unsupported efforts return 400 invalid_request_error.";
         }];
     };
+}, {
+    readonly resource: "agent.sessions";
+    readonly method: "delete";
+    readonly summary: "Delete session";
+    readonly description: "Delete an idle or terminated session and its event history after saving a deletion snapshot. Supply the session id from creation or listing. Running sessions return 409 INVALID_STATE: interrupt first or wait until idle or terminated. Afterwards retrieval and event listing return 404 and lists omit the session. Example: DELETE /agent/v1/sessions/sesn_example.";
+    readonly http: "DELETE";
+    readonly path: "/agent/v1/sessions/{session_id}";
+    readonly streaming: "no";
+    readonly pagination: false;
+    readonly pathParams: readonly [{
+        readonly name: "session_id";
+        readonly sdkName: "session_id";
+    }];
+    readonly query: readonly [];
 }, {
     readonly resource: "agent.sessions";
     readonly method: "retrieve";
@@ -2694,6 +2744,23 @@ export declare const operations: readonly [{
         readonly sdkName: "version_id";
     }];
     readonly query: readonly [];
+}, {
+    readonly resource: "application.workers.versions.assets";
+    readonly method: "retrieveManifest";
+    readonly summary: "Get version asset manifest";
+    readonly description: "Read the retained asset paths, content hashes and byte sizes of a version for publication planning. This read creates no session or version. A version without assets returns an empty manifest; unavailable artifacts and foreign resources return 404.";
+    readonly http: "GET";
+    readonly path: "/application/v1/workers/{worker_id}/versions/{version_id}/assets/manifest";
+    readonly streaming: "no";
+    readonly pagination: false;
+    readonly pathParams: readonly [{
+        readonly name: "worker_id";
+        readonly sdkName: "worker_id";
+    }, {
+        readonly name: "version_id";
+        readonly sdkName: "version_id";
+    }];
+    readonly query: readonly [];
 }, {
     readonly resource: "automation.actions";
     readonly method: "list";
@@ -5435,7 +5502,7 @@ export declare const operations: readonly [{
         readonly name: "{column}";
         readonly type: "string";
         readonly required: false;
-        readonly description: "Horizontal filter: replace {column} with a field name or JSON path, e.g. title=eq.summary. Repeat for more columns. See the filter operator matrix.";
+        readonly description: "Horizontal filter: replace {column} with a field name or JSON path, e.g. title=eq.summary. Repeat for more columns. Supported operators: eq (equal), neq (not equal; ne is not supported), gt/gte/lt/lte (comparisons), like (case-sensitive text pattern), ilike (case-insensitive text pattern), in (membership), is (null/boolean test), cs (contains), cd (contained by), and ov (array overlap). For like/ilike, * or % matches any sequence and _ matches one character, e.g. title=ilike.*spring*; URL-encode a literal % as %25. Use days=in.(1,2,3), title=is.null, active=is.true or active=is.false; is.not_null and is.unknown are also accepted (unknown means null). Negate a condition with not., e.g. title=not.eq.draft. Multiple filters are ANDed; use or=(title.eq.a,title.eq.b), and=(days.gte.1,days.lte.3), not.or=(...) or not.and=(...), with nested and(...) and or(...) groups as needed. cs/cd accept JSON objects or arrays on JSON fields; cs also accepts a JSON scalar. For array values or multi-link fields, use cs.{a,b}, cd.{a,b} or ov.{a,b}. JSON paths use -> for JSON and ->> for text, e.g. attributes->>has_onsen=eq.true or attributes->tags=cs.[1,2]; chain -> segments and end with ->> for text. Dot paths such as attributes.has_onsen are unsupported. Full-text, regex, range operators and any/all modifiers are unsupported.";
     }, {
         readonly name: "and";
         readonly type: "string";
@@ -5475,7 +5542,7 @@ export declare const operations: readonly [{
         readonly name: "on_conflict";
         readonly type: "string";
         readonly required: false;
-        readonly description: "POST upsert: id or one unique field with resolution=merge-duplicates|ignore-duplicates. POST accepts an optional client id matching [A-Za-z0-9_-]{1,64}; omitted ids are generated. PATCH cannot change id.";
+        readonly description: "POST upsert: id or one unique field with resolution=merge-duplicates|ignore-duplicates. With resolution=merge-duplicates, a conflicting row keeps columns omitted from the request; supplied values replace the whole field value (including JSON objects), and explicit null clears a nullable field. With resolution=ignore-duplicates, a conflicting row is left unchanged. Without a conflict, both modes insert a new row using field defaults for omitted fields. In a batch, a key present in another row is filled with null when omitted in this row unless missing=default is set; that null can overwrite a value during merge. With missing=default, omitted keys stay omitted for conflict merges (existing values are preserved); new rows use defaults, or null when no default exists. Explicit null never invokes a default. POST accepts an optional client id matching [A-Za-z0-9_-]{1,64}; omitted ids are generated. PATCH cannot change id.";
     }, {
         readonly name: "columns";
         readonly type: "string";
@@ -5486,7 +5553,7 @@ export declare const operations: readonly [{
     readonly resource: "database.databases.rest";
     readonly method: "retrieve";
     readonly summary: "Select rows";
-    readonly description: "Read matching rows with filters, selected columns and ordering. Returns at most 1000 rows per request, including when limit is omitted. Content-Range reports the actual returned interval and the total when count is requested. PATCH and DELETE are not subject to this read cap. Unlike Supabase, casts, aggregates, spread and join modifiers are unsupported. Each table supports up to 1,000,000 rows. Query budget: 8,000 ms with a shared 3,000,000-row safety ceiling. Create indexes on filtered or sorted fields, or narrow the request when it exceeds its budget. Synchronous SQLite aggregates use candidate-row throughput estimates before execution; deployed Workers freeze clocks during synchronous CPU work, so the timer is not a guaranteed server-side interrupt. Count preferences: without filters, exact, planned and estimated all use SQLite's exact b-tree count. With filters, exact counts within budget; planned skips counting and reports an unknown total (Content-Range: 0-24/*); estimated attempts exact counting only when the preflight budget allows it, otherwise reports an unknown total. Preference-Applied echoes the requested count mode. Error table: QUERY_CANCELED / PostgREST 57014 is HTTP 500, retryable=false: Query timed out: index filtered or sorted fields, or narrow the range. DATABASE_INVALID_STATE is HTTP 409 for operations on a deleting database. Cleared or nonexistent databases return DATABASE_NOT_FOUND / HTTP 404. The count is an HTTP Content-Range response header, not a JSON property. Praxis SDK/codemode methods return the body only; a page length is not a total unless you know all matches fit in that page.";
+    readonly description: "Read matching rows with filters, selected columns and ordering. Returns at most 1000 rows per request, including when limit is omitted. Content-Range reports the actual returned interval and the total when count is requested. PATCH and DELETE are not subject to this read cap. Unlike Supabase, casts, aggregates, spread and join modifiers are unsupported. Each table supports up to 1,000,000 rows. Query budget: 8,000 ms with a shared 3,000,000-row safety ceiling. Create indexes on filtered or sorted fields, or narrow the request when it exceeds its budget. Synchronous SQLite aggregates use candidate-row throughput estimates before execution; deployed Workers freeze clocks during synchronous CPU work, so the timer is not a guaranteed server-side interrupt. Count preferences: without filters, exact, planned and estimated all use SQLite's exact b-tree count. With filters, exact counts within budget; planned skips counting and reports an unknown total (Content-Range: 0-24/*); estimated attempts exact counting only when the preflight budget allows it, otherwise reports an unknown total. Preference-Applied echoes the requested count mode. Error table: QUERY_CANCELED / PostgREST 57014 is HTTP 500, retryable=false: Query timed out: index filtered or sorted fields, or narrow the range. DATABASE_INVALID_STATE is HTTP 409 for operations on a deleting database. Cleared or nonexistent databases return DATABASE_NOT_FOUND / HTTP 404. The count is an HTTP Content-Range response header, not a JSON property. Use praxis.database.count in the SDK or codemode to return { count: number | null }; a page length is not a total unless you know all matches fit in that page.";
     readonly http: "GET";
     readonly path: "/database/v1/databases/{database_id}/rest/{table}";
     readonly streaming: "no";
@@ -5507,7 +5574,7 @@ export declare const operations: readonly [{
         readonly name: "{column}";
         readonly type: "string";
         readonly required: false;
-        readonly description: "Horizontal filter: replace {column} with a field name or JSON path, e.g. title=eq.summary. Repeat for more columns. See the filter operator matrix.";
+        readonly description: "Horizontal filter: replace {column} with a field name or JSON path, e.g. title=eq.summary. Repeat for more columns. Supported operators: eq (equal), neq (not equal; ne is not supported), gt/gte/lt/lte (comparisons), like (case-sensitive text pattern), ilike (case-insensitive text pattern), in (membership), is (null/boolean test), cs (contains), cd (contained by), and ov (array overlap). For like/ilike, * or % matches any sequence and _ matches one character, e.g. title=ilike.*spring*; URL-encode a literal % as %25. Use days=in.(1,2,3), title=is.null, active=is.true or active=is.false; is.not_null and is.unknown are also accepted (unknown means null). Negate a condition with not., e.g. title=not.eq.draft. Multiple filters are ANDed; use or=(title.eq.a,title.eq.b), and=(days.gte.1,days.lte.3), not.or=(...) or not.and=(...), with nested and(...) and or(...) groups as needed. cs/cd accept JSON objects or arrays on JSON fields; cs also accepts a JSON scalar. For array values or multi-link fields, use cs.{a,b}, cd.{a,b} or ov.{a,b}. JSON paths use -> for JSON and ->> for text, e.g. attributes->>has_onsen=eq.true or attributes->tags=cs.[1,2]; chain -> segments and end with ->> for text. Dot paths such as attributes.has_onsen are unsupported. Full-text, regex, range operators and any/all modifiers are unsupported.";
     }, {
         readonly name: "and";
         readonly type: "string";
@@ -5547,7 +5614,7 @@ export declare const operations: readonly [{
         readonly name: "on_conflict";
         readonly type: "string";
         readonly required: false;
-        readonly description: "POST upsert: id or one unique field with resolution=merge-duplicates|ignore-duplicates. POST accepts an optional client id matching [A-Za-z0-9_-]{1,64}; omitted ids are generated. PATCH cannot change id.";
+        readonly description: "POST upsert: id or one unique field with resolution=merge-duplicates|ignore-duplicates. With resolution=merge-duplicates, a conflicting row keeps columns omitted from the request; supplied values replace the whole field value (including JSON objects), and explicit null clears a nullable field. With resolution=ignore-duplicates, a conflicting row is left unchanged. Without a conflict, both modes insert a new row using field defaults for omitted fields. In a batch, a key present in another row is filled with null when omitted in this row unless missing=default is set; that null can overwrite a value during merge. With missing=default, omitted keys stay omitted for conflict merges (existing values are preserved); new rows use defaults, or null when no default exists. Explicit null never invokes a default. POST accepts an optional client id matching [A-Za-z0-9_-]{1,64}; omitted ids are generated. PATCH cannot change id.";
     }, {
         readonly name: "columns";
         readonly type: "string";
@@ -5558,7 +5625,7 @@ export declare const operations: readonly [{
     readonly resource: "database.databases.rest";
     readonly method: "head";
     readonly summary: "Count rows";
-    readonly description: "Inspect the HTTP row count and range without retrieving row data; send Prefer: count=exact for a filtered count. Returns no body and does not fetch or serialize row data. A known count determines the interval using limit/offset or Range with a default and maximum page size of 1000. Without a count preference, or when the selected count mode cannot supply a total, Content-Range is */*. Singular Accept still validates page cardinality. Unlike Supabase, planned and estimated counts do not use PostgreSQL planner estimates. Count preferences: without filters, exact, planned and estimated all use SQLite's exact b-tree count. With filters, exact counts within budget; planned skips counting and reports an unknown total (Content-Range: 0-24/*); estimated attempts exact counting only when the preflight budget allows it, otherwise reports an unknown total. Preference-Applied echoes the requested count mode. Praxis SDK/codemode methods return only the empty body, not the Content-Range response header; use an HTTP client when you need that header.";
+    readonly description: "Inspect the HTTP row count and range without retrieving row data; send Prefer: count=exact for a filtered count. Returns no body and does not fetch or serialize row data. A known count determines the interval using limit/offset or Range with a default and maximum page size of 1000. Without a count preference, or when the selected count mode cannot supply a total, Content-Range is */*. Singular Accept still validates page cardinality. Unlike Supabase, planned and estimated counts do not use PostgreSQL planner estimates. Count preferences: without filters, exact, planned and estimated all use SQLite's exact b-tree count. With filters, exact counts within budget; planned skips counting and reports an unknown total (Content-Range: 0-24/*); estimated attempts exact counting only when the preflight budget allows it, otherwise reports an unknown total. Preference-Applied echoes the requested count mode. Use praxis.database.count in the SDK or codemode to return { count: number | null } from this header without retrieving rows.";
     readonly http: "HEAD";
     readonly path: "/database/v1/databases/{database_id}/rest/{table}";
     readonly streaming: "no";
@@ -5579,7 +5646,7 @@ export declare const operations: readonly [{
         readonly name: "{column}";
         readonly type: "string";
         readonly required: false;
-        readonly description: "Horizontal filter: replace {column} with a field name or JSON path, e.g. title=eq.summary. Repeat for more columns. See the filter operator matrix.";
+        readonly description: "Horizontal filter: replace {column} with a field name or JSON path, e.g. title=eq.summary. Repeat for more columns. Supported operators: eq (equal), neq (not equal; ne is not supported), gt/gte/lt/lte (comparisons), like (case-sensitive text pattern), ilike (case-insensitive text pattern), in (membership), is (null/boolean test), cs (contains), cd (contained by), and ov (array overlap). For like/ilike, * or % matches any sequence and _ matches one character, e.g. title=ilike.*spring*; URL-encode a literal % as %25. Use days=in.(1,2,3), title=is.null, active=is.true or active=is.false; is.not_null and is.unknown are also accepted (unknown means null). Negate a condition with not., e.g. title=not.eq.draft. Multiple filters are ANDed; use or=(title.eq.a,title.eq.b), and=(days.gte.1,days.lte.3), not.or=(...) or not.and=(...), with nested and(...) and or(...) groups as needed. cs/cd accept JSON objects or arrays on JSON fields; cs also accepts a JSON scalar. For array values or multi-link fields, use cs.{a,b}, cd.{a,b} or ov.{a,b}. JSON paths use -> for JSON and ->> for text, e.g. attributes->>has_onsen=eq.true or attributes->tags=cs.[1,2]; chain -> segments and end with ->> for text. Dot paths such as attributes.has_onsen are unsupported. Full-text, regex, range operators and any/all modifiers are unsupported.";
     }, {
         readonly name: "and";
         readonly type: "string";
@@ -5619,7 +5686,7 @@ export declare const operations: readonly [{
         readonly name: "on_conflict";
         readonly type: "string";
         readonly required: false;
-        readonly description: "POST upsert: id or one unique field with resolution=merge-duplicates|ignore-duplicates. POST accepts an optional client id matching [A-Za-z0-9_-]{1,64}; omitted ids are generated. PATCH cannot change id.";
+        readonly description: "POST upsert: id or one unique field with resolution=merge-duplicates|ignore-duplicates. With resolution=merge-duplicates, a conflicting row keeps columns omitted from the request; supplied values replace the whole field value (including JSON objects), and explicit null clears a nullable field. With resolution=ignore-duplicates, a conflicting row is left unchanged. Without a conflict, both modes insert a new row using field defaults for omitted fields. In a batch, a key present in another row is filled with null when omitted in this row unless missing=default is set; that null can overwrite a value during merge. With missing=default, omitted keys stay omitted for conflict merges (existing values are preserved); new rows use defaults, or null when no default exists. Explicit null never invokes a default. POST accepts an optional client id matching [A-Za-z0-9_-]{1,64}; omitted ids are generated. PATCH cannot change id.";
     }, {
         readonly name: "columns";
         readonly type: "string";
@@ -5651,7 +5718,7 @@ export declare const operations: readonly [{
         readonly name: "{column}";
         readonly type: "string";
         readonly required: false;
-        readonly description: "Horizontal filter: replace {column} with a field name or JSON path, e.g. title=eq.summary. Repeat for more columns. See the filter operator matrix.";
+        readonly description: "Horizontal filter: replace {column} with a field name or JSON path, e.g. title=eq.summary. Repeat for more columns. Supported operators: eq (equal), neq (not equal; ne is not supported), gt/gte/lt/lte (comparisons), like (case-sensitive text pattern), ilike (case-insensitive text pattern), in (membership), is (null/boolean test), cs (contains), cd (contained by), and ov (array overlap). For like/ilike, * or % matches any sequence and _ matches one character, e.g. title=ilike.*spring*; URL-encode a literal % as %25. Use days=in.(1,2,3), title=is.null, active=is.true or active=is.false; is.not_null and is.unknown are also accepted (unknown means null). Negate a condition with not., e.g. title=not.eq.draft. Multiple filters are ANDed; use or=(title.eq.a,title.eq.b), and=(days.gte.1,days.lte.3), not.or=(...) or not.and=(...), with nested and(...) and or(...) groups as needed. cs/cd accept JSON objects or arrays on JSON fields; cs also accepts a JSON scalar. For array values or multi-link fields, use cs.{a,b}, cd.{a,b} or ov.{a,b}. JSON paths use -> for JSON and ->> for text, e.g. attributes->>has_onsen=eq.true or attributes->tags=cs.[1,2]; chain -> segments and end with ->> for text. Dot paths such as attributes.has_onsen are unsupported. Full-text, regex, range operators and any/all modifiers are unsupported.";
     }, {
         readonly name: "and";
         readonly type: "string";
@@ -5691,7 +5758,7 @@ export declare const operations: readonly [{
         readonly name: "on_conflict";
         readonly type: "string";
         readonly required: false;
-        readonly description: "POST upsert: id or one unique field with resolution=merge-duplicates|ignore-duplicates. POST accepts an optional client id matching [A-Za-z0-9_-]{1,64}; omitted ids are generated. PATCH cannot change id.";
+        readonly description: "POST upsert: id or one unique field with resolution=merge-duplicates|ignore-duplicates. With resolution=merge-duplicates, a conflicting row keeps columns omitted from the request; supplied values replace the whole field value (including JSON objects), and explicit null clears a nullable field. With resolution=ignore-duplicates, a conflicting row is left unchanged. Without a conflict, both modes insert a new row using field defaults for omitted fields. In a batch, a key present in another row is filled with null when omitted in this row unless missing=default is set; that null can overwrite a value during merge. With missing=default, omitted keys stay omitted for conflict merges (existing values are preserved); new rows use defaults, or null when no default exists. Explicit null never invokes a default. POST accepts an optional client id matching [A-Za-z0-9_-]{1,64}; omitted ids are generated. PATCH cannot change id.";
     }, {
         readonly name: "columns";
         readonly type: "string";
@@ -5706,7 +5773,7 @@ export declare const operations: readonly [{
     readonly resource: "database.databases.rest";
     readonly method: "create";
     readonly summary: "Insert rows";
-    readonly description: "Insert rows into an existing table after defining its fields; at most 500 rows per request. Each request is atomic: any failure rolls back the entire batch. There are no transactions across requests.\nRows are filled to the union of their keys with null; send Prefer: missing=default to use field defaults for missing keys.\nThe default is return=minimal: success returns HTTP 201 with an empty body. Send Prefer: return=representation to return the inserted rows. Unlike Supabase, upsert conflicts can target only id or one unique field, not a composite key. Each table supports up to 1,000,000 rows.";
+    readonly description: "Insert rows into an existing table after defining its fields; at most 500 rows per request. Each request is atomic: any failure rolls back the entire batch. There are no transactions across requests.\nRows are filled to the union of their keys with null; send Prefer: missing=default to use field defaults for missing keys.\nThe default is return=minimal: success returns HTTP 201 with an empty body. Send Prefer: return=representation to return the inserted rows. With resolution=merge-duplicates, a conflicting row keeps columns omitted from the request; supplied values replace the whole field value (including JSON objects), and explicit null clears a nullable field. With resolution=ignore-duplicates, a conflicting row is left unchanged. Without a conflict, both modes insert a new row using field defaults for omitted fields. In a batch, a key present in another row is filled with null when omitted in this row unless missing=default is set; that null can overwrite a value during merge. With missing=default, omitted keys stay omitted for conflict merges (existing values are preserved); new rows use defaults, or null when no default exists. Explicit null never invokes a default. Unlike Supabase, upsert conflicts can target only id or one unique field, not a composite key. Each table supports up to 1,000,000 rows.";
     readonly http: "POST";
     readonly path: "/database/v1/databases/{database_id}/rest/{table}";
     readonly streaming: "no";
@@ -5727,7 +5794,7 @@ export declare const operations: readonly [{
         readonly name: "{column}";
         readonly type: "string";
         readonly required: false;
-        readonly description: "Horizontal filter: replace {column} with a field name or JSON path, e.g. title=eq.summary. Repeat for more columns. See the filter operator matrix.";
+        readonly description: "Horizontal filter: replace {column} with a field name or JSON path, e.g. title=eq.summary. Repeat for more columns. Supported operators: eq (equal), neq (not equal; ne is not supported), gt/gte/lt/lte (comparisons), like (case-sensitive text pattern), ilike (case-insensitive text pattern), in (membership), is (null/boolean test), cs (contains), cd (contained by), and ov (array overlap). For like/ilike, * or % matches any sequence and _ matches one character, e.g. title=ilike.*spring*; URL-encode a literal % as %25. Use days=in.(1,2,3), title=is.null, active=is.true or active=is.false; is.not_null and is.unknown are also accepted (unknown means null). Negate a condition with not., e.g. title=not.eq.draft. Multiple filters are ANDed; use or=(title.eq.a,title.eq.b), and=(days.gte.1,days.lte.3), not.or=(...) or not.and=(...), with nested and(...) and or(...) groups as needed. cs/cd accept JSON objects or arrays on JSON fields; cs also accepts a JSON scalar. For array values or multi-link fields, use cs.{a,b}, cd.{a,b} or ov.{a,b}. JSON paths use -> for JSON and ->> for text, e.g. attributes->>has_onsen=eq.true or attributes->tags=cs.[1,2]; chain -> segments and end with ->> for text. Dot paths such as attributes.has_onsen are unsupported. Full-text, regex, range operators and any/all modifiers are unsupported.";
     }, {
         readonly name: "and";
         readonly type: "string";
@@ -5767,7 +5834,7 @@ export declare const operations: readonly [{
         readonly name: "on_conflict";
         readonly type: "string";
         readonly required: false;
-        readonly description: "POST upsert: id or one unique field with resolution=merge-duplicates|ignore-duplicates. POST accepts an optional client id matching [A-Za-z0-9_-]{1,64}; omitted ids are generated. PATCH cannot change id.";
+        readonly description: "POST upsert: id or one unique field with resolution=merge-duplicates|ignore-duplicates. With resolution=merge-duplicates, a conflicting row keeps columns omitted from the request; supplied values replace the whole field value (including JSON objects), and explicit null clears a nullable field. With resolution=ignore-duplicates, a conflicting row is left unchanged. Without a conflict, both modes insert a new row using field defaults for omitted fields. In a batch, a key present in another row is filled with null when omitted in this row unless missing=default is set; that null can overwrite a value during merge. With missing=default, omitted keys stay omitted for conflict merges (existing values are preserved); new rows use defaults, or null when no default exists. Explicit null never invokes a default. POST accepts an optional client id matching [A-Za-z0-9_-]{1,64}; omitted ids are generated. PATCH cannot change id.";
     }, {
         readonly name: "columns";
         readonly type: "string";
@@ -5810,7 +5877,7 @@ export declare const operations: readonly [{
     readonly resource: "database.databases.tables";
     readonly method: "create";
     readonly summary: "Create table";
-    readonly description: "Creates a table together with its initial fields in one call and returns it (HTTP 201) with generated tbl_ and fld_ ids. name must match ^[a-z_][a-z0-9_]{0,62}$ and be unused in this database (duplicate: 409 UNIQUE_VIOLATION). fields is required and may be an empty array; fields can also be added later with databaseAddField. Limits: 50 tables per database, 64 fields per table, and 16 indexed or unique fields per table; exceeding one returns 400 LIMIT_EXCEEDED. Every row also has a system id column, which is not declared as a field. Insert data afterwards with databaseInsert. Unlike Supabase, define schema with this table API and the field APIs; PostgreSQL DDL and SQL migration files cannot be submitted. Each table supports up to 1,000,000 rows.";
+    readonly description: "Creates a table together with its initial fields in one call and returns it (HTTP 201) with generated tbl_ and fld_ ids. name must match ^[a-z_][a-z0-9_]{0,62}$ and be unused in this database (duplicate: 409 UNIQUE_VIOLATION). fields is required and may be an empty array; fields can also be added later with databaseAddField. Limits: 50 tables per database, 64 fields per table, and 16 indexed or unique fields per table; exceeding one returns 400 LIMIT_EXCEEDED. Fields default to indexed:false. Set indexed:true explicitly for fields used in filters or ordering. Only indexed:true or unique:true consumes one of the 16 indexed-or-unique field slots; a field with both consumes one slot. Unique fields still consume a slot even with indexed:false. Existing fields are unchanged. Minimal field example: {\"name\":\"notes\",\"type\":\"string\",\"indexed\":false}. Every row also has a system id column, which is not declared as a field. Insert data afterwards with databaseInsert. Unlike Supabase, define schema with this table API and the field APIs; PostgreSQL DDL and SQL migration files cannot be submitted. Each table supports up to 1,000,000 rows.";
     readonly http: "POST";
     readonly path: "/database/v1/databases/{database_id}/tables";
     readonly streaming: "no";
@@ -5909,7 +5976,7 @@ export declare const operations: readonly [{
     readonly resource: "database.databases.tables.fields";
     readonly method: "create";
     readonly summary: "Add field";
-    readonly description: "Adds one field to an existing table and returns the updated table (HTTP 201). Required inputs are name (lowercase letters, digits and underscores; id and names starting with _ are reserved) and type (string, integer, number, boolean, datetime, json or link); json needs options.schema and link needs options.linked_table_id and options.multiple. Adding a required field to a table that already has rows needs a default, otherwise the call fails with 400 VALIDATION_FAILED; a default is written into every existing row. Scalar fields are indexed by default, while json and link fields cannot be indexed. Limits: 64 fields and 16 indexed or unique fields per table (400 LIMIT_EXCEEDED). Unlike Supabase, schema evolution uses field definitions rather than ALTER TABLE statements or SQL migrations.";
+    readonly description: "Adds one field to an existing table and returns the updated table (HTTP 201). Required inputs are name (lowercase letters, digits and underscores; id and names starting with _ are reserved) and type (string, integer, number, boolean, datetime, json or link); json needs options.schema and link needs options.linked_table_id and options.multiple. Adding a required field to a table that already has rows needs a default, otherwise the call fails with 400 VALIDATION_FAILED; a default is written into every existing row. Fields default to indexed:false. Set indexed:true explicitly for fields used in filters or ordering. Only indexed:true or unique:true consumes one of the 16 indexed-or-unique field slots; a field with both consumes one slot. Unique fields still consume a slot even with indexed:false. Existing fields are unchanged. Minimal field example: {\"name\":\"notes\",\"type\":\"string\",\"indexed\":false}. JSON and link fields cannot be indexed. Limits: 64 fields and 16 indexed or unique fields per table (400 LIMIT_EXCEEDED). Unlike Supabase, schema evolution uses field definitions rather than ALTER TABLE statements or SQL migrations.";
     readonly http: "POST";
     readonly path: "/database/v1/databases/{database_id}/tables/{table}/fields";
     readonly streaming: "no";