@k9o/core 1.0.0 → 1.1.0

package/src/realtime.ts

@@ -8,17 +8,17 @@
  * `for await (const event of client.realtime.subscribe(topic)) { ... }`.
  *
  * Per `feedback_sdk_abstracted_primitive_default_to_richer_interaction.md`
- * + ch07 §11.3: the SDK chooses the transport (WebSocket primary → SSE
+ * +: the SDK chooses the transport (WebSocket primary → SSE
  * → poll), transparently. SPLIT (polling) is the SDK-internal fallback
  * when WebSocket / SSE are unavailable — NOT a consumer-side design
  * choice. The consumer sees one uniform async iterable regardless.
  *
- * Wire mapping (project-plane; ch07 §11.2):
+ * Wire mapping (project-plane;):
  *   - subscribe → GET  /@<slug>/realtime/subscribe?topic=<t>&filter=<jsonb> (WS/SSE upgrade)
  *   - replay    → POST /@<slug>/realtime/replay  { topic, fromSequence, untilSequence?, limit? }
  *
- * Per ch07 §11.4, `filter` + RLS compose (filter narrows, RLS gates).
- * Per ch07 §11.5, surfaces no new codes — reuses K9O_INVALID_FILTER +
+ * Per, `filter` + RLS compose (filter narrows, RLS gates).
+ * Per, surfaces no new codes — reuses K9O_INVALID_FILTER +
  * K9O_SUBSCRIPTION_LIMIT_EXCEEDED + K9O_TIER_FEATURE_GATED.
  */
 
@@ -29,11 +29,11 @@ import type { Envelope } from "./envelope.ts";
 import { parseSseStream } from "./internal/sse.ts";
 
 // ----------------------------------------------------------------------
-// Topic catalogue (closed 6-family enum per ch07 §11.1)
+// Topic catalogue (closed 6-family enum)
 // ----------------------------------------------------------------------
 
 /**
- * The 6 closed subscription topic families per ch07 §11.1. Concrete
+ * The 6 closed subscription topic families. Concrete
  * topic strings carry a dynamic segment (collection name, resource id,
  * event family) — use `realtimeTopic.*` builders to construct them.
  */
@@ -49,7 +49,7 @@ export type RealtimeTopicFamily =
 export type RealtimeTopic = string;
 
 /**
- * Typed builders for the 6 topic families per ch07 §11.1. Prefer these
+ * Typed builders for the 6 topic families. Prefer these
  * over hand-built strings for compile-time family safety.
  */
 export const realtimeTopic = {
@@ -83,10 +83,10 @@ export const realtimeTopic = {
 // Event + filter shapes
 // ----------------------------------------------------------------------
 
-/** Per-topic filter predicate per ch07 §11.4 (ch04 §3.2 vocabulary). */
+/** Per-topic filter predicate (vocabulary). */
 export type RealtimeFilter = Record<string, unknown>;
 
-/** A single realtime event delivered on a subscription per ch07 §11. */
+/** A single realtime event delivered on a subscription. */
 export type RealtimeEvent<T = unknown> = {
   topic: RealtimeTopic;
   /** Event type within the topic family (e.g. `row_inserted`, `workflow.run.completed`). */
@@ -104,7 +104,7 @@ export type SubscribeOptions = {
   /**
    * Force a transport instead of the WebSocket → SSE → poll cascade.
    * Mainly for tests + constrained runtimes. Omit for production —
-   * the SDK picks the richest available transport per §11.3.
+   * the SDK picks the richest available transport.
    */
   transport?: RealtimeTransportKind;
   /** Poll-transport interval in ms (default 2000). Only used when polling. */
@@ -139,7 +139,7 @@ function requireProjectSlug(config: HttpClientConfig): string {
   return config.projectSlug;
 }
 
-/** Pick the richest transport available in this runtime per §11.3. */
+/** Pick the richest transport available in this runtime. */
 function selectTransport(forced?: RealtimeTransportKind): RealtimeTransportKind {
   if (forced) return forced;
   if (typeof (globalThis as { WebSocket?: unknown }).WebSocket === "function") return "websocket";
@@ -155,7 +155,7 @@ function toWebSocketUrl(baseUrl: string, path: string, query: Record<string, str
   return `${wsBase}${path}${qs ? `?${qs}` : ""}`;
 }
 
-/** WebSocket transport — primary per §11.3. Bridges socket → async queue. */
+/** WebSocket transport — primary. Bridges socket → async queue. */
 async function* websocketTransport<T>(
   config: HttpClientConfig,
   topic: RealtimeTopic,
@@ -222,7 +222,7 @@ async function* websocketTransport<T>(
   }
 }
 
-/** SSE transport — fallback per §11.3. Rides on fetch streaming. */
+/** SSE transport — fallback. Rides on fetch streaming. */
 async function* sseTransport<T>(
   config: HttpClientConfig,
   topic: RealtimeTopic,
@@ -244,7 +244,7 @@ async function* sseTransport<T>(
   }
 }
 
-/** Poll transport — last-resort fallback per §11.3 (SPLIT, SDK-internal). */
+/** Poll transport — last-resort fallback (SPLIT, SDK-internal). */
 async function* pollTransport<T>(
   config: HttpClientConfig,
   topic: RealtimeTopic,
@@ -275,7 +275,7 @@ export function makeRealtimeNamespace(config: HttpClientConfig) {
     /**
      * 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
@@ -319,7 +319,7 @@ export function makeRealtimeNamespace(config: HttpClientConfig) {
     },
 
     /**
-     * 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`.

package/src/retry.ts

@@ -19,7 +19,7 @@
  * Retry method discipline: only GET / HEAD / OPTIONS / DELETE are
  * retried by default — these are RFC-7231 idempotent. POST / PATCH /
  * PUT are NOT retried (caller can opt in via `idempotencyKey` header
- * per ch01 §10.2 when they assert idempotency).
+ * when they assert idempotency).
  *
  * Backoff:
  *   - `exponential` (default) — `initialDelayMs * 2^attempt`, capped at maxDelayMs; jittered ±25%

package/src/storage-buckets.ts

@@ -1,5 +1,5 @@
 /**
- * `client.storage` buckets and objects (ch04 §9): per-project logical buckets and the objects in them, against
+ * `client.storage` buckets and objects: per-project logical buckets and the objects in them, against
  * `/@<projectSlug>/storage/buckets…`. `client.storage.locations.*` (the customer's own object stores) lives in
  * `storage-locations.ts` and is unchanged.
  *

package/src/studio/dashboards.ts

@@ -2,9 +2,9 @@
  * Studio Dashboards SDK — `client.studio.dashboards.*`.
  *
  * Dashboards persisted authoring substrate.
- * Mirrors `_sys.dashboards` (§3.10.1) row shape.
+ * Mirrors `_sys.dashboards` row shape.
  *
- * Wire mapping (project-plane; ch04 §3.10.4):
+ * Wire mapping (project-plane;):
  *   - list()                  → GET    /@<slug>/dashboards
  *   - create(dashboard)       → POST   /@<slug>/dashboards
  *   - read(id)                → GET    /@<slug>/dashboards/<dsh-id>
@@ -13,9 +13,9 @@
  *   - pin(id)                 → POST   /@<slug>/dashboards/<dsh-id>/pin
  *   - unpin(id)               → POST   /@<slug>/dashboards/<dsh-id>/unpin
  *
- * Per ch04 §3.10.4 RBAC: create/update/delete/pin/unpin require
+ * Per RBAC: create/update/delete/pin/unpin require
  * PROJECT_AUTHOR; list/read read against all cohort roles subject
- * to RLS. Per ch04 §3.10.7, surfaces 2 K9O_DASHBOARD_* codes.
+ * to RLS. Per, surfaces 2 K9O_DASHBOARD_* codes.
  */
 
 import { request, type HttpClientConfig } from "../http.ts";
@@ -23,10 +23,10 @@ import { projectPath } from "../url-grammar.ts";
 import type { Envelope } from "../envelope.ts";
 
 // ----------------------------------------------------------------------
-// Enums (closed at v2 launch per ch04 §3.10.2 + §3.10.3)
+// Enums (closed at v2 launch +)
 // ----------------------------------------------------------------------
 
-/** 9-widget catalogue per ch04 §3.10.2. */
+/** 9-widget catalogue. */
 export type WidgetType =
   | "kpi_card"
   | "bar_chart"
@@ -43,7 +43,7 @@ export type WidgetDataSourceMode = "view" | "query" | "workflow" | "rollup" | "f
 
 export type DashboardStatus = "active" | "archived" | "draft";
 
-/** A widget config entry in the `widgets` array per ch04 §3.10.2. */
+/** A widget config entry in the `widgets` array. */
 export type Widget = {
   id: string;
   widgetType: WidgetType;
@@ -61,20 +61,20 @@ export type Widget = {
 // Resource shapes (mirror _sys.dashboards row)
 // ----------------------------------------------------------------------
 
-/** Dashboard record per ch04 §3.10.1 `_sys.dashboards` row. */
+/** Dashboard record `_sys.dashboards` row. */
 export type Dashboard = {
-  /** `dsh_<base62>` per ch01 §3.2. */
+  /** `dsh_<base62>`. */
   id: string;
   projectId: string;
   name: string;
   description: string;
   status: DashboardStatus;
-  /** Widget positions + sizes per output-03 §3 layout schema. */
+  /** Widget positions + sizes per output-03 layout schema. */
   layoutGrid: Record<string, unknown>;
   widgets: ReadonlyArray<Widget>;
   /** Dashboard-level filter widgets cascade to per-widget data sources. */
   filterConfig: Record<string, unknown>;
-  /** Pathmaker org-pin per output-03 §9; surfaces in Workspace sidebar. */
+  /** Pathmaker org-pin per output-03; surfaces in Workspace sidebar. */
   pinnedToWorkspace: boolean;
   rbacBinding: Record<string, unknown>;
   authoredBy: string;
@@ -102,7 +102,7 @@ export type DashboardListFilters = {
   pinnedToWorkspace?: boolean;
 };
 
-/** 2 K9O_DASHBOARD_* error codes per ch04 §3.10.7. */
+/** 2 K9O_DASHBOARD_* error codes. */
 export const DASHBOARD_ERROR_CODES = {
   NOT_FOUND: "K9O_DASHBOARD_NOT_FOUND",
   WIDGET_INVALID: "K9O_DASHBOARD_WIDGET_INVALID",
@@ -117,7 +117,7 @@ function requireProjectSlug(config: HttpClientConfig): string {
 
 export function makeDashboardsNamespace(config: HttpClientConfig) {
   return {
-    /** GET /@<slug>/dashboards — list dashboards (cursor pagination per ch01 §6.4). */
+    /** GET /@<slug>/dashboards — list dashboards (cursor pagination). */
     async list(filters?: DashboardListFilters): Promise<Envelope<ReadonlyArray<Dashboard>>> {
       const slug = requireProjectSlug(config);
       return request(config, { method: "GET", path: projectPath(slug, "dashboards"), query: filters });

package/src/studio/index.ts

@@ -10,9 +10,9 @@ import { makeDashboardsNamespace } from "./dashboards.ts";
 
 export function makeStudioNamespace(config: HttpClientConfig) {
   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),
   };
 }

package/src/studio/workflows.ts

@@ -2,9 +2,9 @@
  * Studio Workflows SDK — `client.studio.workflows.*`.
  *
  * Workflows substrate. Mirrors
- * `_sys.workflows` (§9.1) + `_sys.workflow_runs` (§9.2) row shapes.
+ * `_sys.workflows` + `_sys.workflow_runs` row shapes.
  *
- * Wire mapping (project-plane; ch07 §9.6):
+ * Wire mapping (project-plane;):
  *   - list()                       → GET    /@<slug>/workflows
  *   - create(workflow)             → POST   /@<slug>/workflows
  *   - read(id)                     → GET    /@<slug>/workflows/<wfl-id>
@@ -15,9 +15,9 @@
  *   - runs.read(id, runId)         → GET    /@<slug>/workflows/<wfl-id>/runs/<wfr-id>
  *   - runs.cancel(id, runId)       → POST   /@<slug>/workflows/<wfl-id>/runs/<wfr-id>/cancel
  *
- * Per ch07 §9.6 RBAC: create/update/delete/trigger/cancel require
+ * Per RBAC: create/update/delete/trigger/cancel require
  * PROJECT_AUTHOR; list/read/runs read against all cohort roles subject
- * to RLS. Per ch07 §9.11, surfaces 6 K9O_WORKFLOW_* error codes (see
+ * to RLS. Per, surfaces 6 K9O_WORKFLOW_* error codes (see
  * `WORKFLOW_ERROR_CODES`); callers narrow on `error.code`.
  */
 
@@ -26,10 +26,10 @@ import { projectPath } from "../url-grammar.ts";
 import type { Envelope } from "../envelope.ts";
 
 // ----------------------------------------------------------------------
-// Enums (closed at v2 launch per ch07 §9.3 + §9.4; extensible v2.x)
+// Enums (closed at v2 launch +; extensible v2.x)
 // ----------------------------------------------------------------------
 
-/** 5-trigger catalogue per ch07 §9.3. */
+/** 5-trigger catalogue. */
 export type WorkflowTriggerType =
   | "view_row_event"
   | "form_submission"
@@ -37,7 +37,7 @@ export type WorkflowTriggerType =
   | "manual"
   | "webhook";
 
-/** 9-action catalogue per ch07 §9.4. */
+/** 9-action catalogue. */
 export type WorkflowActionType =
   | "write_collection"
   | "read_collection"
@@ -58,14 +58,14 @@ export type WorkflowRunStatus =
   | "failed"
   | "cancelled";
 
-/** A single step in the `actions` chain per ch07 §9.4. */
+/** A single step in the `actions` chain. */
 export type WorkflowAction = {
   index: number;
   action_type: WorkflowActionType;
   config: Record<string, unknown>;
   retry?: { maxAttempts: number; backoffStrategy?: string };
   condition?: Record<string, unknown>;
-  /** Sibling steps with parallel:true execute concurrently per §9.4. */
+  /** Sibling steps with parallel:true execute concurrently. */
   parallel?: boolean;
 };
 
@@ -73,20 +73,20 @@ export type WorkflowAction = {
 // Resource shapes (mirror _sys.workflows + _sys.workflow_runs rows)
 // ----------------------------------------------------------------------
 
-/** Workflow record per ch07 §9.1 `_sys.workflows` row. */
+/** Workflow record `_sys.workflows` row. */
 export type Workflow = {
-  /** `wfl_<base62>` per ch01 §3.2. */
+  /** `wfl_<base62>`. */
   id: string;
   projectId: string;
   name: string;
   description: string;
   status: WorkflowStatus;
   triggerType: WorkflowTriggerType;
-  /** Shape varies per triggerType per §9.3. */
+  /** Shape varies per triggerType. */
   triggerConfig: Record<string, unknown>;
-  /** Chain definition per §9.4. */
+  /** Chain definition. */
   actions: ReadonlyArray<WorkflowAction>;
-  /** Approver-step participant resolution per §9.5. */
+  /** Approver-step participant resolution. */
   rbacBinding: Record<string, unknown>;
   authoredBy: string;
   authoredAt: string;
@@ -94,7 +94,7 @@ export type Workflow = {
   updatedAt: string;
 };
 
-/** Per-step status entry in a run per ch07 §9.2 `per_step_status`. */
+/** Per-step status entry in a run `per_step_status`. */
 export type WorkflowRunStep = {
   stepIndex: number;
   actionType: WorkflowActionType;
@@ -106,9 +106,9 @@ export type WorkflowRunStep = {
   costSubtotal?: number;
 };
 
-/** Workflow run record per ch07 §9.2 `_sys.workflow_runs` row. */
+/** Workflow run record `_sys.workflow_runs` row. */
 export type WorkflowRun = {
-  /** `wfr_<base62>` per ch01 §3.2. */
+  /** `wfr_<base62>`. */
   id: string;
   workflowId: string;
   projectId: string;
@@ -122,7 +122,7 @@ export type WorkflowRun = {
   firedBy: string;
 };
 
-/** Create input — omits server-assigned fields per §9.1. */
+/** Create input — omits server-assigned fields. */
 export type CreateWorkflowInput = {
   name: string;
   description?: string;
@@ -154,7 +154,7 @@ export type WorkflowRunListFilters = {
 };
 
 /**
- * 6 K9O_WORKFLOW_* error codes per ch07 §9.11. KError code-space is
+ * 6 K9O_WORKFLOW_* error codes. KError code-space is
  * open; these constants document the well-known codes for narrowing
  * (`if (e.code === WORKFLOW_ERROR_CODES.RUN_NOT_CANCELLABLE)`).
  */
@@ -208,7 +208,7 @@ function makeRunsNamespace(config: HttpClientConfig) {
 
 export function makeWorkflowsNamespace(config: HttpClientConfig) {
   return {
-    /** GET /@<slug>/workflows — list workflows (cursor pagination per ch01 §6.4). */
+    /** GET /@<slug>/workflows — list workflows (cursor pagination). */
     async list(filters?: WorkflowListFilters): Promise<Envelope<ReadonlyArray<Workflow>>> {
       const slug = requireProjectSlug(config);
       return request(config, { method: "GET", path: projectPath(slug, "workflows"), query: filters });
@@ -250,7 +250,7 @@ export function makeWorkflowsNamespace(config: HttpClientConfig) {
 
     /**
      * 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: string, triggerContext: Record<string, unknown> = {}): Promise<Envelope<WorkflowRun>> {

package/src/types.ts

@@ -25,11 +25,10 @@
  *   - `baseUrl` — gateway host root (scheme + host; no path). **Optional**;
  *     defaults to the platform apex `https://api.k9o.io`.
  *     When it is the bare apex and `orgSlug` is set, the SDK composes the
- *     canonical org subdomain `https://<orgSlug>.api.k9o.io` (ch01 §5.4 / ch13
- *     §7.1). Pass an explicit host to override — an explicit `<orgSlug>` subdomain,
+ *     canonical org subdomain `https://<orgSlug>.api.k9o.io`. Pass an explicit host to override — an explicit `<orgSlug>` subdomain,
  *     or a self-hosted / Sovereign-Control host, or a dev host — used as-is.
  *   - `fetch` — custom fetch implementation (defaults to global)
- *   - `retryConfig` — retry/backoff config (reserved; v0.1.0 ships single-attempt)
+ *   - `retryConfig` — retry/backoff config (reserved; currently ships single-attempt)
  *   - `defaultHeaders` — headers merged into every request
  */
 export type CreateClientOptions = {
@@ -43,9 +42,8 @@ export type CreateClientOptions = {
 };
 
 /**
- * Retry config per ch13 §7.1. v0.1.0 reserves the type; the HTTP client
- * ships single-attempt and will honour this config in a subsequent
- * sub-cycle.
+ * Retry config. The type is reserved; the HTTP client currently makes a
+ * single attempt per request and does not yet honour this config.
  */
 export type RetryConfig = {
   maxRetries: number;

package/src/url-grammar.ts

@@ -1,5 +1,5 @@
 /**
- * URL grammar v2.5.68.
+ * URL grammar.
  *
  * Canonical URL shapes:
  *   - Member-plane (project-scoped): `<orgSlug>.api.k9o.io/@<projectSlug>/<sub-resource>/...`
@@ -7,8 +7,8 @@
  *   - Platform-plane (cross-org):    `api.k9o.io/discovery/...` + `api.k9o.io/auth/...` etc.
  *
  * The `baseUrl` passed to `createClient` is the gateway host root —
- * scheme + host (+ optional port) per ch13 §7. Path-bearing baseUrls
- * are rejected with `K9O_INVALID_BASE_URL` per ch13 §7.2.
+ * scheme + host (+ optional port). Path-bearing baseUrls
+ * are rejected with `K9O_INVALID_BASE_URL`.
  *
  * The SDK constructs URLs by composing `baseUrl + path-from-builder`.
  * Per-resource SDK methods use the builders below to assemble their
@@ -18,7 +18,7 @@
 import { KError } from "./kerror.ts";
 
 /**
- * Validate a `baseUrl` per ch13 §7.2. Returns the normalised form
+ * Validate a `baseUrl`. Returns the normalised form
  * (trailing-slash stripped) on success; throws `K9O_INVALID_BASE_URL`
  * on any violation.
  *
@@ -94,7 +94,7 @@ const K9O_ORG_DERIVABLE_APEXES = new Set(["api.k9o.io", "api-staging.k9o.io"]);
  * OPTIONAL — it defaults to the platform apex `https://api.k9o.io`. When the
  * (validated) host is a bare apex in `K9O_ORG_DERIVABLE_APEXES` and `orgSlug`
  * is supplied, the SDK composes the canonical org-subdomain wire root
- * `https://<orgSlug>.<apex>` (ch01 §5.4). An explicit `<orgSlug>` subdomain, a
+ * `https://<orgSlug>.<apex>`. An explicit `<orgSlug>` subdomain, a
  * self-hosted / Sovereign host, or a dev host (anything not in that set)
  * passes through unchanged — `orgSlug` is intentionally NOT validated or
  * composed onto a non-apex host (fixed 2026-08-30: this used to silently
@@ -131,7 +131,7 @@ export function validateSlug(slug: string, kind: "org" | "project"): void {
 }
 
 /**
- * Build a project-scoped (member-plane) URL path per v2.5.68 §5.4.
+ * Build a project-scoped (member-plane) URL path per the URL grammar
  * E.g. `projectPath('member-portal', 'collections/posts/documents')`
  *      → `/@member-portal/collections/posts/documents`.
  *

package/dist/chunk-2VSTF5UU.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/kerror.ts"],"sourcesContent":["/**\n * `KError` — the closed-taxonomy error class returned by every `@k9o/core`\n * surface on non-2xx gateway responses or SDK-side validation failures.\n *\n * TypeScript / JavaScript throw on error; the per-language SDKs deliver this same payload\n * via their idiomatic mechanism (Go tuple-return; Rust Result; Python\n * raise; etc.) without changing the field shape.\n *\n * Fields:\n *   - `code`     — closed-taxonomy string (e.g. `K9O_TIER_CAP_HIT`,\n *                  `K9O_PROJECT_NOT_FOUND`); unknown codes pass through\n *                  with `code` preserved + `INTERNAL_ERROR` family\n *                  classification recorded in `context.originalCode`.\n *   - `message`  — human-readable explanation.\n *   - `context`  — structured per-code payload (immutable; frozen).\n *   - `recommendation` — actionable next step (may be null when the\n *                  gateway didn't return one).\n *   - `status`   — HTTP status the gateway returned (or null for\n *                  SDK-side construct-time errors like\n *                  `K9O_INVALID_BASE_URL` per ch13 §7.2).\n *   - `requestId` — gateway-emitted trace ID for downstream correlation.\n *\n * Standalone `@k9o/gate` ships its own `GateError` for the Auth0-parity\n * deployment shape; when `@k9o/gate` is composed inside `@k9o/core`,\n * `GateError` semantics align with `KError extends KError` (alignment still open).\n * Until then `KError` is the canonical error type returned by `@k9o/core` surfaces; `GateError` thrown by\n * `@k9o/gate`-delegated surfaces remain `KError`-shape-compatible\n * (both expose the same `code` / `message` / `context` / `recommendation`\n * fields) so caller code that narrows on `code` works against either.\n */\n\n/**\n * Wire-shape sentinel matching the gateway's `KError` JSON payload. The HTTP client recognises this on non-2xx responses\n * and rehydrates it into a `KError` instance.\n */\nexport type KErrorWire = {\n  code: string;\n  message: string;\n  context?: Record<string, unknown>;\n  recommendation?: string | null;\n  requestId?: string;\n};\n\n/**\n * The customer-facing error type. Every `@k9o/core` surface throws this\n * on non-2xx upstream responses, transport failures, or SDK-side\n * validation failures.\n */\nexport class KError extends Error {\n  readonly code: string;\n  readonly context: Readonly<Record<string, unknown>>;\n  readonly recommendation: string | null;\n  readonly status: number | null;\n  readonly requestId: string | null;\n\n  constructor(init: {\n    code: string;\n    message: string;\n    context?: Record<string, unknown>;\n    recommendation?: string | null;\n    status?: number | null;\n    requestId?: string | null;\n  }) {\n    super(init.message);\n    this.name = \"KError\";\n    this.code = init.code;\n    this.context = Object.freeze({ ...(init.context ?? {}) });\n    this.recommendation = init.recommendation ?? null;\n    this.status = init.status ?? null;\n    this.requestId = init.requestId ?? null;\n  }\n}\n\n/**\n * Rehydrate a wire `KError` payload into a typed `KError` instance.\n * Unlike `@k9o/gate.gateErrorFromWire`, `@k9o/core` does not maintain\n * a hand-curated allow-list of known codes — the gateway's KError\n * code-space is open-ended and curated centrally per ch11; the SDK\n * preserves whatever code the gateway sends. Code-narrowing in caller\n * code uses string-literal comparison against the well-known codes\n * (e.g. `if (e.code === 'K9O_TIER_CAP_HIT')`).\n */\nexport function kerrorFromWire(wire: KErrorWire, status: number): KError {\n  return new KError({\n    code: wire.code,\n    message: wire.message,\n    context: wire.context ?? {},\n    recommendation: wire.recommendation ?? null,\n    status,\n    requestId: wire.requestId ?? null,\n  });\n}\n"],"mappings":";AAgDO,IAAM,SAAN,cAAqB,MAAM;AAAA,EACvB;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAET,YAAY,MAOT;AACD,UAAM,KAAK,OAAO;AAClB,SAAK,OAAO;AACZ,SAAK,OAAO,KAAK;AACjB,SAAK,UAAU,OAAO,OAAO,EAAE,GAAI,KAAK,WAAW,CAAC,EAAG,CAAC;AACxD,SAAK,iBAAiB,KAAK,kBAAkB;AAC7C,SAAK,SAAS,KAAK,UAAU;AAC7B,SAAK,YAAY,KAAK,aAAa;AAAA,EACrC;AACF;AAWO,SAAS,eAAe,MAAkB,QAAwB;AACvE,SAAO,IAAI,OAAO;AAAA,IAChB,MAAM,KAAK;AAAA,IACX,SAAS,KAAK;AAAA,IACd,SAAS,KAAK,WAAW,CAAC;AAAA,IAC1B,gBAAgB,KAAK,kBAAkB;AAAA,IACvC;AAAA,IACA,WAAW,KAAK,aAAa;AAAA,EAC/B,CAAC;AACH;","names":[]}

package/dist/chunk-FVWKL5UQ.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/retry.ts","../src/region.ts","../src/http.ts"],"sourcesContent":["/**\n * Retry + backoff for the HTTP client.\n *\n * Configured via `retryConfig: { maxRetries, backoff }`. Retries are\n * scoped to transient failures only — never retry on KError-carrying\n * non-2xx responses (those are semantic; the caller must handle them).\n *\n * Retryable conditions (transient; safe to retry idempotently):\n *   - Transport error (`K9O_UPSTREAM_UNAVAILABLE` from `request()`) — network down,\n *     DNS fail, connection refused, etc.\n *   - HTTP 502 / 503 / 504 (gateway-up but downstream unavailable)\n *   - HTTP 429 with `Retry-After` header (rate-limit; backoff by header value)\n *\n * Non-retryable (semantic; caller must handle):\n *   - HTTP 4xx other than 429 (caller bug; retry won't help)\n *   - HTTP 5xx other than 502/503/504 (gateway-side bug; surface immediately)\n *   - KError on success-shape (rare; malformed envelope)\n *\n * Retry method discipline: only GET / HEAD / OPTIONS / DELETE are\n * retried by default — these are RFC-7231 idempotent. POST / PATCH /\n * PUT are NOT retried (caller can opt in via `idempotencyKey` header\n * per ch01 §10.2 when they assert idempotency).\n *\n * Backoff:\n *   - `exponential` (default) — `initialDelayMs * 2^attempt`, capped at maxDelayMs; jittered ±25%\n *   - `linear` — `initialDelayMs * (attempt + 1)`, capped at maxDelayMs; jittered ±25%\n *   - `none` — no delay between attempts\n */\n\nimport { KError } from \"./kerror.ts\";\nimport type { RetryConfig } from \"./types.ts\";\n\nconst RETRYABLE_METHODS = new Set([\"GET\", \"HEAD\", \"OPTIONS\", \"DELETE\"]);\nconst RETRYABLE_STATUS = new Set([502, 503, 504]);\n\nexport const DEFAULT_RETRY_CONFIG: Required<RetryConfig> = {\n  maxRetries: 3,\n  backoff: \"exponential\",\n  initialDelayMs: 100,\n  maxDelayMs: 5000,\n};\n\n/**\n * Decide if a thrown error is retryable.\n * Only KError instances are inspected; other thrown values propagate\n * (programmer error / unrecoverable state).\n */\nexport function isRetryable(error: unknown, method: string): boolean {\n  if (!RETRYABLE_METHODS.has(method.toUpperCase())) return false;\n  if (!(error instanceof KError)) return false;\n  if (error.code === \"K9O_UPSTREAM_UNAVAILABLE\") return true;\n  if (error.status !== null && RETRYABLE_STATUS.has(error.status)) return true;\n  if (error.status === 429) return true; // rate-limit; respect Retry-After if surfaced in context\n  return false;\n}\n\n/**\n * Compute the backoff delay for a given attempt index (0-based).\n */\nexport function computeDelay(config: Required<RetryConfig>, attempt: number): number {\n  let base: number;\n  if (config.backoff === \"none\") return 0;\n  if (config.backoff === \"linear\") base = config.initialDelayMs * (attempt + 1);\n  else base = config.initialDelayMs * Math.pow(2, attempt);\n  const capped = Math.min(base, config.maxDelayMs);\n  // ±25% jitter\n  const jitter = capped * 0.25 * (Math.random() * 2 - 1);\n  return Math.max(0, Math.floor(capped + jitter));\n}\n\n/**\n * Sleep helper. Pulled out so tests can stub it via injection.\n */\nexport function sleep(ms: number): Promise<void> {\n  return new Promise((resolve) => setTimeout(resolve, ms));\n}\n\n/**\n * Execute a function with retry. The function is called up to\n * `maxRetries + 1` times; non-retryable failures throw immediately.\n *\n * @param fn - The function to execute (typically the HTTP request)\n * @param method - HTTP method (used to gate retry per RETRYABLE_METHODS)\n * @param config - Retry config; defaults applied if partial\n * @param sleepImpl - Sleep implementation (tests inject a no-op or fast variant)\n */\nexport async function withRetry<T>(\n  fn: () => Promise<T>,\n  method: string,\n  config: RetryConfig | undefined,\n  sleepImpl: (ms: number) => Promise<void> = sleep,\n): Promise<T> {\n  const c: Required<RetryConfig> = {\n    ...DEFAULT_RETRY_CONFIG,\n    ...(config ?? {}),\n  };\n  let lastError: unknown;\n  for (let attempt = 0; attempt <= c.maxRetries; attempt++) {\n    try {\n      return await fn();\n    } catch (e) {\n      lastError = e;\n      if (attempt === c.maxRetries) break;\n      if (!isRetryable(e, method)) break;\n      const delay = computeDelay(c, attempt);\n      if (delay > 0) await sleepImpl(delay);\n    }\n  }\n  throw lastError;\n}\n","/**\n * Regional host resolution lives in `@k9o/gate` (which `@k9o/core` composes), so the Gate client and the core client\n * share one implementation of the probe and of the `Location` validation. See `packages/gate/src/region.ts`.\n */\nexport { resolveRegionalOrigin, regionalOriginFromLocation, type RegionConfig } from \"@k9o/gate\";\n","/**\n * HTTP client abstraction for `@k9o/core`.\n *\n * Lifted + generalised from `@k9o/gate/client.ts` (the auth-pillar SDK's\n * proven pattern). This client is per-instance — `createClient` constructs\n * one bound to its config; per-call options merge into the bound defaults.\n *\n * Responsibilities:\n *   - URL construction against bound `baseUrl` + per-call `path` + query\n *   - Envelope unwrap on 2xx (rejects malformed envelopes as INTERNAL_ERROR)\n *   - KError rehydration on non-2xx\n *   - Bearer token injection (from per-call override OR bound default)\n *   - Project context header (`x-k9o-project-slug`) injection when bound\n *   - Retry with exponential backoff per RetryConfig (see retry.ts) — TBD\n *     in next sub-cycle; v0.1.0 ships single-attempt\n *\n * The client is intentionally minimal — per-resource SDK methods compose\n * the path + body + bearer themselves and hand to `request()`. This keeps\n * the HTTP layer dumb and the per-resource logic auditable.\n */\n\nimport { KError, kerrorFromWire, type KErrorWire } from \"./kerror.ts\";\nimport type { Envelope } from \"./envelope.ts\";\nimport { withRetry } from \"./retry.ts\";\nimport type { RetryConfig } from \"./types.ts\";\nimport { resolveRegionalOrigin } from \"./region.ts\";\n\n/**\n * Per-instance HTTP client config. Constructed by `createClient`; passed\n * to `request()` per call.\n */\nexport type HttpClientConfig = {\n  /** Normalised baseUrl (scheme + host); set via createClient. */\n  baseUrl: string;\n  /** Default bearer token (per-call override wins). */\n  apiKey?: string | undefined;\n  /** Active project slug — injected as `x-k9o-project-slug` header on every request. */\n  projectSlug?: string | undefined;\n  /** Active org slug — injected as `x-k9o-org-slug` header on every request. */\n  orgSlug?: string | undefined;\n  /** Custom fetch impl (defaults to globalThis.fetch); use for tests + non-standard runtimes. */\n  fetch?: typeof globalThis.fetch | undefined;\n  /** Default headers merged into every request. */\n  defaultHeaders?: Record<string, string> | undefined;\n  /** Retry config per ch13 §7.1; idempotent methods only (GET/HEAD/OPTIONS/DELETE) — applied when transport fails or upstream returns 502/503/504/429. */\n  retryConfig?: RetryConfig | undefined;\n};\n\n/**\n * Per-call request options.\n */\nexport type RequestInit = {\n  method: \"GET\" | \"POST\" | \"PUT\" | \"PATCH\" | \"DELETE\";\n  path: string;\n  body?: unknown;\n  /** Per-call bearer override (wins over config.apiKey). */\n  bearerToken?: string | undefined;\n  /** Per-call additional headers (merged with config.defaultHeaders + auth). */\n  headers?: Record<string, string> | undefined;\n  /** Per-call query params. */\n  query?: Record<string, string | number | boolean | undefined> | undefined;\n};\n\n/**\n * Issue a request against the gateway. Returns the unwrapped Envelope\n * on 2xx; throws KError on non-2xx, transport failures, or malformed\n * responses.\n */\nexport async function request<T>(\n  config: HttpClientConfig,\n  init: RequestInit,\n): Promise<Envelope<T>> {\n  return withRetry(() => requestOnce<T>(config, init), init.method, config.retryConfig);\n}\n\n/**\n * Single-attempt request implementation. `request` wraps this in\n * retry-with-backoff per `config.retryConfig`. Exported for tests that\n * want to bypass retry semantics.\n */\nexport async function requestOnce<T>(\n  config: HttpClientConfig,\n  init: RequestInit,\n): Promise<Envelope<T>> {\n  const fetchImpl = config.fetch ?? globalThis.fetch;\n  if (typeof fetchImpl !== \"function\") {\n    throw new KError({\n      code: \"K9O_INTERNAL_ERROR\",\n      message:\n        \"No fetch implementation available — pass {fetch} in createClient options for runtimes without a global fetch\",\n      context: {},\n      recommendation: \"Use Node 18+, Bun 1.1+, or a modern browser; otherwise supply a fetch polyfill via the fetch option.\",\n    });\n  }\n\n  const url = buildUrl(await resolveRegionalOrigin(config), init.path, init.query);\n  const headers: Record<string, string> = {\n    accept: \"application/json\",\n    ...(config.defaultHeaders ?? {}),\n    ...(config.projectSlug ? { \"x-k9o-project-slug\": config.projectSlug } : {}),\n    ...(config.orgSlug ? { \"x-k9o-org-slug\": config.orgSlug } : {}),\n    ...(init.headers ?? {}),\n  };\n  const bearer = init.bearerToken ?? config.apiKey;\n  if (typeof bearer === \"string\" && bearer.length > 0) {\n    headers[\"authorization\"] = `Bearer ${bearer}`;\n  }\n  const requestInit: Record<string, unknown> = {\n    method: init.method,\n    headers,\n  };\n  if (init.body !== undefined) {\n    if (typeof FormData !== \"undefined\" && init.body instanceof FormData) {\n      // Multipart: the runtime sets the content type (with its boundary); never JSON-encode it.\n      requestInit[\"body\"] = init.body;\n    } else {\n      headers[\"content-type\"] = \"application/json\";\n      requestInit[\"body\"] = JSON.stringify(init.body);\n    }\n  }\n\n  let response: Response;\n  try {\n    response = await fetchImpl(url, requestInit as Parameters<typeof fetchImpl>[1]);\n  } catch (e) {\n    throw new KError({\n      code: \"K9O_UPSTREAM_UNAVAILABLE\",\n      message: `Network error reaching ${url}: ${e instanceof Error ? e.message : String(e)}`,\n      context: { url },\n      recommendation: \"Check connectivity to the gateway; retry with backoff if transient.\",\n    });\n  }\n\n  // 204 No Content — synthesize an empty envelope (some DELETE / PUT endpoints).\n  if (response.status === 204) {\n    return { data: undefined as unknown as T, meta: {} };\n  }\n\n  let parsed: unknown;\n  try {\n    parsed = await response.json();\n  } catch (e) {\n    throw new KError({\n      code: \"K9O_INTERNAL_ERROR\",\n      message: `Failed to parse JSON response from ${url}: ${e instanceof Error ? e.message : String(e)}`,\n      context: { url, status: response.status },\n      status: response.status,\n    });\n  }\n\n  if (response.status >= 200 && response.status < 300) {\n    if (!isEnvelope<T>(parsed)) {\n      throw new KError({\n        code: \"K9O_INTERNAL_ERROR\",\n        message: `Malformed envelope from ${url}: expected {data, meta}`,\n        context: { url, status: response.status },\n        status: response.status,\n      });\n    }\n    return parsed;\n  }\n\n  if (isKErrorWire(parsed)) {\n    throw kerrorFromWire(parsed, response.status);\n  }\n  throw new KError({\n    code: \"K9O_INTERNAL_ERROR\",\n    message: `Upstream returned ${response.status} with non-KError body`,\n    context: { url, status: response.status, body: parsed },\n    status: response.status,\n  });\n}\n\n/**\n * Open a streaming request against the gateway. Returns the raw\n * `Response` on 2xx (caller consumes `response.body` as an SSE / chunked\n * stream); throws `KError` on non-2xx, transport failures, or a missing\n * body. Used by streaming surfaces — `client.compute.llms.invokeStream`\n * (ch07 §10.2) + `client.realtime.subscribe` SSE transport (ch07 §11.3).\n *\n * Unlike `request()`, this does NOT unwrap the JSON envelope or apply\n * retry — streaming responses are consumed incrementally and retry on a\n * half-consumed stream is unsafe.\n */\nexport async function requestStream(\n  config: HttpClientConfig,\n  init: RequestInit & { accept?: string },\n): Promise<Response> {\n  const fetchImpl = config.fetch ?? globalThis.fetch;\n  if (typeof fetchImpl !== \"function\") {\n    throw new KError({\n      code: \"K9O_INTERNAL_ERROR\",\n      message: \"No fetch implementation available — pass {fetch} in createClient options\",\n      context: {},\n      recommendation: \"Use Node 18+, Bun 1.1+, or a modern browser; otherwise supply a fetch polyfill via the fetch option.\",\n    });\n  }\n\n  const url = buildUrl(await resolveRegionalOrigin(config), init.path, init.query);\n  const headers: Record<string, string> = {\n    accept: init.accept ?? \"text/event-stream\",\n    ...(config.defaultHeaders ?? {}),\n    ...(config.projectSlug ? { \"x-k9o-project-slug\": config.projectSlug } : {}),\n    ...(config.orgSlug ? { \"x-k9o-org-slug\": config.orgSlug } : {}),\n    ...(init.headers ?? {}),\n  };\n  const bearer = init.bearerToken ?? config.apiKey;\n  if (typeof bearer === \"string\" && bearer.length > 0) {\n    headers[\"authorization\"] = `Bearer ${bearer}`;\n  }\n  const requestInit: Record<string, unknown> = { method: init.method, headers };\n  if (init.body !== undefined) {\n    headers[\"content-type\"] = \"application/json\";\n    requestInit[\"body\"] = JSON.stringify(init.body);\n  }\n\n  let response: Response;\n  try {\n    response = await fetchImpl(url, requestInit as Parameters<typeof fetchImpl>[1]);\n  } catch (e) {\n    throw new KError({\n      code: \"K9O_UPSTREAM_UNAVAILABLE\",\n      message: `Network error reaching ${url}: ${e instanceof Error ? e.message : String(e)}`,\n      context: { url },\n      recommendation: \"Check connectivity to the gateway; retry with backoff if transient.\",\n    });\n  }\n\n  if (response.status < 200 || response.status >= 300) {\n    let parsed: unknown = null;\n    try {\n      parsed = await response.json();\n    } catch {\n      /* non-JSON error body */\n    }\n    if (isKErrorWire(parsed)) throw kerrorFromWire(parsed, response.status);\n    throw new KError({\n      code: \"K9O_INTERNAL_ERROR\",\n      message: `Upstream returned ${response.status} opening stream`,\n      context: { url, status: response.status, body: parsed },\n      status: response.status,\n    });\n  }\n\n  if (response.body === null) {\n    throw new KError({\n      code: \"K9O_INTERNAL_ERROR\",\n      message: `Stream response from ${url} has no body`,\n      context: { url, status: response.status },\n      status: response.status,\n    });\n  }\n\n  return response;\n}\n\nfunction buildUrl(\n  baseUrl: string,\n  path: string,\n  query: RequestInit[\"query\"],\n): string {\n  const trimmedBase = baseUrl.endsWith(\"/\") ? baseUrl.slice(0, -1) : baseUrl;\n  const trimmedPath = path.startsWith(\"/\") ? path : `/${path}`;\n  let url = `${trimmedBase}${trimmedPath}`;\n  if (query !== undefined) {\n    const params = new URLSearchParams();\n    for (const [k, v] of Object.entries(query)) {\n      if (v !== undefined) params.set(k, String(v));\n    }\n    const qs = params.toString();\n    if (qs.length > 0) url += `?${qs}`;\n  }\n  return url;\n}\n\nfunction isEnvelope<T>(value: unknown): value is Envelope<T> {\n  if (value === null || typeof value !== \"object\") return false;\n  const v = value as { data?: unknown; meta?: unknown };\n  return \"data\" in v && \"meta\" in v && typeof v.meta === \"object\" && v.meta !== null;\n}\n\nfunction isKErrorWire(value: unknown): value is KErrorWire {\n  if (value === null || typeof value !== \"object\") return false;\n  const v = value as { code?: unknown; message?: unknown };\n  return typeof v.code === \"string\" && typeof v.message === \"string\";\n}\n"],"mappings":"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","names":[]}

package/dist/chunk-OE2MMUIG.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../src/url-grammar.ts"],"sourcesContent":["/**\n * URL grammar v2.5.68.\n *\n * Canonical URL shapes:\n *   - Member-plane (project-scoped): `<orgSlug>.api.k9o.io/@<projectSlug>/<sub-resource>/...`\n *   - Org-plane (org-scoped):        `<orgSlug>.api.k9o.io/<resource>/...`\n *   - Platform-plane (cross-org):    `api.k9o.io/discovery/...` + `api.k9o.io/auth/...` etc.\n *\n * The `baseUrl` passed to `createClient` is the gateway host root —\n * scheme + host (+ optional port) per ch13 §7. Path-bearing baseUrls\n * are rejected with `K9O_INVALID_BASE_URL` per ch13 §7.2.\n *\n * The SDK constructs URLs by composing `baseUrl + path-from-builder`.\n * Per-resource SDK methods use the builders below to assemble their\n * `path` argument before handing to the HTTP client.\n */\n\nimport { KError } from \"./kerror.ts\";\n\n/**\n * Validate a `baseUrl` per ch13 §7.2. Returns the normalised form\n * (trailing-slash stripped) on success; throws `K9O_INVALID_BASE_URL`\n * on any violation.\n *\n * Accepted shapes:\n *   - `https://api.k9o.io`\n *   - `https://acme.api.k9o.io`\n *   - `http://localhost:8080`\n *   - `https://api.k9o.io:443`\n *\n * Rejected shapes:\n *   - path segments (`https://api.k9o.io/v2`)\n *   - missing scheme (`api.k9o.io`)\n *   - non-http(s) scheme (`wss://api.k9o.io`)\n *   - query / fragment (`https://api.k9o.io?x=1`)\n */\nexport function validateBaseUrl(baseUrl: string): string {\n  let parsed: URL;\n  try {\n    parsed = new URL(baseUrl);\n  } catch {\n    throw new KError({\n      code: \"K9O_INVALID_BASE_URL\",\n      message: `baseUrl \"${baseUrl}\" is not a valid URL`,\n      context: { baseUrl },\n      recommendation: \"Pass a scheme + host like `https://api.k9o.io` or `https://<orgSlug>.api.k9o.io`\",\n      status: null,\n    });\n  }\n  if (parsed.protocol !== \"http:\" && parsed.protocol !== \"https:\") {\n    throw new KError({\n      code: \"K9O_INVALID_BASE_URL\",\n      message: `baseUrl \"${baseUrl}\" uses unsupported scheme \"${parsed.protocol}\"; expected http: or https:`,\n      context: { baseUrl, scheme: parsed.protocol },\n      recommendation: \"Use http:// or https://. WebSocket subscriptions are wired internally over SSE on the same host.\",\n      status: null,\n    });\n  }\n  if (parsed.pathname !== \"/\" && parsed.pathname !== \"\") {\n    throw new KError({\n      code: \"K9O_INVALID_BASE_URL\",\n      message: `baseUrl \"${baseUrl}\" must not contain a path segment; got \"${parsed.pathname}\"`,\n      context: { baseUrl, path: parsed.pathname },\n      recommendation: \"Strip the path segment — pass host only. URL paths are composed by the SDK.\",\n      status: null,\n    });\n  }\n  if (parsed.search.length > 0 || parsed.hash.length > 0) {\n    throw new KError({\n      code: \"K9O_INVALID_BASE_URL\",\n      message: `baseUrl \"${baseUrl}\" must not contain query or fragment`,\n      context: { baseUrl, query: parsed.search, fragment: parsed.hash },\n      recommendation: \"Pass host only.\",\n      status: null,\n    });\n  }\n  // Normalise — strip trailing slash so concatenation is predictable.\n  const normalised = `${parsed.protocol}//${parsed.host}`;\n  return normalised;\n}\n\n/**\n * The bare platform apex hosts org-subdomain derivation applies to. `api.k9o.io`\n * (production) and `api-staging.k9o.io` (staging) share the same\n * `<orgSlug>.<apex>` wire-routing scheme — confirmed live (conformance,\n * `k9o login` examples, staging demo configs all address orgs this way on\n * both). A THIRD apex here needs the same confirmation before joining this\n * set — never inferred from a hostname merely looking apex-shaped.\n */\nconst K9O_ORG_DERIVABLE_APEXES = new Set([\"api.k9o.io\", \"api-staging.k9o.io\"]);\n\n/**\n * Resolve the effective baseUrl. `baseUrl` is\n * OPTIONAL — it defaults to the platform apex `https://api.k9o.io`. When the\n * (validated) host is a bare apex in `K9O_ORG_DERIVABLE_APEXES` and `orgSlug`\n * is supplied, the SDK composes the canonical org-subdomain wire root\n * `https://<orgSlug>.<apex>` (ch01 §5.4). An explicit `<orgSlug>` subdomain, a\n * self-hosted / Sovereign host, or a dev host (anything not in that set)\n * passes through unchanged — `orgSlug` is intentionally NOT validated or\n * composed onto a non-apex host (fixed 2026-08-30: this used to silently\n * ignore `orgSlug` for `api-staging.k9o.io` too, not just genuine\n * self-hosted/custom hosts, since only the literal production apex string\n * was checked).\n */\nexport function resolveBaseUrl(baseUrl: string | undefined, orgSlug?: string): string {\n  const validated = validateBaseUrl(baseUrl ?? \"https://api.k9o.io\");\n  const parsed = new URL(validated);\n  if (K9O_ORG_DERIVABLE_APEXES.has(parsed.hostname) && orgSlug) {\n    validateSlug(orgSlug, \"org\");\n    return `${parsed.protocol}//${orgSlug}.${parsed.hostname}`;\n  }\n  return validated;\n}\n\n/**\n * Slug format validator:\n *   `[a-z][a-z0-9-]{1,62}` and must not end with `-`.\n */\nconst SLUG_RE = /^[a-z][a-z0-9-]{1,62}$/;\n\nexport function validateSlug(slug: string, kind: \"org\" | \"project\"): void {\n  if (!SLUG_RE.test(slug) || slug.endsWith(\"-\")) {\n    throw new KError({\n      code: \"K9O_INVALID_FIELD_VALUE\",\n      message: `${kind}Slug \"${slug}\" does not match required format ^[a-z][a-z0-9-]{1,62}$ (must not end with '-')`,\n      context: { slug, kind },\n      recommendation: `Pass a slug matching the format — lowercase letters / digits / hyphens; 2-63 chars; starts with a letter; does not end with hyphen.`,\n      status: null,\n    });\n  }\n}\n\n/**\n * Build a project-scoped (member-plane) URL path per v2.5.68 §5.4.\n * E.g. `projectPath('member-portal', 'collections/posts/documents')`\n *      → `/@member-portal/collections/posts/documents`.\n *\n * The caller is responsible for normalising sub-resource components\n * (URL-encoding goes through the caller's path construction; this\n * helper handles only the prefix + slug shape).\n */\nexport function projectPath(projectSlug: string, subResource: string): string {\n  validateSlug(projectSlug, \"project\");\n  const cleaned = subResource.startsWith(\"/\") ? subResource.slice(1) : subResource;\n  return `/@${projectSlug}/${cleaned}`;\n}\n\n/**\n * Build an org-plane path. E.g. `orgPath('org')` → `/org`,\n * `orgPath('projects')` → `/projects`.\n */\nexport function orgPath(resource: string): string {\n  const cleaned = resource.startsWith(\"/\") ? resource.slice(1) : resource;\n  return `/${cleaned}`;\n}\n\n/**\n * Build a platform-plane path (cross-org). E.g.\n * `platformPath('discovery/projects')` → `/discovery/projects`,\n * `platformPath('auth/sign-in')` → `/auth/sign-in`.\n *\n * Composes with the platform baseUrl (`https://api.k9o.io`) — not the\n * org-subdomain baseUrl.\n */\nexport function platformPath(resource: string): string {\n  const cleaned = resource.startsWith(\"/\") ? resource.slice(1) : resource;\n  return `/${cleaned}`;\n}\n"],"mappings":";;;;;AAoCO,SAAS,gBAAgB,SAAyB;AACvD,MAAI;AACJ,MAAI;AACF,aAAS,IAAI,IAAI,OAAO;AAAA,EAC1B,QAAQ;AACN,UAAM,IAAI,OAAO;AAAA,MACf,MAAM;AAAA,MACN,SAAS,YAAY,OAAO;AAAA,MAC5B,SAAS,EAAE,QAAQ;AAAA,MACnB,gBAAgB;AAAA,MAChB,QAAQ;AAAA,IACV,CAAC;AAAA,EACH;AACA,MAAI,OAAO,aAAa,WAAW,OAAO,aAAa,UAAU;AAC/D,UAAM,IAAI,OAAO;AAAA,MACf,MAAM;AAAA,MACN,SAAS,YAAY,OAAO,8BAA8B,OAAO,QAAQ;AAAA,MACzE,SAAS,EAAE,SAAS,QAAQ,OAAO,SAAS;AAAA,MAC5C,gBAAgB;AAAA,MAChB,QAAQ;AAAA,IACV,CAAC;AAAA,EACH;AACA,MAAI,OAAO,aAAa,OAAO,OAAO,aAAa,IAAI;AACrD,UAAM,IAAI,OAAO;AAAA,MACf,MAAM;AAAA,MACN,SAAS,YAAY,OAAO,2CAA2C,OAAO,QAAQ;AAAA,MACtF,SAAS,EAAE,SAAS,MAAM,OAAO,SAAS;AAAA,MAC1C,gBAAgB;AAAA,MAChB,QAAQ;AAAA,IACV,CAAC;AAAA,EACH;AACA,MAAI,OAAO,OAAO,SAAS,KAAK,OAAO,KAAK,SAAS,GAAG;AACtD,UAAM,IAAI,OAAO;AAAA,MACf,MAAM;AAAA,MACN,SAAS,YAAY,OAAO;AAAA,MAC5B,SAAS,EAAE,SAAS,OAAO,OAAO,QAAQ,UAAU,OAAO,KAAK;AAAA,MAChE,gBAAgB;AAAA,MAChB,QAAQ;AAAA,IACV,CAAC;AAAA,EACH;AAEA,QAAM,aAAa,GAAG,OAAO,QAAQ,KAAK,OAAO,IAAI;AACrD,SAAO;AACT;AAUA,IAAM,2BAA2B,oBAAI,IAAI,CAAC,cAAc,oBAAoB,CAAC;AAetE,SAAS,eAAe,SAA6B,SAA0B;AACpF,QAAM,YAAY,gBAAgB,WAAW,oBAAoB;AACjE,QAAM,SAAS,IAAI,IAAI,SAAS;AAChC,MAAI,yBAAyB,IAAI,OAAO,QAAQ,KAAK,SAAS;AAC5D,iBAAa,SAAS,KAAK;AAC3B,WAAO,GAAG,OAAO,QAAQ,KAAK,OAAO,IAAI,OAAO,QAAQ;AAAA,EAC1D;AACA,SAAO;AACT;AAMA,IAAM,UAAU;AAET,SAAS,aAAa,MAAc,MAA+B;AACxE,MAAI,CAAC,QAAQ,KAAK,IAAI,KAAK,KAAK,SAAS,GAAG,GAAG;AAC7C,UAAM,IAAI,OAAO;AAAA,MACf,MAAM;AAAA,MACN,SAAS,GAAG,IAAI,SAAS,IAAI;AAAA,MAC7B,SAAS,EAAE,MAAM,KAAK;AAAA,MACtB,gBAAgB;AAAA,MAChB,QAAQ;AAAA,IACV,CAAC;AAAA,EACH;AACF;AAWO,SAAS,YAAY,aAAqB,aAA6B;AAC5E,eAAa,aAAa,SAAS;AACnC,QAAM,UAAU,YAAY,WAAW,GAAG,IAAI,YAAY,MAAM,CAAC,IAAI;AACrE,SAAO,KAAK,WAAW,IAAI,OAAO;AACpC;AAMO,SAAS,QAAQ,UAA0B;AAChD,QAAM,UAAU,SAAS,WAAW,GAAG,IAAI,SAAS,MAAM,CAAC,IAAI;AAC/D,SAAO,IAAI,OAAO;AACpB;AAUO,SAAS,aAAa,UAA0B;AACrD,QAAM,UAAU,SAAS,WAAW,GAAG,IAAI,SAAS,MAAM,CAAC,IAAI;AAC/D,SAAO,IAAI,OAAO;AACpB;","names":[]}