@kortexya/reasoninglayer 1.27.0 → 1.28.0

package/dist/index.cjs

@@ -7,7 +7,7 @@ var __export = (target, all) => {
 };
 
 // src/config.ts
-var SDK_VERSION = "1.27.0";
+var SDK_VERSION = "1.28.0";
 function resolveConfig(config) {
   if (!config.baseUrl) {
     throw new Error("ClientConfig.baseUrl is required");
@@ -102,6 +102,20 @@ var ConstraintViolationError = class extends ApiError {
     this.constraint = constraint;
   }
 };
+var BulkRefusedError = class extends ApiError {
+  name = "BulkRefusedError";
+  /**
+   * The refused rows, each naming its index in the request's `terms` array.
+   *
+   * @remarks
+   * Never empty — the engine answers this shape only when it refused something.
+   */
+  rows;
+  constructor(message, body, headers, rows, errorCode) {
+    super(message, 422, body, headers, errorCode);
+    this.rows = rows;
+  }
+};
 var RateLimitError = class extends ApiError {
   name = "RateLimitError";
   /** Seconds to wait before retrying, or null if not specified. */
@@ -191,6 +205,13 @@ function createApiError(status, body, headers) {
         constraint
       );
     }
+    case 422: {
+      const rows = bulkRefusalRows(body);
+      if (rows !== null) {
+        return new BulkRefusedError(message, body, headers, rows, errorCode);
+      }
+      return new ApiError(message, status, body, headers, errorCode);
+    }
     case 429: {
       const rl = parseRateLimitHeaders(headers);
       return new RateLimitError(message, body, headers, errorCode, rl.retryAfter, rl.limit, rl.remaining);
@@ -207,6 +228,23 @@ function isErrorBody(body) {
   const obj = body;
   return typeof obj.error === "string" && typeof obj.message === "string";
 }
+function bulkRefusalRows(body) {
+  if (typeof body !== "object" || body === null) return null;
+  const obj = body;
+  if (!Array.isArray(obj.errors)) return null;
+  const rows = [];
+  for (const entry of obj.errors) {
+    if (typeof entry !== "object" || entry === null) return null;
+    const row = entry;
+    if (typeof row.index !== "number" || typeof row.message !== "string") return null;
+    rows.push({
+      index: row.index,
+      message: row.message,
+      ...typeof row.feature === "string" ? { feature: row.feature } : {}
+    });
+  }
+  return rows.length > 0 ? rows : null;
+}
 function isConstraintViolationBody(body) {
   if (!isErrorBody(body)) return false;
   if (!("details" in body)) return false;
@@ -1641,7 +1679,7 @@ var Terms = class {
     ...params
   });
   /**
-   * @description Creates multiple terms in a single operation for efficiency. This is optimized for high-volume data loading scenarios and skips individual witness validation (constraint propagation runs once at the end). # Performance - Terms are added to the domain store in a single lock acquisition - Constraint propagation runs once after all terms are added - Much faster than calling add_term N times # Declarations and all-or-nothing (#238, #239) Every entry is held to the same declarations as `POST /terms`, with the same `422`. One refusal — a declaration violation or a bound-constraint violation — refuses the WHOLE batch and puts the store and the facade back: fresh ids removed, coreferenced entities restored to their pre-batch description. A batch may reference the client-minted ids it is itself creating: the resolver is the resident store unioned with the batch's own ids. When such an id then coreferences through a `@key`, every designator of it in the same batch is rewritten to the entity it merged into — the reference names what the write actually produced, never an id the coreference removed. `term_ids` carries the EFFECTIVE id per request position — the created id, or the existing entity's id when the entry coreferenced through a `@key`. # Authorization Requires X-Tenant-Id header. The tenant_id is taken from the header.
+   * @description Creates multiple terms in a single operation for efficiency. This is optimized for high-volume data loading scenarios and skips individual witness validation (constraint propagation runs once at the end). # Performance - Terms are added to the domain store in a single lock acquisition - Constraint propagation runs once after all terms are added - Much faster than calling add_term N times # Declarations and all-or-nothing (#238, #239, #262) Every entry is held to the same declarations as `POST /terms`, with the same `422`. One refusal — a declaration violation or a bound-constraint violation — refuses the WHOLE batch and puts the store and the facade back: fresh ids removed, coreferenced entities restored to their pre-batch description. The refusal NAMES THE ROWS (#262): the body carries `errors[]`, one entry per refused row, each with its `index` in the request's `terms` array and the `feature` the refusal is about when it names one, so a client repairs the exact rows it sent instead of guessing which one a single-message refusal meant. `partial: true` (#271) writes the rows the checks did NOT refuse instead of refusing the batch for one of them. A real import holding one bad record had to be resent minus that record — a second full call, a second full round of constraint evaluation, and a window in which a survivor's reference target can be deleted between the two — although the engine already names every bad entry by index in one pass and therefore already knows which ones were fine. The answer is `201` when anything was written, with `term_ids` carrying one id per ACCEPTED row and the same `errors[]` beside it; `422` when every row was refused, because nothing was written and that is a refusal. ⛔ Two failures stay batch-wide under `partial`, because neither can be attributed to a row, and the flag does not pretend otherwise: the end-of-batch constraint propagation answers ONE `409` for the whole batch (`facade.process_events`), and a persistence failure reverts what the batch inserted (#239). `dry_run: true` (#262) runs every check the real write runs — conversion, declarations, coreference, events — and writes nothing: the store and the facade are put back inside the write lock, nothing persists, nothing is notified, no derivation is queued. A clean dry run answers `200` with the count the batch would have produced and NO `term_ids` (#268): the rollback has already discarded every id it minted for a fresh entry, and a second, real POST of the same body mints different ones — so the vector named nothing, in the very positions the field documents as storable. The ids that DO outlive a dry run are the entities a `@key` coreference would have merged into, and those are answered separately as `coreferenced_term_ids`. A refused dry run answers the same `errors[]` body the real write answers with. A batch may reference the client-minted ids it is itself creating: the resolver is the resident store unioned with the batch's own ids. When such an id then coreferences through a `@key`, every designator of it in the same batch is rewritten to the entity it merged into — the reference names what the write actually produced, never an id the coreference removed. On a real write `term_ids` carries the EFFECTIVE id per request position — the created id, or the existing entity's id when the entry coreferenced through a `@key`. It is ABSENT on a dry run. # Authorization Requires X-Tenant-Id header. The tenant_id is taken from the header.
    *
    * @tags terms
    * @name BulkAddTerms
@@ -1939,7 +1977,7 @@ var Inference = class {
     ...params
   });
   /**
-   * @description This drops the hydrated base facts, the forward-chain `persist_derived` facts and the residuation store, then forgets the hydration flag so the next request reloads the base facts from PostgreSQL. **It does not delete durable data.** The terms are the authority; this is their cache. That makes it the retraction primitive forward chaining otherwise lacks. Chaining is monotonic — delete a `blocks` edge and the derived "A blocks B" survives every later pass, so the KB keeps asserting a relationship the user removed. Clearing and re-chaining rebuilds the closure from the terms that actually exist. # History Until 2026-07-28 this handler enumerated every term in the tenant and deleted it from PostgreSQL, while calling itself "clear facts" and reporting `"Cleared N facts/rules"`. It is reachable with an ordinary tenant credential — unlike `/api/v1/admin/clear-tenant/{tenant_id}`, which gateways block — so a caller reading the name, the path or the response body had no way to know it was a tenant wipe. It destroyed a live tenant that way. Use `DELETE /api/v1/terms/{term_id}` to delete a term, and the admin route to wipe a tenant; deleting durable data must not be something an endpoint does as a side effect of its name. # Authorization Requires X-Tenant-Id header, and the path tenant must match it.
+   * @description This drops the hydrated base facts, the forward-chain `keep_derived` facts and the residuation store, then forgets the hydration flag so the next request reloads the base facts from PostgreSQL. **It does not delete durable data.** The terms are the authority; this is their cache. That makes it the retraction primitive forward chaining otherwise lacks. Chaining is monotonic — delete a `blocks` edge and the derived "A blocks B" survives every later pass, so the KB keeps asserting a relationship the user removed. Clearing and re-chaining rebuilds the closure from the terms that actually exist. # History Until 2026-07-28 this handler enumerated every term in the tenant and deleted it from PostgreSQL, while calling itself "clear facts" and reporting `"Cleared N facts/rules"`. It is reachable with an ordinary tenant credential — unlike `/api/v1/admin/clear-tenant/{tenant_id}`, which gateways block — so a caller reading the name, the path or the response body had no way to know it was a tenant wipe. It destroyed a live tenant that way. Use `DELETE /api/v1/terms/{term_id}` to delete a term, and the admin route to wipe a tenant; deleting durable data must not be something an endpoint does as a side effect of its name. # Authorization Requires X-Tenant-Id header, and the path tenant must match it.
    *
    * @tags inference
    * @name ClearFacts
@@ -6681,7 +6719,7 @@ var Query = class {
     this.http = http;
   }
   /**
-   * @description Returns all terms with the specified sort OR any of its subtypes. This implements proper OSF polymorphic query semantics where querying a parent sort returns all instances of that sort and its descendants. ## Resolving `sort_name` A name can denote more than one id (see `sort_name_candidates`), and no cheap probe tells which of them the query can actually answer from: on the production adapter `get_sort` and `get_sort_ids_by_names` are bare reads of an in-memory cache with no persistence fallback, while the query's own `get_compatible_sorts` does fall back to Postgres. Confirming a candidate with `get_sort` would therefore 404 every tenant sort created before the last restart — a guard strictly stricter than the thing it guards. So the candidates are **tried** against the real query; only `SortNotFound` moves on to the next, every other failure is returned as-is. A phantom id (minted into the tenant lattice by ingestion and never persisted, #138) cannot be returned: the query authority refuses it and the loop skips past it. When no candidate answers, the sort is not queryable and the honest reply is 404 naming the sort the CALLER asked for — never a 400 leaking an internal `SortId` the caller never supplied. Every candidate that answers **contributes**; the answer is their union, deduplicated by term id. Registration now keeps a tenant to one sort per name (#139), so two answering candidates mean rows a pre-fix engine left behind: one name, two sorts, and the tenant's terms of that type divided between them. Stopping at the first — what this route did — returned one half and reported nothing about the other, because an id the caller never supplied going unqueried raises no error. In the ordinary case exactly one candidate answers and the route runs exactly one term query, as it always did.
+   * @description Returns all terms with the specified sort OR any of its subtypes. This implements proper OSF polymorphic query semantics where querying a parent sort returns all instances of that sort and its descendants. ## Resolving `sort_name` A name can denote more than one id (see `sort_name_candidates`), and no cheap probe tells which of them the query can actually answer from: on the production adapter `get_sort` and `get_sort_ids_by_names` are bare reads of an in-memory cache with no persistence fallback, while the query's own `get_compatible_sorts` does fall back to Postgres. Confirming a candidate with `get_sort` would therefore 404 every tenant sort created before the last restart — a guard strictly stricter than the thing it guards. So the candidates are **tried** against the real query; only `SortNotFound` moves on to the next, every other failure is returned as-is. A phantom id (minted into the tenant lattice by ingestion and never persisted, #138) cannot be returned: the query authority refuses it and the loop skips past it. When no candidate answers, the sort is not queryable and the honest reply is 404 naming the sort the CALLER asked for — never a 400 leaking an internal `SortId` the caller never supplied. Every candidate that answers **contributes**; the answer is their union, deduplicated by term id. Registration now keeps a tenant to one sort per name (#139), so two answering candidates mean rows a pre-fix engine left behind: one name, two sorts, and the tenant's terms of that type divided between them. Stopping at the first — what this route did — returned one half and reported nothing about the other, because an id the caller never supplied going unqueried raises no error. In the ordinary case exactly one candidate answers and the route runs exactly one term query, as it always did. ## Conclusions, and what this route promises The answer is the tenant's durable extension of the browse closure UNIONED with the conclusions this process currently HOLDS — the same set OSFQL `MATCH` reads. That is what makes a rule sort readable here at all: no OSFQL path persists a conclusion, so the durable half is empty for a sort whose members exist only by derivation (#261). This route does NOT chain. It reports what the last chain left, so: * after a restart the derived half is empty until something chains again — `CHAIN`, `PROVE`, a retraction's re-chain, or `POST /api/v1/inference/forward-chain`; * a conclusion whose premise was withdrawn through a door that runs no truth maintenance is still answered until the next chain (`docs/OPEN_DEFECTS.md` #82). `total` is the size of the answer before `offset`/`limit`, counted — never a search bound. Rows are ordered by term id, so a page is stable. When the answer is EMPTY and the browsed sort is a rule conclusion sort, `note` says so and names the routes that materialise the conclusions. A bare `total: 0` reads as an authoritative count, and for a rule sort in a freshly-started process it is the one answer a caller must not take at face value — the same confusion #261 was filed about, one state later.
    *
    * @tags query
    * @name FindBySort
@@ -9594,7 +9632,7 @@ var Admin = class {
     ...params
   });
   /**
-   * @description Truncates the derived_facts table for the given tenant and queues a BootstrapAll event covering every analyzed rule. Asynchronous: returns the queue depth and current materialization LSN, not the final state. Concurrent rebuilds for the same tenant are rejected with 409 (per-tenant mutex). Full operational runbook (prerequisites, timings, monitoring, failure recovery, known limitations) lives in .claude/SUB_MS_FORWARD_CHAINING_STATUS.md, section 'Operator runbook — derived-facts rebuild'.
+   * @description Re-materialises the tenant's conclusions SYNCHRONOUSLY: chains the resident store once, so every conclusion the rules prove and the store lacks comes back. `rematerialised` reports how many, and every read surface answers from that store — this is the one call that repairs a drifted tenant (#270). ONE DIRECTION: it does not remove a conclusion the rules no longer support, because the write doors' truth maintenance already does that on the write that changed the premise. It ALSO truncates the durable derived_facts table and queues a BootstrapAll event over every analyzed rule; that half is asynchronous, and `removed` / `rules_queued` / `materialization_lsn` describe it. Concurrent rebuilds for the same tenant are rejected with 409 (per-tenant mutex). Full operational runbook (prerequisites, timings, monitoring, failure recovery, known limitations) lives in .claude/SUB_MS_FORWARD_CHAINING_STATUS.md, section 'Operator runbook — derived-facts rebuild'.
    *
    * @tags admin
    * @name RebuildDerivedFacts
@@ -10040,6 +10078,24 @@ var Osfql = class {
     format: "json",
     ...params
   });
+  /**
+   * @description Takes the same body as `POST /api/v1/osfql` (the `query` matters; `atomic` decides whether the answer reports the atomic refusal) and answers: - `mutates` — whether ANY statement writes, folding every nested statement, so an `IF` whose THEN or ELSE branch writes reports `true`, and including an inline-write `MATCH` a first-statement classification would read as safe; - `atomic_refusal` — why the program cannot run as one atomic unit, with the same code the run would refuse with (`drop_sort_in_atomic_program`); - `statements` — one entry per statement with the ENGINE's classification (catalog id, risk tier, and a per-statement `mutates` — not a client-side tokenizer), the exact source text, the sorts named, nested entries for IF branches and `WITH` continuations, and — for each destructive statement — the affected-row count and up to 10 sample rows. The per-statement `mutates` is what a write gate reads: `CHAIN` and `RELEASE RESIDUATIONS` report `true` although they classify as `process_control`, while `MARK`, `CUT` and `SPACE` report `false`. No client has to keep its own table of which process-control statements write; `GET /api/v1/osfql/catalog` carries the same verdict per entry as `never` / `always` / `depends` (#266). The classification comes from the engine's own parse; the counts come from a read-only `MATCH` derived from the destructive statement's pattern and run against a CLONE of the tenant. Nothing runs against the live store, so nothing observable happens in the tenant afterwards. # Examples ```json { "query": "MATCH person(name: ?N); RETRACT person(name: \"Bob\");" } ``` ```json { "query": "DROP SORT person; INSERT person(name: \"Bob\");" } ```
+   *
+   * @tags osfql
+   * @name PreviewOsfql
+   * @summary Preview an OSFQL program: what each statement would do, decided without running anything (#257).
+   * @request POST:/api/v1/osfql/preview
+   * @secure
+   */
+  previewOsfql = (data, params = {}) => this.http.request({
+    path: `/api/v1/osfql/preview`,
+    method: "POST",
+    body: data,
+    secure: true,
+    type: "application/json",
+    format: "json",
+    ...params
+  });
 };
 
 // src/api-spec/generated/Context.ts
@@ -13229,6 +13285,45 @@ var Research = class {
   });
 };
 
