@abloatai/humans 0.37.0

package/dist/local/sync/ConnectionManager.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Moved to the settlement core with the duplex transport (ADR 0016): the
+ * connection state machine is plain, mobx-free plumbing an agent needs as much
+ * as a browser does. This path re-exports it so existing importers stay
+ * unchanged; the reactive store mirrors its transitions through
+ * `ConnectionCallbacks.onStateChange` into its own observable `syncStatus`.
+ */
+export { ConnectionManager, type ConnectionState, type ConnectionEvent, type ConnectionCallbacks, type ConnectionManagerOptions, } from '@abloatai/transaction/transport/connectionManager';

package/dist/local/sync/ConnectionManager.js

@@ -0,0 +1,8 @@
+/**
+ * Moved to the settlement core with the duplex transport (ADR 0016): the
+ * connection state machine is plain, mobx-free plumbing an agent needs as much
+ * as a browser does. This path re-exports it so existing importers stay
+ * unchanged; the reactive store mirrors its transitions through
+ * `ConnectionCallbacks.onStateChange` into its own observable `syncStatus`.
+ */
+export { ConnectionManager, } from '@abloatai/transaction/transport/connectionManager';

package/dist/local/sync/OnDemandLoader.d.ts

@@ -0,0 +1,231 @@
+/**
+ * Loads model rows on demand — the lazy-load path of the sync engine. When
+ * something needs an entity that the initial bootstrap did not fetch,
+ * {@link OnDemandLoader.fetch | fetch} finds it and populates the
+ * in-memory {@link InstanceCache} so the rest of the engine can read it normally.
+ *
+ * A fetch resolves against three tiers in order, stopping at the first that can
+ * answer:
+ *   1. The object pool — if rows already in memory match the query, return them.
+ *   2. Local storage — if matching rows exist there, hydrate the pool and return.
+ *   3. The network — post the query to `/sync/query`, then hydrate both the pool
+ *      and local storage.
+ *
+ * Concurrent calls with the same query key share one in-flight promise, so a
+ * burst of components mounting and asking for the same data on first paint
+ * triggers a single fetch rather than one each.
+ *
+ * The coordinator does not replace the bootstrap (which fully syncs instantly
+ * loaded models) or the live delta stream (pushed over the WebSocket). It only
+ * fills the gap for lazily loaded models read by id or filter after the engine
+ * is ready.
+ */
+import type { InstanceCache } from '../InstanceCache.js';
+import type { Database } from '../Database.js';
+import type { Model } from '../Model.js';
+import type { ModelRegistry } from '../ModelRegistry.js';
+import type { RuntimeContext } from '../RuntimeContext.js';
+import type { RecoveryClass } from '@abloatai/transaction/errorCodes';
+import type { LoadWhere, WhereClause } from '../query/types.js';
+import type { Schema } from '@abloatai/transaction/schema/schema';
+export interface OnDemandLoaderOptions {
+    readonly objectPool: InstanceCache;
+    readonly database: Database;
+    readonly registry: ModelRegistry;
+    readonly schema: Schema;
+    /** Bootstrap base URL (without trailing slash), e.g. `https://api.example.com/api`. */
+    readonly baseUrl: string;
+    /**
+     * Lazy getter for the active bearer token. Resolved per request so refreshes
+     * propagate without re-instantiating the coordinator.
+     */
+    readonly getAuthToken?: () => string | null;
+    /** @deprecated Use `getAuthToken`. */
+    readonly getCapabilityToken?: () => string | null;
+    /** The owning client's runtime. Defaults to the module-global bridge. */
+    readonly runtime?: RuntimeContext;
+}
+export interface FetchOptions<T> {
+    /**
+     * Filter clauses for the lookup. Accepts either the equality-object form
+     * (`{ id: 'abc' }` becomes `WHERE id = 'abc'`, and an array value becomes an
+     * `IN`) or the explicit tuple form (`[['name', 'ILIKE', '%Acme%']]`), which
+     * mirrors the wire `WhereClause[]` exactly. Multiple entries combine with AND.
+     * See {@link LoadWhere} for the full shape.
+     */
+    readonly where?: LoadWhere<T>;
+    readonly orderBy?: {
+        [K in keyof T]?: 'asc' | 'desc';
+    };
+    readonly limit?: number;
+    /**
+     * Freshness mode. When omitted, the default is derived from the model's
+     * load strategy: `lazy` models default to `'unknown'` (local-first), while
+     * `instant`/`partial` models default to `'complete'`.
+     *
+     * `'complete'`: wait for the network round-trip even if local data exists,
+     * so the caller observes server-confirmed state (read-after-write).
+     * `'unknown'`: return whatever's in the pool/IDB immediately and fire the
+     * network refresh in the background (stale-while-revalidate).
+     */
+    readonly type?: 'complete' | 'unknown';
+    /**
+     * Schema-declared relation names to hydrate alongside the primary
+     * rows. Each related entity is hydrated into its own typed pool
+     * via the same path as the primary fetch (network → pool + IDB).
+     */
+    readonly expand?: readonly string[];
+}
+export declare class OnDemandLoader {
+    private readonly opts;
+    private readonly inFlight;
+    /**
+     * Query keys with a background confirm currently in flight. Distinct from
+     * {@link inFlight} (which dedupes *blocking* callers awaiting the same
+     * fetch): this set dedupes the fire-and-forget network confirm kicked off
+     * after a local-first read returns cached data, so a burst of mounts that
+     * all hit the warm pool/IDB don't each spawn their own redundant fetch.
+     */
+    private readonly revalidating;
+    /**
+     * Query keys that have been satisfied from the server at least once this
+     * session. Once a key is here, repeat reads serve purely from the pool with
+     * no network round-trip: the WebSocket delta stream keeps those pool rows
+     * fresh, so re-running the HTTP query would be redundant polling. This ledger
+     * is what stops an already-open view from re-querying on every navigation.
+     *
+     * Cleared on reconnect (see {@link invalidate}) so that, after a connection
+     * drop where deltas may have been missed, the next read re-confirms once.
+     */
+    private readonly hydratedKeys;
+    private authTokenProvider;
+    /**
+     * The credential-recovery hook (the store's `recoverFromAuthRejection`),
+     * late-bound like {@link setAuthTokenProvider} because the store does not
+     * exist yet when the coordinator is constructed. Handed to `postQuery` so a
+     * 401 on the lazy lane re-mints through the same single-flight path the
+     * WebSocket probe uses, then replays the query once — instead of silently
+     * returning empty rows against an expired key.
+     */
+    private credentialRecovery;
+    constructor(opts: OnDemandLoaderOptions);
+    /**
+     * Late-bind the auth token getter. Browser cookie consumers can omit this;
+     * bearer consumers need it so lazy HTTP queries use the same credential as
+     * bootstrap and the WebSocket.
+     */
+    setAuthTokenProvider(provider: () => string | null): void;
+    /** Late-bind the auth-recovery backbone. See {@link credentialRecovery}. */
+    setCredentialRecovery(recover: (recovery: RecoveryClass) => Promise<'retry' | 'stop'>): void;
+    /** @deprecated Use `setAuthTokenProvider`. */
+    setCapabilityTokenProvider(provider: () => string | null): void;
+    /**
+     * Fetch matching rows for a model, hydrating the pool from IDB or
+     * network if not already present. Idempotent and single-flight
+     * deduped on the (modelName, where, orderBy, limit) tuple.
+     */
+    fetch<T>(modelName: string, options?: FetchOptions<T>): Promise<Model[]>;
+    private runFetch;
+    /**
+     * Read a query's rows from local storage only — pool first, then IndexedDB
+     * on a pool miss (cold start after reload, or LRU eviction), hydrating the
+     * pool from IDB as a side effect. Resolves requested `expand` relations from
+     * their own local stores too. Never touches the network.
+     */
+    private readLocal;
+    /**
+     * Drop the hydration ledger so the next read of each query re-confirms with
+     * the server. Called on reconnect — after a connection drop, deltas may have
+     * been missed, so the "WS keeps the pool fresh" assumption no longer holds
+     * until a fresh fetch (or the engine's delta catch-up) reconciles.
+     */
+    invalidate(): void;
+    /**
+     * Run the network leg of a fetch: query the server, hydrate primary rows
+     * (and any expanded relations) into the pool, and persist them to IDB.
+     * Shared by the blocking path (`runFetch` step 3) and the background
+     * revalidation kicked off after an `'unknown'` local hit.
+     */
+    private fetchFromNetwork;
+    /**
+     * Fires the single background confirm for a query that was just served from
+     * local cache but is not hydrated yet. On success the key is marked hydrated,
+     * so every later read serves purely from local with no network until a
+     * reconnect invalidates the ledger. Deduped per query key so a render burst
+     * does not stampede. Errors are swallowed — the caller already has a usable
+     * local snapshot, and a failed confirm leaves the key un-hydrated so the next
+     * read simply tries again.
+     */
+    private scheduleHydratingFetch;
+    /**
+     * Hydrate a parent's `hasMany`/`hasOne` relations from their OWN local
+     * stores (pool first, then IndexedDB by the FK secondary index) into the
+     * pool. The mirror of {@link hydrateExpanded} for the local read path:
+     * `hydrateExpanded` walks server-JOINed nested rows, this walks the child
+     * model's own store keyed by the relation's foreign key.
+     *
+     * Fully schema-driven via the relation's `target` + `foreignKey` — no
+     * per-model special-casing. `belongsTo` relations are skipped: those point
+     * at a single parent (the inverse direction), already covered by the
+     * primary scan when that parent is itself the fetched model.
+     */
+    private hydrateExpandedFromLocal;
+    /**
+     * Read a child model's rows from local storage by foreign key.
+     *
+     * Uses the FK secondary index (O(matches) per parent) only when the schema
+     * declares one — `getAllFromIndex` resolves `[]` for a missing index rather
+     * than throwing, so the decision is made up front from the registry, not by
+     * catching. Unindexed FKs — and in-memory stores, which carry no secondary
+     * indexes at all — fall back to a single full-store scan filtered in JS.
+     */
+    private readChildrenLocal;
+    /** Typed accessor for a model's schema definition (typename + relations). */
+    private getModelDef;
+    private hydrateOne;
+    /**
+     * Stamp `__typename` onto a row when it's known (from the schema's
+     * relation target). Strips the mangled `_Typename` key the
+     * `postgres.camel` driver leaves behind when the server's SQL
+     * bakes `__typename` into a JSONB literal — the driver's
+     * snake↔camel transform misreads `__typename` as `_typename` with
+     * a leading underscore and produces `_Typename`. InstanceCache only
+     * recognises `__typename`, so without this step nested rows fall
+     * through to the 'Unknown' branch and never instantiate.
+     */
+    private stampTypename;
+    private queryNetwork;
+    /**
+     * Hydrate nested expanded rows. Resolves each relation's target
+     * typename via the schema and stamps `__typename` on every nested
+     * row before passing to `hydrateOne` — the server's JSONB
+     * `__typename` field gets mangled by `postgres.camel` (`__typename`
+     * → `_Typename`), so the SDK can't trust whatever string lands.
+     */
+    private hydrateExpanded;
+    private persistToIdb;
+    private resolveTypename;
+    private columnizeField;
+    private columnizeClause;
+}
+/**
+ * Normalize `LoadWhere<T>` input to the canonical `readonly WhereClause[]`
+ * tuple form used throughout `runFetch`. Tuple inputs pass through; object
+ * inputs become one `['col', '=', val]` or `['col', 'IN', vals]` per key.
+ *
+ * Detection: an array whose first element is itself an array is treated
+ * as tuple form. Object form is the fallback.
+ *
+ * Exported so callers can pre-normalize (e.g., for tests, or to inspect
+ * the canonical clauses before passing them to `load`/`subscribe`).
+ */
+export declare function normalizeWhere(where: unknown): readonly WhereClause[];
+/**
+ * Operator-aware predicate. Mirrors the server's WhereOp semantics for
+ * local matching against pool/IDB rows. LIKE/ILIKE use SQL wildcards
+ * (`%` = any chars, `_` = one char) translated to a JS regex.
+ *
+ * Exported so callers can apply the same predicate to in-memory
+ * collections (tests, batch operations) using the canonical clauses.
+ */
+export declare function matchesClauses(entity: Record<string, unknown>, clauses: readonly WhereClause[]): boolean;