@happyvertical/smrt-types 0.42.4 → 0.42.5

package/AGENTS.md

@@ -11,6 +11,7 @@ Shared TypeScript type definitions. Prevents circular dependencies between packa
 | `user.ts` | `UserStatus`, `TenantStatus`, `MembershipStatus`, `SessionStatus`, `OverrideEffect` — status enums |
 | `identity.ts` | `User`, `Tenant`, `Role`, `Membership`, `SmrtEntityFields` — cross-package identity data contracts (runtime classes live in smrt-users, which `implements` these) |
 | `knowledge.ts` | Additive schema-version-1 domain knowledge contracts shared by core generation and development tooling |
+| `data-query.ts` | Serializable bounded query request/result envelope, allowlisted schema, filters, paging, totals, freshness, and facets |
 
 ## Rules
 

package/README.md

@@ -39,6 +39,15 @@ import { UserStatus, TenantStatus, MembershipStatus } from '@happyvertical/smrt-
 | `ModuleUIBaseProps` | Base props interface for module UI components |
 | `ModuleUIRegistryInterface` | Registry interface for module UI registration |
 
+### Bounded Data Queries (types)
+
+| Export | Description |
+|--------|------------|
+| `DataQueryRequest` / `DataQueryResult` | Serializable, transport-neutral bounded query and normalized result envelopes |
+| `DataQuerySchema` / `DataQueryFieldDescriptor` | Trusted adapter allowlist for projection, filter, sort, and facet capabilities |
+| `DataQueryFilter` / `DataQuerySort` / `DataQueryPage` | Typed predicates, deterministic sort terms, and cursor/offset paging |
+| `DataQueryTotal` / `DataQueryFreshness` | Explicit total exactness/as-of semantics and response freshness |
+
 ### User/Tenant Status (enums — runtime values)
 
 | Export | Description |

package/dist/index.d.ts

@@ -137,6 +137,197 @@ export declare interface AiUsageSummaryOptions extends Omit<AiUsageListOptions,
     groupBy?: AiUsageGroupBy;
 }
 
