@githolon/client 0.1.2 → 0.1.6

package/LICENSE.md

@@ -24,6 +24,15 @@ with it; we keep the rest for now.
 - offer the Nomos runtime, or anything materially similar, as a hosted service;
 - reverse-engineer the holon wasm runtime.
 
+## Data retention
+
+This is a pre-release we are actively evaluating. Workspaces you retire stop
+counting toward your quota but are NOT deleted: **we retain all workspace data
+(ledgers, law, intents) and may examine it to evaluate how the product is
+used.** Don't put anything in a pre-release workspace you wouldn't want the
+builders to read. If you need something truly expunged, ask:
+jack@captainapp.co.uk.
+
 ## The rest
 
 Provided **as is**, with no warranty of any kind; to the maximum extent

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@githolon/client",
-  "version": "0.1.2",
+  "version": "0.1.6",
   "type": "module",
   "description": "Nomos Cloud web client — a LOCAL holon for offline-first apps: pulls the workspace ledger (git) from Nomos Cloud, replays it into the in-memory SQLite projection inside the wasm32-wasip1 GitHolon, and exposes dispatch / watch / sync. The browser runs the SAME byte-identical holon artifact the edge runs.",
   "license": "SEE LICENSE IN LICENSE.md",
@@ -9,8 +9,12 @@
     "url": "git+https://github.com/Captain-App/nomos2.git",
     "directory": "cloud/web-client"
   },
