@lotics/app-sdk 0.96.0 → 0.97.0

package/AGENTS.md

@@ -20,7 +20,7 @@ signature; open the file.**
 | [docs/mutations.md](./docs/mutations.md) | `useWorkflow` (the ONLY write path), the `WorkflowResult` resolve-never-throw contract (`field_errors` locates a refusal on the control it belongs to, where `message` can only say it at the dialog's scope), typed inputs, the automatic re-read a SUCCESSFUL write triggers over every mounted query (so a screen never waits on the host push to see its own write), diff-before-update, locked records, `useOptimistic`, `useNewRecord` (client-minted `rec_*` id so a new-record surface never remounts on its first save), read-after-write ordering (a re-read must not overtake an in-flight write). |
 | [docs/workflows.md](./docs/workflows.md) | **The workflow-BODY authoring reference** — the JS subset a `src/workflows/<alias>.ts` body may use: the parse-at-save/never-execute model, opaque `fld_*`/`opt_*` keys, expression sources + explicit `linked()` descent, every step form (tool call, `agent`, waits, `validate`, `return`), the accepted sugar and its canonical lowering, helpers + callback rules, record-write surfaces, the traps, the bright line, and the verify loop — `check` (the only local gate: the app's own `npm run typecheck` never sees a body) → `dry_run_workflow` (static green is not a run) → `set`. |
 | [docs/files.md](./docs/files.md) | Files end to end — `useFileUpload`, `useAttachments` (**the add-queue, and which lifecycle it keeps**: a composer clears, a record passes `landed` and each entry leaves as the stored pile takes it over), `readFiles`/presigned URLs (**a bearer credential for the bytes** — never logged, reported, or persisted), workflow-generated files, **naming a zip's entries** (`{ id, name }` per file — a file name, never a path), preview pairing, filter operators, the server-side delivery bounds. **Uploads declare a `fidelity`** (`standard` / `high` / `original`) — the app picks how much of the image survives storage; use `high` whenever text must stay legible. |
-| [docs/members_and_options.md](./docs/members_and_options.md) | People + select options + stage dates + comments — `useMembers`, `useFieldOptions` (keyed by the alias's OWN columns, every key optional), `useViewer`, `useLifecycleHistory` (option id → the instant the row most recently entered it, folded server-side from the record's audit trail; an option never entered is absent), `useComments` (each comment carries its own resolved `author`, so a thread crossing a role boundary is legible without declaring member access), and the `@lotics/ui` components they feed. |
+| [docs/members_and_options.md](./docs/members_and_options.md) | People + select options + comments — `useMembers`, `useFieldOptions` (keyed by the alias's OWN columns, every key optional), `useViewer`, `useComments` (each comment carries its own resolved `author`, so a thread crossing a role boundary is legible without declaring member access), and the `@lotics/ui` components they feed. |
 | [docs/navigation_and_state.md](./docs/navigation_and_state.md) | `AppRouter` (embedded/standalone URL model), `useUrlState` + `urlParam` codecs, `useRecents`. |
 | [docs/ai.md](./docs/ai.md) | `useAgentRun` (structured vs free-text, streaming ai-sdk `parts` → `AgentRun`, the agent's ask-back — `pendingChoice`/`answerChoice` over the parked `awaiting_input` state — and the `AgentRunLanding` every leg resolves), `askAi` — plus the fields-vs-file razor for choosing between them — and `useAiContext` (push the current screen's view state to the member's ambient chat agent; caps, push-only semantics; a chat mutation refetches your queries through the realtime channel, not a separate poke). **A `file` input carries its own content** — no reader tool to declare. **An agent reaches record DATA only through its declared `query_aliases` / `workflow_aliases`.** Also **what the member's own chat agent can do with your app while it is open** — the alias catalog it reads and how to shape a mutating alias for it. |
 | [docs/security.md](./docs/security.md) | **Read before shipping** — the owner-principal model, `is_current_member` scoping, write attribution, group gates, public-app bounds, what runtime refinement cannot widen, and why a per-input bound is a tenancy floor rather than an authorization check (a caller-supplied id must be intersected with the record server-side). |

package/dist/src/index.d.ts

@@ -20,8 +20,6 @@ export type { QueryRow, RowOf, UploadedFile, BaseQueryOptions, QueryOptions, Inf
 export type { AttachedFile, AttachmentsOptions, AttachmentsState } from "./attachments.js";
 export { useComments, useCommentCounts } from "./comments.js";
 export type { AppComment, AppCommentAuthor, AppCommentFile, CommentsState, UseCommentsArgs, CommentCountsState, UseCommentCountsArgs, } from "./comments.js";
-export { useLifecycleHistory } from "./lifecycle_history.js";
-export type { LifecycleHistory, LifecycleHistoryArgs } from "./lifecycle_history.js";
 export { useViewer } from "./viewer.js";
 export { requestGeofencedLocation, isWithinZone } from "./geolocation.js";
 export type { GeofenceZone, GeoCoords, GeofenceOutcome, GeofenceOptions } from "./geolocation.js";

package/dist/src/index.js

@@ -16,7 +16,6 @@
 export { mount } from "./mount.js";
 export { useWorkflow, useQuery, useInfiniteQuery, usePaginatedQuery, useCount, useFieldOptions, useFileUpload, useAttachments, useMembers, useAgentRun, useAgentRuns, useAiContext, buildChoiceOutput, } from "./hooks.js";
 export { useComments, useCommentCounts } from "./comments.js";
-export { useLifecycleHistory } from "./lifecycle_history.js";
 export { useViewer } from "./viewer.js";
 export { requestGeofencedLocation, isWithinZone } from "./geolocation.js";
 export { rpc, isEmbedded } from "./rpc.js";

package/dist/src/rpc.d.ts

@@ -21,7 +21,7 @@ import { type UrlParams, type UrlParamsPatch } from "./url_params.js";
  *   app  → host: { id, op, payload }
  *   host → app:  { id, type: "result", data } | { id, type: "error", message }
  */
-export type RpcOp = "query" | "field_options" | "field_history" | "workflow" | "agentRuns" | "agentRun.get" | "agentRun.cancel" | "upload" | "members" | "context" | "openExternal" | "openApp" | "askAi" | "urlState.get" | "urlState.set" | "comments.list" | "comments.create" | "comments.update" | "comments.delete" | "comments.counts";
+export type RpcOp = "query" | "field_options" | "workflow" | "agentRuns" | "agentRun.get" | "agentRun.cancel" | "upload" | "members" | "context" | "openExternal" | "openApp" | "askAi" | "urlState.get" | "urlState.set" | "comments.list" | "comments.create" | "comments.update" | "comments.delete" | "comments.counts";
 /** Payload for starting a streaming agent run. */
 export interface AgentRunPayload {
     alias: string;

package/dist/src/rpc.js

@@ -703,8 +703,6 @@ function rpcStandalone(op, payload) {
             return standaloneQuery(payload);
         case "field_options":
             return standaloneFieldOptions(payload);
-        case "field_history":
-            return standaloneFieldHistory(payload);
         case "workflow":
             return standaloneWorkflow(payload);
         case "agentRuns":
@@ -753,17 +751,6 @@ function rpcStandalone(op, payload) {
 function rejectCommentsStandalone() {
     return Promise.reject(new Error("Comments are available only in embedded apps — a signed-in member is required."));
 }
-/**
- * When the row entered each stage — the public-app half of `field_history`.
- * The endpoint is app-authority and `publicAppAccess`, so an anonymous visitor
- * of a shared app reads exactly the dates its own queries already earn it.
- */
-async function standaloneFieldHistory(p) {
-    const { app_id } = await boot();
-    const qs = new URLSearchParams({ table_id: p.table_id, field_id: p.field_id });
-    const r = (await apiCall("GET", `/v1/apps/${app_id}/records/${encodeURIComponent(p.record_id)}/field-history?${qs.toString()}`, undefined, { appId: app_id }));
-    return { entered: r.entered ?? [] };
-}
 async function standaloneMembers(p) {
     const { app_id } = await boot();
     const qs = p.group ? `?group_id=${encodeURIComponent(p.group)}` : "";

package/docs/members_and_options.md

@@ -2,10 +2,10 @@
 
 How an app renders and picks **people** and **select-field options**, plus the **record comments**
 surface. Covers the two cell readers (`readSelect`, `readMembers`), the two catalog hooks
-(`useFieldOptions`, `useMembers`), the viewer identity hook (`useViewer`), when a row entered each
-stage (`useLifecycleHistory`), comments (`useComments`, `useCommentCounts`), and the `@lotics/ui`
-components they feed. Read this before building an assign picker, a colored `Status` mark, a
-pipeline with dates against its steps, a per-viewer ("my records") screen, or a comment thread. Query mechanics live in [queries](./queries.md); the authority model in
+(`useFieldOptions`, `useMembers`), the viewer identity hook (`useViewer`), comments
+(`useComments`, `useCommentCounts`), and the `@lotics/ui` components they feed. Read this before
+building an assign picker, a colored `Status` mark, a per-viewer ("my records") screen, or a
+comment thread. Query mechanics live in [queries](./queries.md); the authority model in
 [security](./security.md).
 
 ## Cells vs. catalogs — the model
@@ -18,7 +18,6 @@ Every select and member value reaches the app in one of two shapes, and most scr
 | Populate a select picker, or color a stored value | `useFieldOptions(alias)` | Each select column's **complete** option list — `{ key, label, color }` — plus a `byKey` index |
 | Render a stored member value | `readMembers(cell)` | The members the record actually holds |
 | Populate a member picker (assign UIs) | `useMembers(opts?)` | The org roster — every member, not only the referenced ones |
-| Date each step of a pipeline | `useLifecycleHistory(args)` | When the row entered each option — `Map<option id, ISO instant>` |
 
 Cells are **self-describing**: the server rewrites raw storage shapes into resolved objects before
 rows reach the app, so an app never maintains a hardcoded key→label or id→name map. Catalogs are
@@ -238,45 +237,6 @@ template via the `is_current_member` filter operator — the server binds the sa
 view-as) with nothing client-supplied to spoof. Write attribution belongs server-side in the
 workflow body (`runtime.triggered_by_member_id`). Full model: [security](./security.md).
 
-## When the row entered each stage: `useLifecycleHistory`
-
-A pipeline drawn as steps has to say **when** each step happened, and the record carries only where
-it is. The platform is the one that knows: every write to a record lands an audit entry carrying the
-field diff, so the instants are folded server-side and arrive ready to render.
-
-```tsx
-const { entered, loading, error } = useLifecycleHistory({
-  table_id: row.__source_table_id,   // the record's table
-  record_id: row.__source_record_id, // the record itself
-  field_id: "fld_stage",             // the lifecycle select
-});
-
-<Step label={option.label} at={entered.get(option.key)} />
-```
-
-- `entered` is `ReadonlyMap<option id, ISO 8601 instant>`. The stage the row is on **now** is in
-  there too. An option the row never entered is **absent** — read "no date" as "never been there",
-  and never as "not loaded yet" (that is `loading`).
-- The instant is the **most recent** entry into that option, so a row that left a stage and came
-  back is dated by the return. A write that re-states the stage the row is already on changes
-  nothing and dates nothing; on a multi-value select, adding an option does not re-date the ones the
-  cell kept.
-- Keyed by `opt_` ids, so a renamed option keeps its date.
-- `field_id` names a **select** — the only field whose values are option ids. Anything else is
-  refused.
-- Every part of the address must be a **real** id; an empty string fetches nothing and answers an
-  empty map. Narrow `__source_record_id` / `__source_table_id` first — a grouped query emits
-  neither.
-- The authority IS a declared query: before it answers, the server runs one of the app's own
-  declarations over that table, narrowed to this record, and refuses unless it comes back. A table
-  none of them reads is refused; so is a row their filters or the table's row rule exclude. No
-  member table grant is needed, and none is a way in.
-- `error` carries why a read failed, as the SDK's other hooks do. An empty `entered` alone cannot
-  say it — draw the failure rather than an undated strip.
-- **Freshness:** SWR-cached, keyed by (table, record, field) — two steps of one lifecycle buy one
-  read. An audit entry emits no record event, so a stage moved elsewhere appears after this app's
-  own write (which re-reads every mounted query) or on the next focus.
-
 ## Comments: `useComments` / `useCommentCounts`
 
 Record comments — member-to-member discussion attached to any record the app reaches

package/docs/security.md

@@ -9,7 +9,6 @@ Every data operation an app performs — queries, workflows, agent runs — exec
 | Named queries (`useQuery`, the query RPC) | App owner | Yes — bound server-side into `is_current_member` / `current_member` filter predicates |
 | Workflows (`useWorkflow`) | App owner | Yes — `runtime.triggered_by_member_id` in the workflow body (`null` for anonymous) |
 | Agent runs (`useAgentRun`) | App owner | Yes — requires an authenticated member; runs are private to that member |
-| Stage history (`useLifecycleHistory`) | App owner — proven by running a declared query narrowed to that record, so reach is the query surface's | Only as a declared query's own `is_current_member` resolves it |
 | Comments (`useComments`) | App authority for **access**; the **author** is always the real member | Always — members-only, anonymous callers are rejected |
 
 Consequences of owner authority:
@@ -99,7 +98,6 @@ A publicly-shared app (its own origin, or its public link) is reachable by **any
 | File upload (workflow `file` inputs) | Yes — bounded to the app's workspace |
 | Query/workflow file outputs | Yes — file cells and workflow-produced files return direct presigned URLs (24-hour TTL) that anonymous viewers can fetch; see [files](./files.md) |
 | Agent runs (`useAgentRun`) | **No** — rejected: agent runs require an authenticated member, and each member's run history is private to them (a guessed session id cannot read another member's thread) |
-| Stage history (`useLifecycleHistory`) | Yes — for a row a declared query hands back, which is the same IDOR surface as the query itself |
 | Comments (`useComments`) | **No** — members-only |
 | Member roster (`useMembers`) | **No** — same-org members only (below) |
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/app-sdk",
-  "version": "0.96.0",
+  "version": "0.97.0",
   "description": "Runtime SDK for Lotics custom-code apps \u2014 typed hooks, postMessage bridge, mount entry point",
   "type": "module",
   "exports": {

package/dist/src/lifecycle_history.d.ts

@@ -1,26 +0,0 @@
-export interface LifecycleHistoryArgs {
-    /** The table the record lives in. */
-    table_id: string;
-    /** The record whose walk to date. */
-    record_id: string;
-    /** The `fld_` id of the lifecycle select. */
-    field_id: string;
-}
-export interface LifecycleHistory {
-    /**
-     * Option id → the ISO 8601 instant the row MOST RECENTLY entered it. The
-     * stage the row is on now is in here too; an option it never entered is
-     * absent rather than present with an empty value, so a caller reads "no date"
-     * as "never been there".
-     */
-    entered: ReadonlyMap<string, string>;
-    /** True on the first load only — false during a background revalidation. */
-    loading: boolean;
-    /**
-     * Why the read failed, or `null`. An undated strip and a strip whose dates
-     * could not be read look identical, so the caller is told which it is holding
-     * rather than drawing "never entered" over a failure.
-     */
-    error: string | null;
-}
-export declare function useLifecycleHistory(args: LifecycleHistoryArgs): LifecycleHistory;

package/dist/src/lifecycle_history.js

@@ -1,41 +0,0 @@
-/**
- * `useLifecycleHistory` — when the row entered each stage.
- *
- * A pipeline drawn as steps has to say when each step happened, and the record
- * carries only where it IS. The platform is the one that knows: every write to
- * a record lands an audit row carrying the field diff, so the instants are
- * derived server-side and arrive already folded — one entry per option the row
- * entered, dated by the MOST RECENT entry into it.
- *
- * The field is a `select`, which is what a lifecycle is, and the keys of
- * `entered` are its `opt_` ids — never a rendered label, so a renamed option
- * keeps its date.
- *
- * SWR-cached like every other read hook: keyed by (table, record, field), so
- * two steps of the same lifecycle share one fetch and the cache survives a
- * remount. There is no realtime channel for an audit row, so a stage moved in
- * another tab appears on the next focus or after the write that moved it
- * invalidates this app's queries.
- */
-import { useMemo } from "react";
-import useSWR from "swr";
-import { rpc } from "./rpc.js";
-const NOTHING = new Map();
-export function useLifecycleHistory(args) {
-    const { table_id, record_id, field_id } = args;
-    // Every part of the address has to be real: a hook cannot be called
-    // conditionally, and a blank id would fetch the history of nothing and cache
-    // the empty answer under a key a real id later reads.
-    const addressed = table_id !== "" && record_id !== "" && field_id !== "";
-    const swr = useSWR(addressed ? ["app-field-history", table_id, record_id, field_id] : null, () => rpc("field_history", { table_id, record_id, field_id }), { shouldRetryOnError: false });
-    const entered = useMemo(() => {
-        if (!swr.data)
-            return NOTHING;
-        return new Map(swr.data.entered.map((entry) => [entry.option_id, entry.entered_at]));
-    }, [swr.data]);
-    return {
-        entered,
-        loading: addressed && swr.data === undefined && swr.error === undefined,
-        error: swr.error ? swr.error.message : null,
-    };
-}