+// src/normalizers/ontology-alignment.ts
+function AlignOntologyRequestFromFrontToApi(model) {
+  return {
+    domain_owl: model.domainOwl,
+    targets: model.targets
+  };
+}
+function AlignmentMatchDtoFromApiToFront(dto) {
+  return {
+    domainSort: dto.domain_sort,
+    matchType: dto.match_type,
+    targetCurie: dto.target_curie,
+    targetLabel: dto.target_label
+  };
+}
+function AlignmentConflictDtoFromApiToFront(dto) {
+  return {
+    domainSort: dto.domain_sort,
+    targetA: dto.target_a,
+    targetB: dto.target_b
+  };
+}
+function ExternalMatchDtoFromApiToFront(dto) {
+  return {
+    matchType: dto.match_type,
+    ontologyId: dto.ontology_id,
+    source: dto.source
+  };
+}
+function AlignOntologyResponseFromApiToFront(dto) {
+  return {
+    conflicts: dto.conflicts.map(AlignmentConflictDtoFromApiToFront),
+    domainSorts: dto.domain_sorts,
+    mappingTtl: dto.mapping_ttl,
+    matches: dto.matches.map(AlignmentMatchDtoFromApiToFront),
+    targetSorts: dto.target_sorts
+  };
+}
+
 // src/utils/records.ts
 function definedEntries(map) {
   return Object.entries(map).filter((entry) => entry[1] !== void 0);
@@ -13280,7 +13375,12 @@ function FeatureDescriptorDtoFromApiToFront(dto) {
     // `undefined` for a question the wire already answers.
     required: dto.required ?? false,
     constraint: dto.constraint ? ConstraintDtoFromApiToFront(dto.constraint) : void 0,
-    key: dto.key
+    key: dto.key,
+    expectedSortName: dto.expected_sort_name ?? void 0,
+    minCount: dto.min_count ?? void 0,
+    maxCount: dto.max_count ?? void 0,
+    cardinalityOrigin: dto.cardinality_origin ?? void 0,
+    annotations: definedRecord2(dto.annotations)
   };
 }
 function FeatureDescriptorDtoFromFrontToApi(model) {
@@ -13290,7 +13390,18 @@ function FeatureDescriptorDtoFromFrontToApi(model) {
     expected_type_hint: model.expectedTypeHint ?? void 0,
     required: model.required,
     constraint: model.constraint ? ConstraintDtoFromFrontToApi(model.constraint) : void 0,
-    key: model.key
+    key: model.key,
+    expected_sort_name: model.expectedSortName ?? void 0,
+    min_count: model.minCount ?? void 0,
+    max_count: model.maxCount ?? void 0,
+    cardinality_origin: model.cardinalityOrigin ?? void 0,
+    annotations: model.annotations
+  };
+}
+function CoextensiveDefinitionDtoFromApiToFront(dto) {
+  return {
+    definition: dto.definition,
+    exampleCount: dto.example_count
   };
 }
 function BoundConstraintDtoFromApiToFront(dto) {
@@ -13372,7 +13483,17 @@ function SortDtoFromApiToFront(dto) {
     worldMode: dto.world_mode,
     annotations: definedRecord2(dto.annotations),
     pluginId: dto.plugin_id ?? void 0,
-    pluginLocalName: dto.plugin_local_name ?? void 0
+    pluginLocalName: dto.plugin_local_name ?? void 0,
+    altLabels: dto.alt_labels,
+    hiddenLabels: dto.hidden_labels,
+    scopeNote: dto.scope_note ?? void 0,
+    related: dto.related,
+    definition: dto.definition ?? void 0,
+    coextensive: dto.coextensive?.map(CoextensiveDefinitionDtoFromApiToFront),
+    externalMatches: dto.external_matches?.map(
+      (match) => ExternalMatchDtoFromApiToFront(match)
+    ),
+    featureEquations: dto.feature_equations
   };
 }
 function SortInfoDtoFromApiToFront(dto) {
@@ -13384,7 +13505,20 @@ function SortInfoDtoFromApiToFront(dto) {
 function SortListResponseFromApiToFront(dto) {
   return {
     sorts: dto.sorts.map(SortDtoFromApiToFront),
-    count: dto.count
+    count: dto.count,
+    total: dto.total,
+    offset: dto.offset
+  };
+}
+function ListSortsQueryFromFrontToApi(query) {
+  if (query === void 0) return void 0;
+  return {
+    include_system: query.includeSystem,
+    limit: query.limit,
+    llm_extracted: query.llmExtracted,
+    name_prefix: query.namePrefix?.join(","),
+    needs_review: query.needsReview,
+    offset: query.offset
   };
 }
 function CreateSortRequestFromFrontToApi(model) {
@@ -13406,6 +13540,8 @@ function BulkSortDefinitionFromFrontToApi(model) {
     parents: model.parents,
     features: model.features?.map(FeatureDescriptorDtoFromFrontToApi),
     alt_labels: model.altLabels,
+    hidden_labels: model.hiddenLabels,
+    scope_note: model.scopeNote ?? void 0,
     description: model.description ?? void 0,
     world_mode: model.worldMode
   };
@@ -14015,13 +14151,60 @@ var SortsClient = class {
     return response.data;
   }
   /**
-   * List all sorts.
+   * List every sort the tenant owns.
+   *
+   * @param requestOptions - Per-call transport overrides.
+   * @returns The sorts, each with its feature declarations.
+   * @throws {ApiError} When the engine refuses the request.
+   *
+   * @remarks
+   * This asks for the whole listing and keeps only the array. A production
+   * tenant can own 1 M+ sorts (~500 MB uncompressed), which one response
+   * cannot deliver — use {@link SortsClient.listSortsPage} to window it, to
+   * filter it, or to read the `total` that says when to stop.
    *
-   * @returns Array of sorts.
+   * @example
+   * ```typescript
+   * const sorts = await client.sorts.listSorts();
+   * ```
    */
   async listSorts(requestOptions) {
-    const response = await this.sorts.listSorts(this.tenantId, void 0, toRequestParams(requestOptions));
-    return SortListResponseFromApiToFront(response.data).sorts;
+    return (await this.listSortsPage(void 0, requestOptions)).sorts;
+  }
+  /**
+   * List the tenant's sorts, keeping the envelope — `count`, `total` and
+   * `offset` beside the page.
+   *
+   * @param query - The window and filters over the listing.
+   * @param requestOptions - Per-call transport overrides.
+   * @returns The page, its length, the tenant's filtered total and the
+   *   offset the page starts at.
+   * @throws {ApiError} When the engine refuses the request.
+   *
+   * @remarks
+   * `count` is the length of THIS page; `total` is what the tenant owns after
+   * filters, across all pages. Measured against the engine on a tenant
+   * holding three sorts, `GET /api/v1/sorts/tenant/{id}` answers
+   * `{"count":3,"total":3,"offset":0}`.
+   *
+   * @example
+   * ```typescript
+   * let offset = 0;
+   * for (;;) {
+   *   const page = await client.sorts.listSortsPage({ limit: 500, offset });
+   *   consume(page.sorts);
+   *   offset += page.count;
+   *   if (page.total === undefined || offset >= page.total) break;
+   * }
+   * ```
+   */
+  async listSortsPage(query, requestOptions) {
+    const response = await this.sorts.listSorts(
+      this.tenantId,
+      ListSortsQueryFromFrontToApi(query),
+      toRequestParams(requestOptions)
+    );
+    return SortListResponseFromApiToFront(response.data);
   }
   /**
    * Bulk-create sorts with name-based parent references.
@@ -14628,6 +14811,11 @@ function toUntaggedValue(value) {
       return value.value.map(toUntaggedValue);
     }
     if (value.type === "Reference") {
+      if (typeof value.value !== "string") {
+        throw new ValidationError(
+          `A @key reference designator (sort "${value.value.sortName}") cannot be a FEATURE value on an untagged inference endpoint: the untagged feature-value family has no designator variant. Name a whole term with { designator: \u2026 } where a TermInputDto is expected, or resolve this one to a term id.`
+        );
+      }
       return { termId: value.value };
     }
     if (value.type === "SortId") {
@@ -14691,6 +14879,18 @@ function ValueDtoFromApiToFront(dto) {
       value: dto.value.map(ValueDtoFromApiToFront)
     };
   }
+  if (dto.type === "Reference") {
+    if (typeof dto.value === "string") {
+      return { type: "Reference", value: dto.value };
+    }
+    return {
+      type: "Reference",
+      value: {
+        sortName: dto.value.sort_name,
+        features: featuresFromApiToFront(dto.value.features)
+      }
+    };
+  }
   if (dto.type === "PsiTerm") {
     const features = dto.value.features;
     return {
@@ -14781,6 +14981,18 @@ function ValueDtoFromFrontToApi(value) {
       value: value.value.map(ValueDtoFromFrontToApi)
     };
   }
+  if (value.type === "Reference") {
+    if (typeof value.value === "string") {
+      return { type: "Reference", value: value.value };
+    }
+    return {
+      type: "Reference",
+      value: {
+        sort_name: value.value.sortName,
+        features: featuresFromFrontToApi(value.value.features)
+      }
+    };
+  }
   if (value.type === "PsiTerm") {
     const features = value.value.features;
     return {
@@ -14866,7 +15078,10 @@ function TermDtoFromApiToFront(dto) {
     sortName: dto.sort_name ?? void 0,
     displayName: dto.display_name ?? void 0,
     referencedTerms,
-    origin: dto.origin
+    origin: dto.origin,
+    // `derived_by` is a uuid or `null`; the shipped field is `string |
+    // undefined`, so a null collapses rather than travelling as a third state.
+    ...dto.derived_by == null ? {} : { derivedBy: dto.derived_by }
   };
 }
 function WitnessProofDtoFromApiToFront(dto) {
@@ -14895,9 +15110,21 @@ function CreateTermRequestFromFrontToApi(model) {
   return {
     sort_id: model.sortId,
     owner_id: model.ownerId,
-    features: featuresFromFrontToApi(model.features)
+    features: featuresFromFrontToApi(model.features),
+    ...model.id === void 0 ? {} : { id: model.id }
   };
 }
+function CreateTermInputFromFrontToApi(model) {
+  if ("sortName" in model) {
+    return {
+      sort_name: model.sortName,
+      owner_id: model.ownerId,
+      features: featuresFromFrontToApi(model.features),
+      ...model.id === void 0 ? {} : { id: model.id }
+    };
+  }
+  return CreateTermRequestFromFrontToApi(model);
+}
 function UpdateTermRequestFromFrontToApi(model) {
   return {
     features: featuresFromFrontToApi(model.features)
@@ -14905,15 +15132,34 @@ function UpdateTermRequestFromFrontToApi(model) {
 }
 function BulkAddTermsRequestFromFrontToApi(model) {
   return {
-    terms: model.terms.map(CreateTermRequestFromFrontToApi)
+    terms: model.terms.map(CreateTermInputFromFrontToApi),
+    dry_run: model.dryRun,
+    partial: model.partial
   };
 }
 function BulkAddTermsResponseFromApiToFront(dto) {
   return {
-    termIds: dto.term_ids,
+    // `term_ids` is absent on a dry run and shorter than the request under
+    // `partial`, so it is optional on the shipped type rather than defaulted to
+    // an empty array — an empty array would read as "nothing was created", and
+    // a dry run over a clean batch creates nothing while reporting a non-zero
+    // `termsAdded`. The two facts are different and both matter.
+    ...dto.term_ids ? { termIds: dto.term_ids } : {},
+    termsAdded: dto.terms_added,
+    dryRun: dto.dry_run,
+    ...dto.refused === void 0 || dto.refused === null ? {} : { refused: dto.refused },
+    ...dto.errors ? { errors: dto.errors.map(BulkRowRefusalFromApiToFront) } : {},
+    ...dto.coreferenced_term_ids ? { coreferencedTermIds: dto.coreferenced_term_ids } : {},
     processingTimeMs: dto.processing_time_ms
   };
 }
+function BulkRowRefusalFromApiToFront(dto) {
+  return {
+    index: dto.index,
+    message: dto.message,
+    ...dto.feature ? { feature: dto.feature } : {}
+  };
+}
 function ClearTermsResponseFromApiToFront(dto) {
   return {
     message: dto.message,
@@ -14958,7 +15204,12 @@ function ValidatedUnifyResponseFromApiToFront(dto) {
 function TermListResponseFromApiToFront(dto) {
   return {
     terms: dto.terms.map(TermDtoFromApiToFront),
-    count: dto.count
+    count: dto.count,
+    // `total` is `null` on a route that does not page, and `note` is `null`
+    // whenever the engine has no remark. Both collapse to absent so a consumer
+    // tests one thing — presence — rather than two.
+    ...dto.total == null ? {} : { total: dto.total },
+    ...dto.note == null ? {} : { note: dto.note }
   };
 }
 function TermReferrerDtoFromApiToFront(dto) {
@@ -15075,10 +15326,9 @@ var TermsClient = class {
    * ```
    */
   async createTerm(request, requestOptions) {
-    const wireRequest = CreateTermRequestFromFrontToApi({
-      ...request,
-      features: convertFeatures(request.features)
-    });
+    const wireRequest = CreateTermInputFromFrontToApi(
+      "sortName" in request ? { ...request, features: convertFeatures(request.features) } : { ...request, features: convertFeatures(request.features) }
+    );
     const response = await this.api.addTerm(wireRequest, toRequestParams(requestOptions));
     return TermResponseFromApiToFront(response.data);
   }
@@ -15253,13 +15503,91 @@ var TermsClient = class {
     }
   }
   /**
-   * Bulk-create terms.
+   * Create many terms in one request, all-or-nothing by default.
    *
-   * @param request - Bulk creation request.
-   * @returns Bulk creation result with term UUIDs.
+   * @param request - The rows, plus `dryRun` to check without writing and
+   *   `partial` to keep the rows that passed. Features may be plain JS values
+   *   or `Value.*` output.
+   * @param requestOptions - Per-call request options.
+   * @returns What was written (or, on a dry run, what WOULD be written):
+   *   `termsAdded`, `termIds` on a real write, `errors` beside them under
+   *   `partial`, `coreferencedTermIds` on a dry run.
+   * @throws {@link BulkRefusedError} 422 when the batch was refused and
+   *   NOTHING was written. Read `error.rows` — one entry per refused row, each
+   *   naming its `index` in `request.terms`. This is the answer for a refused
+   *   default batch, for a refused dry run, and for a `partial` batch in which
+   *   every row was refused.
+   * @throws {@link ApiError} 409 when the end-of-batch constraint propagation
+   *   refuses the batch as a whole. That verdict cannot be attributed to a row,
+   *   so `partial` does not split it.
+   *
+   * @remarks
+   * **Serialization format: Tagged (`ValueDto`).** Plain feature values are
+   * converted exactly as {@link TermsClient.createTerm} converts them.
+   *
+   * There are three outcomes, and they are distinguishable without reading a
+   * status code:
+   *
+   * 1. **A clean write** — `201`. `termIds` holds one id per request row, in
+   *    request order; `termsAdded` equals its length; `errors` is absent.
+   *    Measured 2026-09-18, a 2-row clean batch:
+   *    `{"terms_added":2,"term_ids":["3d936f37-…","f4a77a0b-…"],
+   *    "processing_time_ms":38,"dry_run":false}`.
+   * 2. **A partial write** — `201`, and only with `partial: true`. Some rows
+   *    landed. `termIds` holds one id per ACCEPTED row, so it is SHORTER than
+   *    `request.terms`, and `errors` sits beside it naming the refused ones.
+   *    Map a refusal back with `errors[].index`, never with a position in
+   *    `termIds`. Measured, a 2-row batch whose second row violates a declared
+   *    range:
+   *    `{"terms_added":1,"term_ids":["d6ba85e6-…"],"errors":[{"index":1,
+   *    "feature":"price","message":"Constraint violation: Feature 'price'
+   *    value violates its declared range/constraint"}],"refused":1,
+   *    "processing_time_ms":37,"dry_run":false}`.
+   * 3. **A refusal** — `422`, thrown as {@link BulkRefusedError}. Nothing was
+   *    written. Measured, the same bad batch WITHOUT `partial`:
+   *    `{"code":"bulk_refused","message":"1 of 2 entries were refused; the
+   *    whole batch was refused and nothing was written","errors":[{"index":1,
+   *    "feature":"price","message":"Constraint violation: …"}]}`. With
+   *    `partial: true` and BOTH rows bad, the same `422`:
+   *    `"2 of 2 entries were refused; the whole batch was refused and nothing
+   *    was written"`.
+   *
+   * **`dryRun` runs every check and writes nothing**, and it answers in the
+   * same two shapes. A clean dry run is `200` and reports NO `termIds` —
+   * measured:
+   * `{"terms_added":2,"coreferenced_term_ids":[],"processing_time_ms":0,
+   * "dry_run":true}`. The absence is deliberate: the rollback discarded every
+   * id it minted, a later real write mints different ones, so the vector would
+   * name nothing. The ids that DO outlive a dry run are the existing entities
+   * a `@key` coreference would have merged into, and they come back as
+   * `coreferencedTermIds`. A dry run over a BAD batch throws
+   * {@link BulkRefusedError} with the same per-row refusals a real write throws
+   * — measured, identical body to outcome 3 — so a caller can validate an
+   * import with one call and never touch the store.
+   *
+   * @example
+   * ```typescript
+   * // Validate an import without writing.
+   * try {
+   *   const check = await client.terms.bulkCreateTerms({ terms: rows, dryRun: true });
+   *   console.log(`${check.termsAdded} rows would be written`); // no check.termIds
+   * } catch (e) {
+   *   if (e instanceof BulkRefusedError) {
+   *     for (const row of e.rows) console.error(`row ${row.index}: ${row.message}`);
+   *   }
+   * }
+   *
+   * // Write what passes, and report what did not.
+   * const result = await client.terms.bulkCreateTerms({ terms: rows, partial: true });
+   * console.log(`${result.termsAdded} written`, result.termIds);
+   * for (const bad of result.errors ?? []) {
+   *   console.warn(`row ${bad.index} (${bad.feature}): ${bad.message}`);
+   * }
+   * ```
    */
   async bulkCreateTerms(request, requestOptions) {
     const wireRequest = BulkAddTermsRequestFromFrontToApi({
+      ...request,
       terms: request.terms.map((t) => ({
         ...t,
         features: convertFeatures(t.features)
@@ -15269,34 +15597,66 @@ var TermsClient = class {
     return BulkAddTermsResponseFromApiToFront(response.data);
   }
   /**
-   * List terms for the authenticated tenant.
+   * List one page of the tenant's terms, and say how many there are.
    *
-   * @param query - Optional paging and sort filter. Omit for every term.
-   * @returns The list of terms with total count.
-   * @throws {ApiError} If the request fails.
-   *
-   * @remarks
-   * Terms are enriched with sort names, display names, and referenced term summaries.
-   * Requires X-Tenant-Id header (set via client configuration).
-   * Uses the tagged {@link ValueDto} serialization format.
-   *
-   * `sortName` filters on the sort's committed name. For a plugin-contributed
-   * sort that is the namespaced form (`plugin:<plugin-name>:<local>`), which
-   * {@link SortDto.name} carries and {@link SortDto.pluginLocalName} maps back
-   * to the name its author wrote.
-   *
-   * @example
-   * ```typescript
-   * const result = await client.terms.listTerms();
-   * console.log(`Found ${result.count} terms`);
+   * @param query - Paging, the sort filter, and `includeDerived`. Omit for
+   *   every term.
+   * @param requestOptions - Per-call request options.
+   * @returns The page in `terms`, its length in `count`, the size of the whole
+   *   answer in `total`, and an engine remark in `note`.
+   * @throws {@link ApiError} If the request fails.
+   *
+   * @remarks
+   * **Serialization format: Tagged (`ValueDto`).** Terms are enriched with sort
+   * names, display names, and referenced-term summaries. Requires the
+   * `X-Tenant-Id` header, which the client configuration sets.
+   *
+   * **Page off `total`, not `count`.** `count` is this page's length and
+   * nothing else. Measured 2026-09-18 on a tenant holding 3 terms:
+   * `GET /api/v1/terms?limit=1&offset=2` answered
+   * `{"terms":[…one…],"count":1,"total":3}`. `total` is counted before the
+   * window, so it is the number to compare an offset against.
+   *
+   * **When the page is empty, read `note` before you report "no results".**
+   * The route neither chains nor persists conclusions, so for a sort whose
+   * members exist only by derivation the honest answer in a freshly started
+   * process is zero rows — and `total: 0` reads like an authoritative "no
+   * members", which is false. Measured 2026-09-18, a tenant with `widget`,
+   * subsort `premium_widget`, one `widget` fact and the rule
+   * `widget(name: ?N) → premium_widget(name: ?N)`:
+   * `GET /api/v1/terms?sort_name=premium_widget` answered
+   * `{"terms":[],"count":0,"total":0,"note":"`premium_widget` is a rule
+   * conclusion sort: its members are derived … An empty answer here does not
+   * mean the sort has no members."}`. Without the rule, the same empty answer
+   * carried no note.
+   *
+   * `sortName` filters on the sort's committed name, and on that sort EXACTLY
+   * — a member of a subsort is not answered. For a plugin-contributed sort the
+   * committed name is the namespaced form (`plugin:<plugin-name>:<local>`),
+   * which {@link SortDto.name} carries and {@link SortDto.pluginLocalName}
+   * maps back to the name its author wrote.
+   *
+   * @example
+   * ```typescript
+   * const first = await client.terms.listTerms({ sortName: 'person', limit: 50 });
+   * if (first.terms.length === 0 && first.note) console.info(first.note);
+   * for (let offset = 50; offset < (first.total ?? 0); offset += 50) {
+   *   const page = await client.terms.listTerms({ sortName: 'person', limit: 50, offset });
+   *   // …
+   * }
    *
-   * // Only the first page of one sort's terms.
-   * const page = await client.terms.listTerms({ sortName: 'person', limit: 50 });
+   * // The asserted rows alone — the engine includes conclusions by default.
+   * const asserted = await client.terms.listTerms({ includeDerived: false });
    * ```
    */
   async listTerms(query, requestOptions) {
     const response = await this.api.listTerms(
-      query ? { limit: query.limit, offset: query.offset, sort_name: query.sortName } : void 0,
+      query ? {
+        limit: query.limit,
+        offset: query.offset,
+        sort_name: query.sortName,
+        include_derived: query.includeDerived
+      } : void 0,
       toRequestParams(requestOptions)
     );
     return TermListResponseFromApiToFront(response.data);
@@ -15325,12 +15685,25 @@ var TermsClient = class {
   // ─── Friendly Aliases ─────────────────────────────────────────────
   /**
    * Create multiple records in a single request.
-   * Alias for {@link bulkCreateTerms}.
+   * Alias for {@link TermsClient.bulkCreateTerms}.
+   *
+   * @param request - The rows, plus `dryRun` and `partial`.
+   * @param requestOptions - Per-call request options.
+   * @returns What was written, exactly as {@link TermsClient.bulkCreateTerms}
+   *   returns it.
+   * @throws {@link BulkRefusedError} 422 when nothing was written.
+   *
+   * @remarks
+   * **Serialization format: Tagged (`ValueDto`).** Same call, friendlier name
+   * — read {@link TermsClient.bulkCreateTerms} for the three outcomes and for
+   * what a dry run does and does not report.
    *
-   * @param request - Bulk creation request.
-   * @returns Bulk creation result with term UUIDs.
+   * @example
+   * ```typescript
+   * const result = await client.terms.createMany({ terms: rows, partial: true });
+   * ```
    *
-   * @see bulkCreateTerms
+   * @see {@link TermsClient.bulkCreateTerms}
    */
   async createMany(request, requestOptions) {
     return this.bulkCreateTerms(request, requestOptions);
@@ -15361,7 +15734,7 @@ var TermsClient = class {
     return paginateByOffset(
       async (window, perCall) => {
         const page = await this.listTerms({ ...query, ...window }, perCall);
-        return { items: page.terms };
+        return page.total === void 0 ? { items: page.terms } : { items: page.terms, total: page.total };
       },
       options,
       requestOptions
@@ -15369,10 +15742,6 @@ var TermsClient = class {
   }
 };
 function convertFeatures(features) {
-  const values = Object.values(features);
-  if (values.length > 0 && values.every(isTaggedValueDto)) {
-    return features;
-  }
   return toTaggedFeatures(features);
 }
 
@@ -15423,6 +15792,14 @@ function TermInputDtoFromFrontToApi(model) {
   if ("termId" in model) {
     return { term_id: model.termId };
   }
+  if ("designator" in model) {
+    return {
+      designator: {
+        sort_name: model.designator.sortName,
+        features: model.designator.features
+      }
+    };
+  }
   if ("sortId" in model) {
     const inline = {
       sort_id: model.sortId,
@@ -15593,7 +15970,7 @@ function ForwardChainResponseFromApiToFront(dto) {
     iterations: dto.iterations,
     totalFacts: dto.total_facts,
     materializationTimeMs: dto.materialization_time_ms,
-    persistedCount: dto.persisted_count,
+    keptCount: dto.kept_count,
     provenanceTags: dto.provenance_tags?.map(ProvenanceTagDtoFromApiToFront)
   };
 }
@@ -16030,7 +16407,7 @@ function BackwardChainRequestFromFrontToApi(model) {
 function ForwardChainRequestFromFrontToApi(model) {
   return {
     initial_facts: model.initialFacts?.map(TermInputDtoFromFrontToApi),
-    persist_derived: model.persistDerived,
+    keep_derived: model.keepDerived,
     enable_provenance_tags: model.enableProvenanceTags,
     max_iterations: model.maxIterations,
     max_facts: model.maxFacts,
@@ -16393,7 +16770,19 @@ var InferenceClient = class {
    * Forward chaining starts from existing facts and applies rules to derive new facts,
    * repeating until no more new facts can be derived (fixpoint) or limits are reached.
    *
-   * If `persist_derived` is true, derived facts are permanently saved to the database.
+   * `keepDerived: true` keeps the run's derivations RESIDENT so a later `MATCH`
+   * reads them. A default run is rolled back, not merely unwritten — so this
+   * route reports what it derived and leaves the store as it found it. Neither
+   * setting is durable: to repair a tenant whose materialised set has drifted,
+   * use OSFQL `CHAIN;` or {@link AdminClient.rebuildDerivedFacts}.
+   *
+   * `timeoutMs` is a server-side deadline in milliseconds, checked at every
+   * fixpoint boundary and every rule application. Omitted means the engine's own
+   * backstop (`OSFKB_FC_TIMEOUT_SECS`, 300 s by default); `0` opts out entirely.
+   * The route answers `504` when the deadline passes, and the body says whether
+   * a `keepDerived` run kept the partial derivation it had reached.
+   *
+   * @throws {ApiError} With status 504 when the derivation passed its deadline.
    */
   async forwardChain(request, requestOptions) {
     const wireRequest = {
@@ -16693,6 +17082,7 @@ function FindBySortRequestFromFrontToApi(model) {
     sort_name: model.sortName ?? void 0,
     filter: model.filter ?? void 0,
     limit: model.limit ?? void 0,
+    offset: model.offset ?? void 0,
     include_derived: model.includeDerived
   };
 }
@@ -16833,11 +17223,97 @@ var QueryClient = class {
     return response.data.results.map(TermDtoFromApiToFront);
   }
   /**
-   * Find terms by sort ID, sort name, or with optional filter.
+   * Browse a sort and everything below it, one page at a time.
    *
-   * @param request - Query by sort request. Accepts sort_id (UUID),
-   *   sort_name (human-readable), and optional filter for feature-based filtering.
-   * @returns Array of matching terms (tagged ValueDto format).
+   * @param request - `sortId` (UUID) or `sortName`, an optional feature
+   *   `filter`, the `limit`/`offset` window, and `includeDerived`.
+   * @param requestOptions - Per-call request options.
+   * @returns The page in `terms`, its length in `count`, the size of the whole
+   *   answer in `total`, and an engine remark in `note`.
+   * @throws {@link ApiError} 404 when no sort of that name is queryable for
+   *   the tenant.
+   *
+   * @remarks
+   * **Serialization format: Tagged (`ValueDto`).** This is the polymorphic
+   * browse: a query on a sort answers that sort AND every subsort of it, which
+   * is what distinguishes it from {@link TermsClient.listTerms}'s exact
+   * `sortName` filter.
+   *
+   * **Page off `total`.** `count` is this page's length. `total` is the number
+   * of rows matched BEFORE `offset` and `limit`, counted rather than estimated.
+   *
+   * **A page is stable.** The answer is ordered by term id before the window
+   * is applied, so page 2 neither repeats nor skips a row of page 1. Measured
+   * 2026-09-18 against a 2-member sort:
+   * `POST /api/v1/query/by-sort {"sort_name":"widget","include_derived":true}`
+   * answered ids `829ef5dc-…` then `d4f7a4f8-…` with
+   * `{"count":2,"total":2}`; the same request plus `{"limit":1,"offset":1}`
+   * answered `d4f7a4f8-…` alone with `{"count":1,"total":2}` — the second row,
+   * and the same total.
+   *
+   * **The route does not chain.** It answers the tenant's durable extension
+   * UNIONED with the conclusions this process currently HOLDS. After a restart
+   * the derived half is empty until something chains again. So when the page
+   * is empty, read `note` rather than trusting `total: 0`: measured
+   * 2026-09-18, a tenant with `widget`, subsort `premium_widget`, one `widget`
+   * fact and the rule `widget(name: ?N) → premium_widget(name: ?N)`,
+   * `{"sort_name":"premium_widget"}` answered
+   * `{"terms":[],"count":0,"total":0,"note":"`premium_widget` is a rule
+   * conclusion sort: its members are derived … Materialise them with OSFQL
+   * CHAIN, POST /api/v1/inference/forward-chain, or POST
+   * /api/v1/admin/derived-facts/rebuild/{tenant_id} … An empty answer here
+   * does not mean the sort has no members."}`. Before the rule existed, the
+   * same empty query carried no note.
+   *
+   * @example
+   * ```typescript
+   * const page = await client.query.findBySortPage({
+   *   sortName: 'sales_order',
+   *   includeDerived: true,
+   *   limit: 25,
+   *   offset: 0,
+   * });
+   * if (page.terms.length === 0 && page.note) console.info(page.note);
+   * console.log(`${page.count} of ${page.total}`);
+   * ```
+   *
+   * @see {@link QueryClient.findBySort} — the deprecated array-returning form.
+   */
+  async findBySortPage(request, requestOptions) {
+    const response = await this.api.findBySort(
+      FindBySortRequestFromFrontToApi(request),
+      toRequestParams(requestOptions)
+    );
+    return TermListResponseFromApiToFront(response.data);
+  }
+  /**
+   * Browse a sort and everything below it, discarding the envelope.
+   *
+   * @deprecated Use {@link QueryClient.findBySortPage}, which returns the
+   *   engine's envelope. This method drops `count`, `total` and `note`, so a
+   *   caller cannot tell a full answer from a truncated one, cannot page, and
+   *   reads an empty array for a rule-conclusion sort with no way to see the
+   *   engine's explanation. It is kept so 1.27 callers keep compiling.
+   *
+   * @param request - `sortId` or `sortName`, an optional feature `filter`, the
+   *   `limit`/`offset` window, and `includeDerived`.
+   * @param requestOptions - Per-call request options.
+   * @returns The page's terms alone.
+   * @throws {@link ApiError} 404 when no sort of that name is queryable for
+   *   the tenant.
+   *
+   * @remarks
+   * **Serialization format: Tagged (`ValueDto`).** Identical request,
+   * identical rows, identical ordering — see
+   * {@link QueryClient.findBySortPage} for the measured ordering and paging
+   * contract. The only difference is what is thrown away.
+   *
+   * @example
+   * ```typescript
+   * const terms = await client.query.findBySort({ sortName: 'sales_order' });
+   * ```
+   *
+   * @see {@link QueryClient.findBySortPage}
    */
   async findBySort(request, requestOptions) {
     const response = await this.api.findBySort(FindBySortRequestFromFrontToApi(request), toRequestParams(requestOptions));
@@ -16945,10 +17421,6 @@ var QueryClient = class {
   }
 };
 function convertPattern(pattern) {
-  const values = Object.values(pattern.features);
-  if (values.length > 0 && values.every(isTaggedValueDto)) {
-    return pattern;
-  }
   return {
     sortId: pattern.sortId,
     features: toTaggedFeatures(pattern.features)
@@ -31399,6 +31871,11 @@ function OsfqlValueFromApiToFront(value) {
       return typeof payload === "string" ? { type: "string", value: payload } : void 0;
     case "boolean":
       return typeof payload === "boolean" ? { type: "boolean", value: payload } : void 0;
+    // The engine's own RFC 3339 rendering, passed through as the string it is.
+    // Parsing it to a `Date` here would reformat a response, which this layer
+    // never does — and would lose the offset the engine chose to send.
+    case "datetime":
+      return typeof payload === "string" ? { type: "datetime", value: payload } : void 0;
     case "term_ref":
       return typeof payload === "string" ? { type: "term_ref", value: payload } : void 0;
     case "list": {
@@ -31532,6 +32009,7 @@ function OsfqlCatalogEntryFromApiToFront(dto) {
     syntax: dto.syntax,
     examples: dto.examples,
     risk: dto.risk,
+    mutates: dto.mutates,
     execution: OsfqlCatalogExecutionFromApiToFront(dto.execution),
     uiAffinity: {
       display: dto.ui_affinity.display ?? void 0,
@@ -31550,6 +32028,74 @@ function OsfqlCatalogExecutionFromApiToFront(dto) {
   if (dto === "PlanOnly") return { status: "planOnly" };
   return { status: "partial", note: dto.Partial };
 }
+function OsfqlPreviewSortCountFromApiToFront(dto) {
+  return { sort: dto.sort, count: dto.count };
+}
+function OsfqlPreviewAffectedFromApiToFront(dto) {
+  const affected = { count: dto.count };
+  if (dto.exact !== void 0) {
+    affected.exact = dto.exact;
+  }
+  if (dto.sample_rows !== void 0) {
+    const rows = OsfqlBindingsFromApiToFront(dto.sample_rows);
+    if (rows === void 0) {
+      return void 0;
+    }
+    affected.sampleRows = rows;
+  }
+  if (dto.by_sort !== void 0) {
+    affected.bySort = dto.by_sort.map(OsfqlPreviewSortCountFromApiToFront);
+  }
+  return affected;
+}
+function OsfqlAtomicRefusalFromApiToFront(dto) {
+  return { code: dto.code, message: dto.message };
+}
+function OsfqlPreviewStatementFromApiToFront(dto) {
+  const statement = {
+    index: dto.index,
+    id: dto.id,
+    statement: dto.statement,
+    risk: dto.risk,
+    mutates: dto.mutates,
+    sorts: dto.sorts,
+    source: dto.source
+  };
+  if (dto.affected !== void 0) {
+    const affected = OsfqlPreviewAffectedFromApiToFront(dto.affected);
+    if (affected === void 0) {
+      return void 0;
+    }
+    statement.affected = affected;
+  }
+  if (dto.nested !== void 0) {
+    const nested = [];
+    for (const child of dto.nested) {
+      const parsed = OsfqlPreviewStatementFromApiToFront(child);
+      if (parsed === void 0) {
+        return void 0;
+      }
+      nested.push(parsed);
+    }
+    statement.nested = nested;
+  }
+  return statement;
+}
+function OsfqlPreviewResponseFromApiToFront(dto) {
+  const statements = [];
+  for (const entry of dto.statements) {
+    const parsed = OsfqlPreviewStatementFromApiToFront(entry);
+    if (parsed === void 0) {
+      return void 0;
+    }
+    statements.push(parsed);
+  }
+  const response = { mutates: dto.mutates, statements };
+  if (dto.atomic_refusal !== void 0) {
+    response.atomicRefusal = dto.atomic_refusal ? OsfqlAtomicRefusalFromApiToFront(dto.atomic_refusal) : dto.atomic_refusal;
+  }
+  return response;
+}
 
 // src/resources/osfql.ts
 var OsfqlClient = class {
@@ -31625,6 +32171,107 @@ var OsfqlClient = class {
     }
     return parsed;
   }
+  /**
+   * Preview an OSFQL program: what each statement would do, decided without
+   * running anything.
+   *
+   * @param query - The OSFQL program text (one or more statements separated by `;`).
+   * @param options - Optional request options. Only `atomic` changes the answer:
+   *   it decides whether `atomicRefusal` is reported. `reactive`, `maxRows` and
+   *   `timeoutMs` are accepted for wire parity with {@link execute} and are
+   *   ignored by the route.
+   * @param requestOptions - Per-call transport options (timeout, signal, headers).
+   * @returns The per-statement classification, the affected-row reports, and the
+   *   atomic refusal when there is one.
+   * @throws {ApiError} If the program does not parse (HTTP 400, `OsfqlErrorResponse`),
+   *   or the request otherwise fails.
+   * @throws {ReasoningLayerError} If a sample row carries a value that does not satisfy
+   *   the published {@link OsfqlValue} contract.
+   *
+   * @remarks
+   * **Why call this instead of classifying the program client-side.** Three
+   * answers only the engine's own parse can give:
+   *
+   * 1. **Per-statement `mutates`.** A client keeps no table of which
+   *    process-control statements write. Measured on the dev engine: `CHAIN` and
+   *    `RELEASE RESIDUATIONS` report `mutates: true`, while `MARK ?m1`, `CUT` and
+   *    `SPACE CREATE ?S` report `false` — all five are `risk: "process_control"`.
+   *    In the other direction, `MATCH customer(name: ?N) INSERT vip(name: ?N)`
+   *    is `risk: "read"` with `mutates: true`. Read `mutates`, never `risk`.
+   * 2. **`affected.count` and `affected.sampleRows`.** Up to 10 rows, each
+   *    identifying itself with a `term_id` column and the declaring sort's
+   *    `@key` features, so a confirm dialog can say WHICH rows go, not just how
+   *    many. Counted by running a derived read-only `MATCH` against a clone of
+   *    the tenant. Verified: four destructive previews (`RETRACT`, `CLEAR FACTS`,
+   *    `DROP SORT`, `DEFINE`) left the tenant's fact count and its lattice
+   *    unchanged.
+   * 3. **`atomicRefusal`.** The same `drop_sort_in_atomic_program` verdict
+   *    `POST /api/v1/osfql` would refuse the program with, answered before the
+   *    program runs.
+   *
+   * ⚠️ **The one thing a caller must NOT do: treat `affected.count` as the
+   * number of rows the run will remove.** It is the reach of the statement's
+   * PATTERN. For `MATCH customer(name: ?N, spend: ?S); IF ?S > 60 THEN RETRACT
+   * customer(name: ?N);` over three customers of which one has `spend > 60`, the
+   * nested `RETRACT` answers `count: 3` — the derived `MATCH customer(name: ?N)`
+   * applies neither the `IF` condition nor the binding the earlier statement
+   * gives `?N`. Present it as "up to N rows" for a nested statement or one that
+   * reads a variable from an earlier statement.
+   *
+   * Two further measured facts. The top-level `mutates` DOES fold nested
+   * statements now: the `IF` program above answers `true`, and so does an `IF`
+   * whose only writing branch is the `ELSE` — the earlier defect where an `IF`
+   * with a writing branch answered `false` is fixed. And `affected` being absent
+   * is ambiguous: `RETRACT customer(tier: "bronze")` matching zero rows omits
+   * the field entirely rather than answering `count: 0`, exactly as a read does.
+   *
+   * `statement.index` is a single counter over the whole program: an `IF` at
+   * index 1 carries nested entries at index 2 and 3.
+   *
+   * Request serialization matches {@link execute} — `query` plus the optional
+   * `atomic` / `reactive` / `max_rows` / `timeout_ms` keys. The program TEXT is
+   * a string value, so the request bridge's snake_case pass does not touch it;
+   * a `camelCase` feature name inside the query survives verbatim. Sample-row
+   * KEYS are data and are not camelCased on the way back.
+   *
+   * @example
+   * ```typescript
+   * const preview = await client.osfql.preview(
+   *   'MATCH customer(name: ?N); RETRACT customer(tier: "gold");'
+   * );
+   *
+   * console.log(preview.mutates);                  // true
+   * const writes = preview.statements.filter((s) => s.mutates);
+   * console.log(writes[0].id);                     // "retract"
+   * console.log(writes[0].risk);                   // "targeted_destructive"
+   * console.log(writes[0].affected?.count);        // 2
+   * console.log(writes[0].affected?.sampleRows);   // [{ term_id: …, tier: … }, …]
+   *
+   * // A DROP SORT cannot share an atomic program
+   * const refused = await client.osfql.preview('DROP SORT widget; INSERT widget(label: "x");');
+   * console.log(refused.atomicRefusal?.code);      // "drop_sort_in_atomic_program"
+   *
+   * // Ask the same question without the atomic constraint
+   * const loose = await client.osfql.preview(
+   *   'DROP SORT widget; INSERT widget(label: "x");',
+   *   { atomic: false },
+   * );
+   * console.log(loose.atomicRefusal);              // undefined
+   * ```
+   */
+  async preview(query, options, requestOptions) {
+    const response = await this.api.previewOsfql(
+      OsfqlRequestFromFrontToApi({ ...options, query }),
+      toRequestParams(requestOptions)
+    );
+    const parsed = OsfqlPreviewResponseFromApiToFront(response.data);
+    if (parsed === void 0) {
+      throw new ReasoningLayerError(
+        "osfql/preview returned an affected sample row that does not match the published OsfqlValue contract (expected tagged values with a lowercase `type` discriminator)"
+      );
+    }
+    return parsed;
+  }
   /**
    * Diagnose an OSFQL program for contradictions and inconsistencies.
    *
@@ -35442,38 +36089,6 @@ var SolverClient = class {
   }
 };
 
-// src/normalizers/ontology-alignment.ts
-function AlignOntologyRequestFromFrontToApi(model) {
-  return {
-    domain_owl: model.domainOwl,
-    targets: model.targets
-  };
-}
-function AlignmentMatchDtoFromApiToFront(dto) {
-  return {
-    domainSort: dto.domain_sort,
-    matchType: dto.match_type,
-    targetCurie: dto.target_curie,
-    targetLabel: dto.target_label
-  };
-}
-function AlignmentConflictDtoFromApiToFront(dto) {
-  return {
-    domainSort: dto.domain_sort,
-    targetA: dto.target_a,
-    targetB: dto.target_b
-  };
-}
-function AlignOntologyResponseFromApiToFront(dto) {
-  return {
-    conflicts: dto.conflicts.map(AlignmentConflictDtoFromApiToFront),
-    domainSorts: dto.domain_sorts,
-    mappingTtl: dto.mapping_ttl,
-    matches: dto.matches.map(AlignmentMatchDtoFromApiToFront),
-    targetSorts: dto.target_sorts
-  };
-}
-
 // src/resources/ontology-alignment.ts
 var OntologyAlignmentClient = class {
   /** @internal */
@@ -38529,15 +39144,15 @@ function TemporalSeriesPointFromApiToFront(value) {
   }
   const bucketStart = asNumber(value["bucket_start"]);
   const count = asNumber(value["count"]);
-  const aggregate = asNumber(value["aggregate"]);
-  if (bucketStart === void 0 || count === void 0 || aggregate === void 0) {
+  const aggregate2 = asNumber(value["aggregate"]);
+  if (bucketStart === void 0 || count === void 0 || aggregate2 === void 0) {
     return void 0;
   }
   return {
     bucketStart,
     bucketEnd: asNumber(value["bucket_end"]),
     count,
-    aggregate,
+    aggregate: aggregate2,
     aggregateSecondary: asNumber(value["aggregate_secondary"])
   };
 }
@@ -42018,21 +42633,75 @@ var embeddings_exports = {};
 // src/builders/value.ts
 var Value = {
   /**
-   * Create a reference to another term by UUID.
+   * Create a reference to another stored term — by its UUID, or by the `@key`
+   * values that name it.
    *
-   * @param id - The UUID of the referenced term.
-   * @returns A tagged `ReferenceValue`: `{"type": "Reference", "value": "uuid"}`.
+   * @param target - The referenced term's UUID, or a {@link ReferenceDesignator}
+   *   naming it through the `@key` features of its sort.
+   * @returns A tagged `ReferenceValue`: `{"type": "Reference", "value": "uuid"}`
+   *   for the id form, `{"type":"Reference","value":{"sort_name":…,"features":…}}`
+   *   for the designator form.
+   * @throws {@link ValidationError} when the designator carries an empty
+   *   `sortName`, or names no feature — the engine refuses both, so the builder
+   *   refuses them before the round trip.
    *
    * @remarks
-   * Serialization format: Tagged (ValueDto). Use with term CRUD, queries, fuzzy operations.
+   * **Serialization format: Tagged (`ValueDto`).** Use with term CRUD, queries
+   * and fuzzy operations. The homoiconic inference endpoints take the untagged
+   * format and have no designator form.
+   *
+   * The two forms differ in what they can be used for:
+   *
+   * - The **UUID form** is what a read answers, and the only form that can
+   *   point at a term whose sort declares no `@key`.
+   * - The **designator form** is WRITE-side only. It RESOLVES to a term that
+   *   already exists and never mints one: measured on 2026-09-18, writing
+   *   a `payment` whose `invoice` feature was
+   *   `Value.reference({ sortName: 'invoice', features: { number: { type: 'String', value: 'INV-1' } } })`
+   *   stored `{"type":"Reference","value":"4641cbcb-…"}` — the id of the single
+   *   existing invoice — and the invoice extent still held exactly one term. A
+   *   designator matching nothing is refused `422 no term of sort 'invoice'
+   *   carries @key 'number' = "INV-NOPE"; a reference designator names an
+   *   existing term, it never creates one`. The same refusal arrives from
+   *   `POST /api/v1/terms/bulk` as a `BulkRefusedError` naming the entry index.
+   *
+   * The designator's `features` keys are OSF feature names — user data, not
+   * schema — and survive the request bridge verbatim, so a feature declared
+   * `invoiceNumber` must be spelled `invoiceNumber` here. Sending the
+   * snake_cased spelling is refused: `422 feature 'invoice_number' of sort
+   * 'invoice' is not a @key feature; a designator addresses a term only through
+   * its @key`.
    *
    * @example
    * ```typescript
+   * // By id:
    * Value.reference("550e8400-e29b-41d4-a716-446655440000")
+   *
+   * // By @key, when the caller has the business key and not the UUID:
+   * Value.reference({
+   *   sortName: 'invoice',
+   *   features: { number: { type: 'String', value: 'INV-1' } },
+   * })
    * ```
    */
-  reference(id) {
-    return { type: "Reference", value: id };
+  reference(target) {
+    if (typeof target === "string") {
+      return { type: "Reference", value: target };
+    }
+    if (target.sortName.length === 0) {
+      throw new ValidationError(
+        "Value.reference() expects a designator with a non-empty sortName"
+      );
+    }
+    if (Object.keys(target.features).length === 0) {
+      throw new ValidationError(
+        `Value.reference() expects a designator naming at least one @key feature of sort "${target.sortName}"; the engine refuses an empty designator`
+      );
+    }
+    return {
+      type: "Reference",
+      value: { sortName: target.sortName, features: target.features }
+    };
   },
   /**
    * Create a reference to a sort by UUID.
@@ -42771,6 +43440,7 @@ var FuzzyShape = {
 };
 
 // src/builders/psi.ts
+var NEGATION_SORT = "negation";
 function psi(sortOrName, features) {
   if (typeof sortOrName === "string") {
     if (!features) {
@@ -42799,6 +43469,38 @@ function bind(name, term) {
   }
   return { ...term, binding: name };
 }
+function not(clause) {
+  if ("sortName" in clause && clause.sortName === NEGATION_SORT) {
+    throw new ValidationError(
+      `not() cannot negate a negation: the chainers read the "${NEGATION_SORT}" carrier one clause deep, so a nested negation is accepted and derives nothing`
+    );
+  }
+  return {
+    __psiTerm: true,
+    sortName: NEGATION_SORT,
+    features: { clause }
+  };
+}
+function aggregate(spec) {
+  if (spec.groupBy.length === 0) {
+    throw new ValidationError(
+      "aggregate() expects at least one groupBy feature; an aggregator with no group key has no group to fold into"
+    );
+  }
+  const blank = spec.groupBy.find((name) => name.trim().length === 0);
+  if (blank !== void 0) {
+    throw new ValidationError("aggregate() expects every groupBy entry to be a feature name");
+  }
+  if (spec.target.trim().length === 0) {
+    throw new ValidationError("aggregate() expects a target feature name");
+  }
+  if (spec.groupBy.includes(spec.target)) {
+    throw new ValidationError(
+      `aggregate() cannot aggregate "${spec.target}" and also group by it`
+    );
+  }
+  return { groupBy: [...spec.groupBy], op: spec.op, target: spec.target };
+}
 function constrained(name, constraint) {
   return { __constrainedVar: true, name, constraint };
 }
@@ -43483,6 +44185,7 @@ exports.AuthenticationError = AuthenticationError;
 exports.Authz = authz_exports;
 exports.BadRequestError = BadRequestError;
 exports.Batch = batch_exports;
+exports.BulkRefusedError = BulkRefusedError;
 exports.CDL = cdl_exports;
 exports.Causal = causal_exports;
 exports.Chase = chase_exports;
@@ -43594,6 +44297,7 @@ exports.Visualization = visualization_exports;
 exports.WebSocketClient = WebSocketClient;
 exports.WebSocketConnection = WebSocketConnection;
 exports.WebhookActions = webhook_actions_exports;
+exports.aggregate = aggregate;
 exports.allen = allen;
 exports.bind = bind;
 exports.collect = collect;
@@ -43604,6 +44308,7 @@ exports.isConstrainedPlainVar = isConstrainedPlainVar;
 exports.isPsiTermInput = isPsiTermInput;
 exports.isTaggedValueDto = isTaggedValueDto;
 exports.isUuid = isUuid;
+exports.not = not;
 exports.paginateByOffset = paginateByOffset;
 exports.paginateByPage = paginateByPage;
 exports.psi = psi;