+/** One typed predicate. `in` and `notIn` require a non-empty value array. */
+export declare interface DataQueryCondition {
+    kind: 'condition';
+    field: DataQueryFieldId;
+    operator: DataQueryFilterOperator;
+    value: DataQueryScalar | DataQueryScalar[];
+}
+
+export declare interface DataQueryConsistency {
+    /** Prefer the adapter's most recently available data. */
+    mode: DataQueryConsistencyMode;
+    /** Optional RFC 3339 instant requested by a time-travel capable adapter. */
+    asOf?: string;
+}
+
+/** Read consistency requested by a caller; adapters decide whether they support it. */
+export declare type DataQueryConsistencyMode = 'eventual' | 'snapshot';
+
+/** Cursor values are opaque to callers and bound to a normalized query. */
+export declare interface DataQueryCursorPage {
+    kind: 'cursor';
+    after?: string;
+    limit: number;
+}
+
+/** A bounded request for one declared facet. */
+export declare interface DataQueryFacetRequest {
+    field: DataQueryFieldId;
+    limit: number;
+}
+
+export declare interface DataQueryFacetResult {
+    field: DataQueryFieldId;
+    values: DataQueryFacetValue[];
+    truncated: boolean;
+}
+
+/** A bounded facet value/count pair. */
+export declare interface DataQueryFacetValue {
+    value: DataQueryScalar;
+    count: number;
+}
+
+/** An explicitly declared query field and its capability allowlist. */
+export declare interface DataQueryFieldDescriptor {
+    id: DataQueryFieldId;
+    type: 'string' | 'number' | 'boolean' | 'datetime' | 'json';
+    projectable?: boolean;
+    sortable?: boolean;
+    facetable?: boolean;
+    filterOperators?: DataQueryFilterOperator[];
+}
+
+/** A stable, adapter-defined field identifier. It is never a property path. */
+export declare type DataQueryFieldId = string;
+
+/** Bounded, recursive filter expression with explicit boolean semantics. */
+export declare type DataQueryFilter = DataQueryCondition | {
+    kind: 'all' | 'any';
+    filters: DataQueryFilter[];
+} | {
+    kind: 'not';
+    filter: DataQueryFilter;
+};
+
+/** Operators map to an adapter's allowlisted, typed predicate implementation. */
+export declare type DataQueryFilterOperator = 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte' | 'in' | 'notIn' | 'like';
+
+/** Freshness metadata is declarative; it does not grant access to a snapshot. */
+export declare interface DataQueryFreshness {
+    state: 'fresh' | 'stale' | 'unknown';
+    asOf?: string;
+}
+
+/** Offset pagination is explicit so callers cannot smuggle arbitrary bounds. */
+export declare interface DataQueryOffsetPage {
+    kind: 'offset';
+    offset: number;
+    limit: number;
+}
+
+export declare type DataQueryPage = DataQueryOffsetPage | DataQueryCursorPage;
+
+/**
+ * Canonical data-query request.
+ *
+ * A request id correlates transport logs and results only; it is intentionally
+ * excluded from the semantic query fingerprint. The query does not contain
+ * authority, raw database expressions, property paths, functions, or a
+ * transport-specific filter object.
+ */
+export declare interface DataQueryRequest {
+    version: 1;
+    requestId: string;
+    mode: 'rows' | 'count' | 'facets';
+    projection?: DataQueryFieldId[];
+    filter?: DataQueryFilter;
+    sort?: DataQuerySort[];
+    page?: DataQueryPage;
+    consistency?: DataQueryConsistency;
+    facets?: DataQueryFacetRequest[];
+}
+
+/**
+ * Normalized adapter result. `queryFingerprint` identifies the semantic query
+ * (not the request id or page cursor), while pagination state stays explicit.
+ */
+export declare interface DataQueryResult {
+    version: 1;
+    requestId: string;
+    queryFingerprint: string;
+    identityField: DataQueryFieldId;
+    rows: DataQueryRow[];
+    page?: {
+        kind: 'offset';
+        limit: number;
+        offset: number;
+        hasMore: boolean;
+    } | {
+        kind: 'cursor';
+        limit: number;
+        nextCursor?: string;
+        hasMore: boolean;
+    };
+    total: DataQueryTotal;
+    facets?: DataQueryFacetResult[];
+    freshness: DataQueryFreshness;
+    warnings: string[];
+    truncated: boolean;
+}
+
+/** Rows use JSON-safe values; adapters must project only declared fields. */
+export declare type DataQueryRow = Record<string, unknown>;
+
+/**
+ * Transport-neutral, bounded data-query contract (#2444).
+ *
+ * This module intentionally has no runtime code. The core package owns
+ * normalization, policy enforcement, canonical fingerprints, and result
+ * validation; browser, REST, MCP, WebMCP, ContentList, and report adapters
+ * share these serializable shapes without importing a server runtime.
+ *
+ * Authority is deliberately absent. A query can name only adapter-declared
+ * field ids and operators; tenant, principal, SQL, relationship paths, and
+ * execution details belong to the authenticated adapter, never this envelope.
+ */
+/** JSON scalar values accepted in predicates, facets, and normalized rows. */
+export declare type DataQueryScalar = string | number | boolean | null;
+
+/**
+ * Per-adapter execution policy. It is trusted adapter configuration, never
+ * client input, and therefore carries the field allowlists the normalizer
+ * applies to requests and returned rows.
+ */
+export declare interface DataQuerySchema {
+    version: 1;
+    identityField: DataQueryFieldId;
+    fields: DataQueryFieldDescriptor[];
+    defaultPageLimit?: number;
+    maxPageLimit?: number;
+    maxResultBytes?: number;
+    defaultSort?: DataQuerySort[];
+    supports?: {
+        cursorPagination?: boolean;
+        consistency?: boolean;
+        facets?: boolean;
+    };
+}
+
+/** Deterministic sort precedence; earlier terms take precedence. */
+export declare interface DataQuerySort {
+    field: DataQueryFieldId;
+    direction: DataQuerySortDirection;
+}
+
+export declare type DataQuerySortDirection = 'asc' | 'desc';
+
+/** How a returned total was obtained, including the absence of a total. */
+export declare type DataQueryTotal = {
+    kind: 'exact';
+    value: number;
+    asOf?: string;
+} | {
+    kind: 'estimated';
+    value: number;
+    asOf?: string;
+} | {
+    kind: 'unavailable';
+    reason?: string;
+};
+
 /** Per-object configuration controlling domain-knowledge generation and exposure. */
 export declare interface DomainKnowledgeConfig {
     enabled?: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-types",
-  "version": "0.42.4",
+  "version": "0.42.5",
   "description": "Shared type definitions for the HAVE SDK",
   "type": "module",
   "main": "./dist/index.js",