@k9o/core 1.0.0 → 1.1.0

package/dist/index.js

@@ -2,7 +2,7 @@ import "./chunk-YEYRP6PG.js";
 import {
   request,
   requestStream
-} from "./chunk-FVWKL5UQ.js";
+} from "./chunk-O2ZTV6YN.js";
 import {
   orgPath,
   platformPath,
@@ -10,11 +10,11 @@ import {
   resolveBaseUrl,
   validateBaseUrl,
   validateSlug
-} from "./chunk-OE2MMUIG.js";
+} from "./chunk-2NDFTHUB.js";
 import {
   KError,
   kerrorFromWire
-} from "./chunk-2VSTF5UU.js";
+} from "./chunk-LJZ45UA2.js";
 
 // src/data/from.ts
 var QueryBuilder = class {
@@ -92,7 +92,7 @@ var QueryBuilder = class {
     return this;
   }
   /**
-   * Total-count behaviour per ch01 §6.4. `none` (default) skips the
+   * Total-count behaviour. `none` (default) skips the
    * count query (cheapest); `exact` runs `SELECT COUNT(*)` (most
    * expensive at scale); `estimated` reads from pg_stats (fast +
    * approximate).
@@ -134,7 +134,7 @@ var FromBuilder = class {
   }
   /**
    * Insert one record. Returns the inserted record (with platform-
-   * generated `id` + `metadata`) per ch04 §6.4.
+   * generated `id` + `metadata`).
    */
   async insert(record) {
     return request(this.config, {
@@ -193,9 +193,9 @@ var UpdateBuilder = class extends QueryBuilder {
     if (idFilter === void 0) {
       throw new KError({
         code: "K9O_INVALID_FIELD_VALUE",
-        message: "update() requires an `.eq('id', '...')` filter; row-mass update is not supported at v0.1.0",
+        message: "update() requires an `.eq('id', '...')` filter; changing many rows in one call is not supported",
         context: { collection: this.collection },
-        recommendation: "Chain `.eq('id', 'rec_\u2026')` before awaiting the update; row-mass update lands in a v0.x sub-cycle."
+        recommendation: "Chain `.eq('id', 'rec_\u2026')` before awaiting the update; to change several rows, call update once per id."
       });
     }
     return request(this.config, {
@@ -221,9 +221,9 @@ var DeleteBuilder = class extends QueryBuilder {
     if (idFilter === void 0) {
       throw new KError({
         code: "K9O_INVALID_FIELD_VALUE",
-        message: "delete() requires an `.eq('id', '...')` filter; row-mass delete is not supported at v0.1.0",
+        message: "delete() requires an `.eq('id', '...')` filter; deleting many rows in one call is not supported",
         context: { collection: this.collection },
-        recommendation: "Chain `.eq('id', 'rec_\u2026')` before awaiting the delete; row-mass delete lands in a v0.x sub-cycle."
+        recommendation: "Chain `.eq('id', 'rec_\u2026')` before awaiting the delete; to delete several rows, call delete once per id."
       });
     }
     return request(this.config, {
@@ -266,7 +266,7 @@ function makeProjectsNamespace(config) {
   return {
     /**
      * List projects accessible to the caller. Requires authenticated
-     * session; results are scoped by RBAC per ch06.
+     * session; results are scoped by RBAC.
      */
     async list() {
       return request(config, {
@@ -564,7 +564,7 @@ function requireProjectSlug3(config) {
   if (config.projectSlug === void 0 || config.projectSlug.length === 0) {
     throw new KError({
       code: "K9O_MISSING_PROJECT_CONTEXT",
-      message: "client.metadata requires a bound projectSlug (project data-plane resource, ch14 \xA74)",
+      message: "client.metadata requires a bound projectSlug (project data-plane resource,)",
       context: {},
       recommendation: "Pass projectSlug when constructing the client."
     });
@@ -598,7 +598,7 @@ function makeBuilder(config, surfaces, where, limit, cursorValue) {
 }
 function makeMetadataNamespace(config) {
   return {
-    /** Start a cross-surface metadata query against one or more surfaces (ch14 §3.1). */
+    /** Start a cross-surface metadata query against one or more surfaces. */
     from(surface) {
       const surfaces = Array.isArray(surface) ? surface : [surface];
       if (surfaces.length === 0) {
@@ -648,7 +648,7 @@ function makeMigrationsNamespace(config) {
         path: projectPath(slug, `migrations/${encodeURIComponent(String(version))}`)
       });
     },
-    /** Queue migrations for maker-checker approval per ch06 §8. */
+    /** Queue migrations for maker-checker approval. */
     async queue(input) {
       const slug = requireProjectSlug4(config);
       return request(config, {
@@ -666,7 +666,7 @@ function makeMigrationsNamespace(config) {
       });
     },
     /**
-     * Apply a queued migration by id (§2.6 same-actor fast path — floors at
+     * Apply a queued migration by id (same-actor fast path — floors at
      * PROJECT_ADMIN; a `pending_approval` row, i.e. a protected-collection
      * migration awaiting a distinct-admin's review, is refused here and
      * needs its own approval flow, not this call).
@@ -716,7 +716,7 @@ function makeFunctionsNamespace(config) {
         body: input
       });
     },
-    /** List deployed functions (cursor pagination per ch01 §6.4). */
+    /** List deployed functions (cursor pagination). */
     async list(opts) {
       const slug = requireProjectSlug5(config);
       return request(config, {
@@ -733,7 +733,7 @@ function makeFunctionsNamespace(config) {
         path: projectPath(slug, `functions/${encodeURIComponent(name)}`)
       });
     },
-    /** Retire a function. Returns confirmation; the function name enters a 24h cooldown per ch07 §3.1. */
+    /** Retire a function. Returns confirmation; the function name enters a 24h cooldown. */
     async delete(name) {
       const slug = requireProjectSlug5(config);
       return request(config, {
@@ -746,8 +746,8 @@ function makeFunctionsNamespace(config) {
      * verbatim; the gateway returns whatever the function returns wrapped
      * in the standard envelope.
      *
-     * Per ch07 §3.3: invoke authority is per-function (declared in the
-     * function manifest). Per ch07 §5: streaming responses use the
+     * Per: invoke authority is per-function (declared in the
+     * function manifest). Per: streaming responses use the
      * subscription/async-iterator pattern; this method covers the
      * request-response variant only.
      */
@@ -855,7 +855,7 @@ function makeAuditNamespace(config) {
      * Query the audit log. Returns reverse-chronological events matching
      * all supplied filters (AND composition).
      *
-     * Per ch05 §4 RBAC: requires `AUDIT_READER` role minimum; Custodian-
+     * Per RBAC: requires `AUDIT_READER` role minimum; Custodian-
      * class roles inherit. Project-level audit is project-scoped (this
      * endpoint); platform-level audit is admin-only (separate surface).
      */
@@ -870,7 +870,7 @@ function makeAuditNamespace(config) {
     /**
      * Convenience: live-tail recent events. Currently single-shot read
      * with `since` defaulted to "1 minute ago"; subscription-mode tail
-     * (SSE) lands when the streaming layer ships per ch04 §8 pattern.
+     * (SSE) lands when the streaming layer ships pattern.
      */
     async tail(opts) {
       const slug = requireProjectSlug7(config);
@@ -967,7 +967,7 @@ function makeOrgAuditLogNamespace(config) {
      * GET /audit-log (org-plane).
      * Distinct from project-plane `client.audit.query()` which routes to
      * `@<projectSlug>/audit-log`. Org-plane events cover the 6-event family
-     * per ch05 §4.2 (member_invited/removed/role_granted/revoked/
+     * (member_invited/removed/role_granted/revoked/
      * idp_config_changed/settings_updated).
      */
     async query(opts) {
@@ -988,7 +988,7 @@ function makeOrgAuditLogNamespace(config) {
 function makeOrgGateNamespace(config) {
   return {
     roles: {
-      /** GET /org-role-grants — list active grants per ch02 §6.5 ask 4. */
+      /** GET /org-role-grants — list active grants ask 4. */
       async list(opts) {
         return request(config, { method: "GET", path: orgPath("org-role-grants"), query: opts });
       },
@@ -1006,7 +1006,7 @@ function makeOrgGateNamespace(config) {
       }
     },
     idpProviders: {
-      /** GET /idp-providers — list configured org operator IdP providers per ch02 §6.5 ask 7. */
+      /** GET /idp-providers — list configured org operator IdP providers ask 7. */
       async list() {
         return request(config, { method: "GET", path: orgPath("idp-providers") });
       },
@@ -1034,7 +1034,7 @@ function makeSmtpNamespace(config) {
     /**
      * GET /org/smtp — read current SMTP config.
      * Returns null when no org-level SMTP is configured (falls back to
-     * platform SMTP per ch02 §6.6 3-tier cascade).
+     * platform SMTP 3-tier cascade).
      */
     async get() {
       return request(config, { method: "GET", path: orgPath("org/smtp") });
@@ -1065,17 +1065,17 @@ function makeSmtpNamespace(config) {
 function makeDefaultLlmNamespace(config) {
   return {
     /**
-     * GET /org/default-llm — read the org-default LLM model id per ch07
-     * §10.3. Returns `null` when no explicit default is set (gateway
-     * falls back to `mistral-7b` per §10.3). ORG_ADMIN read; tier-gated.
+     * GET /org/default-llm — read the org-default LLM model id
+     *. Returns `null` when no explicit default is set (gateway
+     * falls back to `mistral-7b`). ORG_ADMIN read; tier-gated.
      */
     async get() {
       return request(config, { method: "GET", path: orgPath("org/default-llm") });
     },
     /**
-     * PATCH /org/default-llm — set the org-default LLM per ch07 §10.3.
+     * PATCH /org/default-llm — set the org-default LLM.
      * ORG_ADMIN only. The model must be available to the org's tier per
-     * §10.1 or the gateway returns K9O_TIER_FEATURE_GATED.
+     * or the gateway returns K9O_TIER_FEATURE_GATED.
      */
     async set(input) {
       return request(config, { method: "PATCH", path: orgPath("org/default-llm"), body: input });
@@ -1094,7 +1094,7 @@ function makeOrgNamespace(config) {
     gate: makeOrgGateNamespace(config),
     /** Org-level SMTP config — get / set / test / unset. */
     smtp: makeSmtpNamespace(config),
-    /** Org-default LLM — get / set per ch07 §10.3 (ORG_ADMIN). */
+    /** Org-default LLM — get / set (ORG_ADMIN). */
     defaultLLM: makeDefaultLlmNamespace(config),
     /**
      * GET /org — read the current org (slug + name + status + settings).
@@ -1135,9 +1135,8 @@ function makeMeNamespace(config) {
       }
     },
     /**
-     * API tokens for personal scripting (forward-cycle surface per ch12
-     * §3.1 implicit; substrate not yet shipped per gateway routes audit).
-     * Methods will return K9O_NOT_FOUND until gateway lands the endpoints.
+     * API tokens for personal scripting. The gateway endpoints are not available yet,
+     * so these methods return K9O_NOT_FOUND until they ship.
      */
     apiTokens: {
       async list() {
@@ -1236,7 +1235,7 @@ function makeRunsNamespace(config) {
 }
 function makeWorkflowsNamespace(config) {
   return {
-    /** GET /@<slug>/workflows — list workflows (cursor pagination per ch01 §6.4). */
+    /** GET /@<slug>/workflows — list workflows (cursor pagination). */
     async list(filters) {
       const slug = requireProjectSlug8(config);
       return request(config, { method: "GET", path: projectPath(slug, "workflows"), query: filters });
@@ -1273,7 +1272,7 @@ function makeWorkflowsNamespace(config) {
     },
     /**
      * POST /@<slug>/workflows/<wfl-id>/runs — manual-trigger a run.
-     * Valid only for `triggerType: 'manual'` workflows per ch07 §9.6.
+     * Valid only for `triggerType: 'manual'` workflows.
      * Requires PROJECT_AUTHOR. Returns the materialised WorkflowRun.
      */
     async trigger(workflowId, triggerContext = {}) {
@@ -1302,7 +1301,7 @@ function requireProjectSlug9(config) {
 }
 function makeDashboardsNamespace(config) {
   return {
-    /** GET /@<slug>/dashboards — list dashboards (cursor pagination per ch01 §6.4). */
+    /** GET /@<slug>/dashboards — list dashboards (cursor pagination). */
     async list(filters) {
       const slug = requireProjectSlug9(config);
       return request(config, { method: "GET", path: projectPath(slug, "dashboards"), query: filters });
@@ -1359,9 +1358,9 @@ function makeDashboardsNamespace(config) {
 // src/studio/index.ts
 function makeStudioNamespace(config) {
   return {
-    /** Workflow lifecycle + runs — `client.studio.workflows.*` (ch07 §9). */
+    /** Workflow lifecycle + runs — `client.studio.workflows.*`. */
     workflows: makeWorkflowsNamespace(config),
-    /** Dashboard lifecycle + widget data — `client.studio.dashboards.*` (ch04 §3.10). */
+    /** Dashboard lifecycle + widget data — `client.studio.dashboards.*`. */
     dashboards: makeDashboardsNamespace(config)
   };
 }
@@ -1436,7 +1435,7 @@ function requireProjectSlug10(config) {
 }
 function makeLlmsNamespace(config) {
   return {
-    /** GET /@<slug>/compute/llms — list models available to the project tier per ch10. */
+    /** GET /@<slug>/compute/llms — list models available to the project tier. */
     async list(opts) {
       const slug = requireProjectSlug10(config);
       return request(config, { method: "GET", path: projectPath(slug, "compute/llms"), query: opts });
@@ -1451,7 +1450,7 @@ function makeLlmsNamespace(config) {
     },
     /**
      * POST /@<slug>/compute/llms/<model-id>/invoke — synchronous inference.
-     * Requires PROJECT_AUTHOR or PROJECT_ADMIN (LLM cost gate per §10.5).
+     * Requires PROJECT_AUTHOR or PROJECT_ADMIN (LLM cost gate).
      */
     async invoke(modelId, input) {
       const slug = requireProjectSlug10(config);
@@ -1463,7 +1462,7 @@ function makeLlmsNamespace(config) {
     },
     /**
      * POST /@<slug>/compute/llms/<model-id>/invoke-stream — streaming
-     * inference (SSE; per-token delta for low-latency UX per §10.2).
+     * inference (SSE; per-token delta for low-latency UX).
      * Returns an async iterable of `LLMStreamChunk` — caller writes
      * `for await (const chunk of client.compute.llms.invokeStream(...))`.
      * The SDK handles SSE framing internally per
@@ -1483,7 +1482,7 @@ function makeLlmsNamespace(config) {
 }
 function makeComputeNamespace(config) {
   return {
-    /** LLM registry + inference — `client.compute.llms.*` (ch07 §10). */
+    /** LLM registry + inference — `client.compute.llms.*`. */
     llms: makeLlmsNamespace(config)
   };
 }
@@ -1647,7 +1646,7 @@ function makeRealtimeNamespace(config) {
     /**
      * Subscribe to a topic. Returns a `RealtimeSubscription` — an async
      * iterable of `RealtimeEvent`s. The SDK selects the richest available
-     * transport (WebSocket → SSE → poll) per ch07 §11.3; the caller's
+     * transport (WebSocket → SSE → poll); the caller's
      * `for await` loop is transport-agnostic.
      *
      * ```ts
@@ -1688,7 +1687,7 @@ function makeRealtimeNamespace(config) {
       };
     },
     /**
-     * One-shot historical replay per ch07 §11.2 — catch up on missed
+     * One-shot historical replay — catch up on missed
      * events from `fromSequence`. Capped at 10k events server-side;
      * paginate via the returned events' `sequence`. Use the highest
      * `sequence` you've seen as the next `fromSequence`.