+  "types": "./src/index.d.ts",
   "exports": {
-    ".": "./src/index.mjs"
+    ".": {
+      "types": "./src/index.d.ts",
+      "default": "./src/index.mjs"
+    }
   },
   "files": [
     "src"

package/src/index.d.ts

@@ -0,0 +1,255 @@
+// ─── @githolon/client — hand-authored declarations for src/index.mjs ───────────────────────────
+//
+// Keep this file honest: every member below mirrors what `connect()` in index.mjs actually
+// builds and returns. The runtime is plain JS; this is its reference manual — hover any
+// member for the semantics (offline-first authoring, edge admission, dead letters).
+
+/** Options for {@link connect}. */
+export interface ConnectOptions {
+  /** Nomos Cloud base URL (e.g. `https://nomos.captainapp.co.uk`). */
+  cloud: string;
+  /** Workspace name — must already exist (`POST /v1/workspaces/:ws`). */
+  workspace: string;
+  /**
+   * Stable client identity: drives the untrusted session branch (`session/<clientId>`)
+   * and the HLC replica id. Defaults to a random id per connect — pass your own so the
+   * same app instance keeps the same offer lane across reconnects.
+   */
+  clientId?: string;
+  /**
+   * Bearer token for keyed clouds — needed for `sync()`'s push when the cloud sets
+   * `NOMOS_CLOUD_KEY`. Reads and admission stay open without it.
+   */
+  authToken?: string;
+  /**
+   * A {@link Holon.export} snapshot: hydrate the workspace directory from these bytes
+   * INSTEAD of cloning, then catch up via an automatic pull. Pending un-synced local
+   * commits survive the restore and remain syncable.
+   */
+  restoreFrom?: Uint8Array;
+}
+
+/**
+ * One projection row: the aggregate's wire type, its id, and the folded fields.
+ * Fields are partial folds — read them as possibly-absent (`unknown` per key).
+ */
+export interface AggregateRow {
+  type: string;
+  id: string;
+  data: Record<string, unknown>;
+}
+
+/**
+ * One parked intent in the DEAD-LETTER QUEUE: refused-but-LEGITIMATE work, with full
+ * provenance. The intent bytes stay in the queue (and ride `export()`/restore) — work
+ * is never lost; the app decides (retry after a law fix, or discard explicitly).
+ */
+export interface DeadLetter {
+  /** The content-derived intent id (absent only if the commit carried none). */
+  id?: string;
+  /** Short (10-hex) commit oid of the refused local commit — also accepted as a retry/discard key. */
+  oid: string;
+  /** Who refused it: `"edge"` (the admission gate) or `"local"` (a replay under changed local law). */
+  source: "edge" | "local";
+  /** The refusal verdict, verbatim from the law (truncated to 300 chars). */
+  error: string;
+  /** The intent's domain, when it could be read from the intent bytes. */
+  domain: string | null;
+  /** The intent's directive id, when it could be read from the intent bytes. */
+  directiveId: string | null;
+  /** ISO timestamp of the (latest) refusal. */
+  at: string;
+}
+
+/** One refusal inside an admission report (`deadLettered` marks a domain rejection vs an attack-lane drop). */
+export interface AdmissionRejection {
+  oid?: string;
+  error?: string;
+  /** True when the edge parked the work in the workspace DLQ (domain rejection) rather than dropping it. */
+  deadLettered?: boolean;
+  [k: string]: unknown;
+}
+
+/** One judged session branch inside an admission report. */
+export interface AdmissionSession {
+  /** Intents the edge re-admitted and merged to main. */
+  admitted?: unknown[];
+  /** Intents the edge refused (routed to the DLQ or dropped — see {@link AdmissionRejection.deadLettered}). */
+  rejected?: AdmissionRejection[];
+  [k: string]: unknown;
+}
+
+/**
+ * The edge holon's admission verdict (`POST /v1/workspaces/:ws/admit`): each pending
+ * session branch judged — every carried intent re-admitted under the workspace's own
+ * law (verification, never trust) and merged to `main`, or refused.
+ */
+export interface AdmissionReport {
+  ok: boolean;
+  sessions?: AdmissionSession[];
+  [k: string]: unknown;
+}
+
+/**
+ * Result of {@link Holon.pull} (and the `.converged` leg of {@link Holon.sync}):
+ * incremental convergence onto canonical main. When the remote advanced, local main is
+ * reset onto it and the local-only intents the canon doesn't already carry (by
+ * content-derived id) are rebase-replayed through `apply_intent` — the same
+ * re-admission primitive the edge runs.
+ */
+export interface PullResult {
+  /** True when remote main already equals the local head — nothing to do. */
+  upToDate: boolean;
+  /** The canonical remote main sha we now sit on. */
+  remoteHead: string;
+  /** Local-only intents re-admitted locally on top of the adopted canon. */
+  replayed?: { oid: string; id?: string | null; head?: string }[];
+  /** Local intents the canon already carried (edge-sealed copies, same intent id) — deduped, never double-folded. */
+  skipped?: { oid: string; id?: string | null }[];
+  /** Replays the local law refused or that errored (domain refusals also land in the DLQ). */
+  rejected?: { oid: string; id?: string | null; error: string }[];
+  /** Edge-refused attack-lane intents dropped from the lineage (present only when non-empty). */
+  dropped?: { oid: string; id?: string | null; edgeRejected: true }[];
+  /** Edge- or locally-refused LEGITIMATE work parked in the dead-letter queue (present only when non-empty). */
+  deadLettered?: { oid: string; id?: string | null; error?: string }[];
+}
+
+/**
+ * Result of {@link Holon.sync} — the offline-first exchange:
+ * up (push local commits to the untrusted session branch), judge (edge admission),
+ * down (converge onto canonical main in the same call).
+ */
+export interface SyncResult {
+  /** The session branch the local commits were pushed to (`session/<clientId>`), or null when there was nothing local to push. */
+  pushed: string | null;
+  /**
+   * The edge holon's admission verdict for this round. NULL when there was nothing to
+   * push (or `admit: false`): a pull-only sync converging in place is normal, not an
+   * error — the edge is only asked to judge when we actually offered work.
+   */
+  admission: AdmissionReport | null;
+  /** The in-call convergence (adopt canonical main + rebase-replay) that follows a successful admission; null otherwise. */
+  converged: PullResult | null;
+  /** True when remote main advanced and we adopted it (the next query folds the delta). */
+  pulled: boolean;
+  /** True when remote main advanced while we hold un-merged local work — wait for edge admission instead of force-adopting. */
+  diverged: boolean;
+  /** Always false — convergence happens in place on this instance; no reconnect is ever required. */
+  reconnectRequired: boolean;
+  /** The local ledger tip at the start of the sync. */
+  localHead: string;
+  /** Remote main as of this sync (undefined only if the remote advertised no main). */
+  remoteMain: string | undefined;
+}
+
+/** Outcome of {@link Holon.retryDeadLetter}. */
+export interface RetryDeadLetterResult {
+  ok: boolean;
+  /** New local head when the retry re-applied cleanly (it rides the next sync). */
+  head?: string;
+  /** True when the pull found the intent already admitted on canonical main — nothing to re-apply. */
+  alreadyOnMain?: boolean;
+  /** The (fresh) refusal when the law still says no — the entry stays parked, error updated. */
+  error?: string;
+}
+
+/**
+ * A LOCAL holon: the byte-identical wasm32-wasip1 GitHolon the edge runs, hydrated from
+ * the workspace's git ledger and folded into an in-memory SQLite projection. All reads
+ * and writes are local; `sync()` is the only network exchange. All operations are
+ * serialized onto the one wasm instance.
+ */
+export interface Holon {
+  /** The stable client identity — names the session branch (`session/<clientId>`) and seeds the HLC replica. */
+  clientId: string;
+  /** The 63-bit HLC replica id derived from `clientId`, as a decimal string. */
+  replica: string;
+
+  /** Local head — the client's own ledger tip (commit sha of local `main`). */
+  head(): Promise<string>;
+
+  /** Read an aggregate's row(s) from the LOCAL projection by id (folds any un-folded ledger delta first). */
+  queryById(aggregateId: string): Promise<AggregateRow[]>;
+
+  /** Run a declared domain query against the LOCAL projection (routed by the read manifest — works offline). */
+  query(queryId: string, params?: Record<string, unknown>): Promise<AggregateRow[]>;
+
+  /**
+   * LOCAL-FIRST write: author an intent under the workspace's INSTALLED law (resolved from
+   * the pulled ledger — works fully offline) and commit it to the local ledger. Returns the
+   * new local head; the write becomes durable on the cloud via `sync()`. A law refusal
+   * throws, verbatim — the write never silently disappears. `domainHash` is required: it is
+   * the content hash of the installed law you are authoring under (the generated client
+   * bakes it in).
+   */
+  dispatch(domain: string, directiveId: string, payload: unknown, opts: { domainHash: string }): Promise<string>;
+
+  /**
+   * Watch a declared query: polls the local projection and fires `cb(rows)` whenever the
+   * result changes (purely local — sync separately). Returns a `stop()` function.
+   */
+  watch(queryId: string, params: Record<string, unknown> | undefined, cb: (rows: AggregateRow[]) => void, opts?: { intervalMs?: number }): () => void;
+
+  /** Watch a single aggregate id (local reactive read, like {@link Holon.watch}). Returns a `stop()` function. */
+  watchById(aggregateId: string, cb: (rows: AggregateRow[]) => void, opts?: { intervalMs?: number }): () => void;
+
+  /** A declared count's maintained O(1) value from the LOCAL projection. */
+  count(countId: string, groupKey?: string): Promise<number>;
+
+  /** A declared sum's maintained O(1) total from the LOCAL projection. */
+  sum(sumId: string, groupKey?: string): Promise<number>;
+
+  /**
+   * SYNC — the offline-first exchange: push local commits to the untrusted session branch
+   * (the edge holon validates and merges to main — admission, not trust), then converge
+   * onto canonical main in the same call. With `admit: false` the push lands but the edge
+   * is not asked to judge now (pushes also self-admit via a debounced alarm).
+   */
+  sync(opts?: { admit?: boolean }): Promise<SyncResult>;
+
+  /**
+   * PULL — incremental convergence onto canonical main on demand: fetch origin main; if
+   * unchanged, `{ upToDate: true }`. Otherwise adopt the remote head (the projection
+   * re-folds from it at the next query) and rebase-replay the local-only intents the
+   * canon doesn't already carry.
+   */
+  pull(): Promise<PullResult>;
+
+  /**
+   * EXPORT — serialize the workspace directory (the bare nomos.git ledger + manifests +
+   * dead letters) to bytes. Persist them anywhere (IndexedDB, a file); hand them back via
+   * `connect({ restoreFrom })` to resume WITHOUT a clone — pending un-synced commits included.
+   */
+  export(): Promise<Uint8Array>;
+
+  /**
+   * The DEAD-LETTER QUEUE: refused-but-legitimate intents with full provenance. Refused
+   * work is NEVER lost — it parks here (durably; rides export/restore) until the app
+   * retries it (after a law fix) or explicitly discards it. The raw intent bytes stay in
+   * the queue but are not returned here — only the metadata.
+   */
+  deadLetters(): Promise<DeadLetter[]>;
+
+  /**
+   * Retry one dead-lettered intent by id (or short oid) — the UNJAM after the domain dev
+   * ships a law fix: pulls canon first (it may already be admitted), else re-applies
+   * locally so it rides the next sync. Resolves (removes) the entry on success; on
+   * refusal the entry stays with its error refreshed.
+   */
+  retryDeadLetter(id: string): Promise<RetryDeadLetterResult>;
+
+  /** Discard one dead letter by id (or short oid) — the APP's explicit choice, never the runtime's. */
+  discardDeadLetter(id: string): Promise<{ ok: boolean; removed: number }>;
+
+  /** Runtime vitals: the wasm instance's current linear-memory footprint in MiB. */
+  stats(): { wasmLinearMemMB: number };
+}
+
+/**
+ * Open a LOCAL holon for `workspace`, hydrated from Nomos Cloud: fetches the
+ * byte-identical holon wasm the edge runs, git-pulls the workspace ledger `main`, and
+ * replays it locally — verifying as it goes (content-addressed law; custody is never
+ * trusted). The returned {@link Holon} reads and writes entirely locally; `sync()` is
+ * the only exchange with the cloud.
+ */
+export function connect(opts: ConnectOptions): Promise<Holon>;