akanjs 3.0.0-beta.2 → 3.0.0-beta.20

package/signal/trace.ts

@@ -7,40 +7,20 @@ import {
   type LogRecord,
   logSeverity,
   registerLogContextReader,
+  round,
 } from "akanjs/common";
 
-/**
- * Request tracing for Akan signals, in two modes.
- *
- * `context` is on by default, production included: it carries only the identity a log record needs
- * (`traceId`, endpoint, origin) and costs one `als.run` per call (~25ns measured). `AKAN_LOG_CONTEXT=0` is
- * the emergency exit. `full` adds the per-stage spans, query counts and cache ratio the metrics endpoint
- * aggregates, and stays behind `AKAN_TRACE=1` because those are for performance work, not for every request.
- *
- * Two opt-ins ride the same trace: the canonical request line (`AKAN_LOG_CANONICAL`) summarizes every call as
- * one record at its end, and the flight recorder (`AKAN_LOG_FLIGHT`) keeps the call's own sub-level records
- * and promotes them only when the call failed or ran long.
- */
-
 let traceEnabledCache: boolean | null = null;
 let logContextEnabledCache: boolean | null = null;
 
-/** Whether full request tracing (`AKAN_TRACE=1`) is enabled. Cached after first read. */
-export const isTraceEnabled = (): boolean => {
-  if (traceEnabledCache === null) traceEnabledCache = process.env.AKAN_TRACE === "1";
-  return traceEnabledCache;
-};
+export const isTraceEnabled = (): boolean => (traceEnabledCache ??= process.env.AKAN_TRACE === "1");
 
-/** Override the trace flag at runtime (tests / harness control). */
 export const setTraceEnabled = (enabled: boolean): void => {
   traceEnabledCache = enabled;
 };
 
-export const isLogContextEnabled = (): boolean => {
-  if (logContextEnabledCache === null)
-    logContextEnabledCache = !(process.env.AKAN_LOG_CONTEXT === "0" || process.env.AKAN_LOG_CONTEXT === "false");
-  return logContextEnabledCache;
-};
+export const isLogContextEnabled = (): boolean =>
+  (logContextEnabledCache ??= !(process.env.AKAN_LOG_CONTEXT === "0" || process.env.AKAN_LOG_CONTEXT === "false"));
 
 export const setLogContextEnabled = (enabled: boolean): void => {
   logContextEnabledCache = enabled;
@@ -64,10 +44,7 @@ export const setCanonicalLineMode = (mode: CanonicalLineMode): void => {
 };
 
 let flightEnabledCache: boolean | null = null;
-export const isFlightRecorderEnabled = (): boolean => {
-  if (flightEnabledCache === null) flightEnabledCache = isOn(process.env.AKAN_LOG_FLIGHT);
-  return flightEnabledCache;
-};
+export const isFlightRecorderEnabled = (): boolean => (flightEnabledCache ??= isOn(process.env.AKAN_LOG_FLIGHT));
 export const setFlightRecorderEnabled = (enabled: boolean): void => {
   flightEnabledCache = enabled;
   refreshLoggerContextGate();
@@ -86,11 +63,6 @@ export const setFlightThresholdMs = (ms: number): void => {
   flightThresholdCache = ms;
 };
 
-/**
- * `x-akan-debug` lowers one request's log floor to `trace`. Honoured in `local` unconditionally, and elsewhere only
- * when the header carries the value of `AKAN_LOG_DEBUG_HEADER`: a client that can lower a server's log level is a
- * log-volume vector, so outside development it has to prove it was told the secret.
- */
 export const isDebugHeaderAllowed = (): boolean =>
   process.env.AKAN_PUBLIC_ENV === "local" || !!process.env.AKAN_LOG_DEBUG_HEADER;
 
@@ -108,7 +80,6 @@ export type TraceOrigin = "http" | "websocket" | "mcp" | "internal" | "page";
 export type TraceOutcome = "ok" | "error";
 
 const MAX_SPANS_PER_TRACE = 64;
-/** Per call; 64 lines is a whole request at `trace` for anything short of a loop that logs per row. */
 const FLIGHT_RING_SIZE = 64;
 const CANONICAL_ERROR_CHARS = 200;
 
@@ -117,7 +88,6 @@ interface FlightEntry {
   written: boolean;
 }
 
-/** Per-request trace context. Threaded via {@link AsyncLocalStorage}. */
 export class SignalTrace {
   /** Total captured records the process holds at once (`AKAN_LOG_FLIGHT_MAX`); a call past it runs unrecorded. */
   static readonly defaultFlightMaxRecords = 65_536;
@@ -131,7 +101,6 @@ export class SignalTrace {
   readonly mode: TraceMode;
   readonly startedAt: number;
   readonly spans: SpanRecord[] = [];
-  /** What the canonical line carries beyond timing — `userId` once the caller is known. */
   readonly attrs: LogAttrs = {};
   dbQueryCount = 0;
   dbQueryMs = 0;
@@ -161,7 +130,7 @@ export class SignalTrace {
     this.traceId = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
   }
 
-  /** The trace a call runs under given what is switched on, or `null` when both modes are off. */
+  /** `null` when both modes are off. */
   static create(endpointKey: string, endpointType: string, origin: TraceOrigin): SignalTrace | null {
     const trace = isTraceEnabled()
       ? new SignalTrace(endpointKey, endpointType, { mode: "full", origin })
@@ -189,7 +158,6 @@ export class SignalTrace {
     return `${this.endpointType}:${this.endpointKey}`;
   }
 
-  /** Attaches the ring unless the process is already holding its cap; a trace past the cap simply is not recorded. */
   startFlightRecorder(): boolean {
     if (this.#flightRing || this.#finalized) return !!this.#flightRing;
     if (SignalTrace.#activeFlights >= SignalTrace.#flightMaxTracesFromEnv()) return false;
@@ -314,22 +282,14 @@ const traceProcessStore = process as unknown as {
   __akanTraceAggregator?: TraceAggregator;
 };
 
-let alsInstance = traceProcessStore.__akanTraceAls;
-if (!alsInstance) {
-  alsInstance = new AsyncLocalStorage<SignalTrace>();
-  traceProcessStore.__akanTraceAls = alsInstance;
-}
-const als = alsInstance;
+traceProcessStore.__akanTraceAls ??= new AsyncLocalStorage<SignalTrace>();
+const als = traceProcessStore.__akanTraceAls;
 
 export const getCurrentTrace = (): SignalTrace | undefined => als.getStore();
 
-/** Run `fn` with `trace` as the ambient request trace. */
 export const runWithTrace = <T>(trace: SignalTrace, fn: () => T): T => als.run(trace, fn);
 
-/**
- * Run `fn` as the whole life of `trace`: a throw marks the outcome before it propagates, and the trace is
- * finalized after the caller's own catch has run — which is what lets an error log carry the traceId.
- */
+/** Finalizes `trace` after the caller's own catch has run, which is what lets an error log carry the traceId. */
 export const runTraced = async <T>(trace: SignalTrace | null, fn: () => Promise<T>): Promise<T> => {
   if (!trace) return await fn();
   return await als.run(trace, async () => {
@@ -357,10 +317,6 @@ registerLogContextReader(() => {
 });
 refreshLoggerContextGate();
 
-/**
- * Time an async stage under the current trace. When tracing is off (or no trace is
- * active) this is a thin passthrough with no measurement overhead.
- */
 export const traceSpan = async <T>(name: string, fn: () => Promise<T>): Promise<T> => {
   const trace = getCurrentTrace();
   if (trace?.mode !== "full") return await fn();
@@ -372,17 +328,14 @@ export const traceSpan = async <T>(name: string, fn: () => Promise<T>): Promise<
   }
 };
 
-/** Record a DB query duration against the current trace (no-op when untraced). */
 export const traceDbQuery = (durationMs: number): void => {
   getCurrentTrace()?.countDbQuery(durationMs);
 };
 
-/** Record a cache hit/miss against the current trace (no-op when untraced). */
 export const traceCache = (hit: boolean): void => {
   getCurrentTrace()?.countCache(hit);
 };
 
-/** Record a DataLoader batch against the current trace (no-op when untraced). */
 export const traceDataLoaderBatch = (keyCount: number): void => {
   getCurrentTrace()?.countDataLoaderBatch(keyCount);
 };
@@ -415,11 +368,6 @@ const percentile = (sorted: number[], p: number): number => {
   return sorted[idx] ?? 0;
 };
 
-/**
- * Process-wide aggregator. Keeps rolling per-endpoint, per-span statistics with a
- * bounded sample ring per span so percentiles stay representative of steady state
- * without unbounded memory growth.
- */
 class TraceAggregator {
   #endpoints = new Map<string, EndpointStat>();
 
@@ -466,7 +414,6 @@ class TraceAggregator {
     this.#endpoints.clear();
   }
 
-  /** Summarized snapshot suitable for JSON exposure on the metrics endpoint. */
   snapshot() {
     const endpoints = [...this.#endpoints.values()].map((stat) => {
       const spans = [...stat.spans.entries()].map(([name, s]) => {
@@ -500,31 +447,11 @@ class TraceAggregator {
   }
 }
 
-const round = (value: number, digits = 3): number => {
-  const factor = 10 ** digits;
-  return Math.round(value * factor) / factor;
-};
-
-let aggregatorInstance = traceProcessStore.__akanTraceAggregator;
-if (!aggregatorInstance) {
-  aggregatorInstance = new TraceAggregator();
-  traceProcessStore.__akanTraceAggregator = aggregatorInstance;
-}
-export const traceAggregator: TraceAggregator = aggregatorInstance;
+traceProcessStore.__akanTraceAggregator ??= new TraceAggregator();
+export const traceAggregator: TraceAggregator = traceProcessStore.__akanTraceAggregator;
 
-/** Snapshot of all aggregated trace stats. Safe to call when tracing is disabled. */
 export const getTraceSnapshot = () => traceAggregator.snapshot();
 
-/**
- * Optional file sink for the aggregated snapshot.
- *
- * The akan worker loads the app-server bundle and the framework metrics collector in
- * separate module realms that share neither `globalThis` nor `process`, so the in-realm
- * aggregator that records spans cannot be read by the metrics endpoint's collector. When
- * `AKAN_TRACE_FILE` is set, the recording realm instead flushes the cumulative snapshot to
- * that path (throttled), where any external reader (e.g. the benchmark harness) can pick it
- * up. This is a benchmarking/diagnostics aid, not a production hot-path concern.
- */
 const traceFilePath = process.env.AKAN_TRACE_FILE;
 let lastTraceFlushAt = 0;
 const TRACE_FLUSH_INTERVAL_MS = 1_000;

package/signal/types.ts

@@ -52,6 +52,8 @@ interface InitOption {
   serverMode?: "federation" | "batch" | "all";
   operationMode?: ("cloud" | "edge" | "local" | (string & {}))[];
   enabled?: boolean;
+  /** Instances booting together take turns and one that waited skips its own run; unset, every instance runs it. */
+  once?: boolean;
 }
 
 interface TimerOption {
@@ -81,42 +83,32 @@ export interface SignalOption<Response = any, Nullable extends boolean = false,
   default?: boolean;
   path?: string;
   serverMode?: "federation" | "batch" | "all";
+  /**
+   * Milliseconds; the server rejects with `base.error.gatewayTimeout` and the client sizes its request budget from
+   * it. Losing the race does not stop the handler, which runs to completion with nobody holding its result.
+   */
   timeout?: number;
   partial?: _Key[] | readonly _Key[];
+  /**
+   * Milliseconds to reuse the answer, keyed by endpoint and arguments; unset caches nothing. Only a `query` with no
+   * internal argument may carry one (those answer per caller), and the lookup runs after the guards.
+   */
   cache?: number;
   guards?: GuardCls[];
   middlewares?: MiddlewareCls[];
   prefix?: false | string;
   globalPrefix?: false;
-  /**
-   * HTTP verb for a `mutation`, `POST` unless named. Only a foreign wire protocol needs the others — a client
-   * that cannot be changed and sends `PATCH /rest/v1/<table>`. Every other endpoint type ignores it.
-   */
+  /** HTTP verb of a `mutation`, `POST` unless named; every other endpoint type ignores it. */
   method?: HttpMutationMethod;
-  /** Marks this mutation as the framework file-upload endpoint (see resolveFileUploadCapability). */
   fileUpload?: boolean;
-  /**
-   * Whether this endpoint belongs on an agent's shelf. `true` — the default — publishes it to MCP subject to the
-   * guard and shape rules; `false` keeps it out of the catalogue entirely.
-   *
-   * This is curation, not authorization: HTTP serves the endpoint exactly as before, and the guards are still the
-   * only thing deciding who may call it. Write it where an endpoint is perfectly guarded and still has no business
-   * on a shelf — a step of a UI-driven state machine (`requestPhoneCodeForSignin`), or a read a model would only
-   * ever call by mistake. Every catalogue entry carries the model schemas it mentions, so one endpoint dropped
-   * here is kilobytes off every `tools/list`.
-   */
+  /** `false` keeps it out of the MCP catalogue (default `true`); curation, not authorization — HTTP still serves it. */
   mcp?: boolean;
   /**
-   * What a `pubsub(Binary)` does when a subscriber cannot keep up. `"coalesce"` (the default) keeps only the
-   * newest frame per room, which is what a telemetry or video stream wants — an old frame is worthless once a
-   * newer one exists. Name `"queue"` when the frames are a sequence a subscriber has to see in full, such as
-   * deltas against a base it already holds; the send buffer then grows with the slowest subscriber.
+   * A slow subscriber of a `pubsub(Binary)`: `"coalesce"` (default) keeps only the newest frame per room, `"queue"`
+   * delivers every frame and grows the send buffer with the slowest subscriber.
    */
   backpressure?: "coalesce" | "queue";
-  /**
-   * Set by the resolver on the pubsub endpoint it generates for a `.live()` slice, never by hand. It carries what
-   * the room needs to route a change — which model, and how the slice asked to be treated.
-   */
+  /** Set by the resolver on the pubsub endpoint it generates for a `.live()` slice, never by hand. */
   live?: LiveEndpointOption;
 
   scheduleType?: "init" | "destroy" | "cron" | "interval" | "timeout";
@@ -134,25 +126,13 @@ interface SerializedSignalOption {
   guards?: string[];
   method?: HttpMutationMethod;
   fileUpload?: boolean;
-  /**
-   * Only ever `false`, and only when something declared it: `true` is the default, so serializing it would ship a
-   * field per endpoint that says nothing. Resolved here rather than left to the reader because the browser API
-   * explorer has guard *names* and no classes, and a second implementation of the rule would eventually disagree
-   * with the catalogue.
-   */
+  /** Only ever `false`, when declared. Resolved here because the API explorer holds guard names, not classes. */
   mcp?: false;
-  /**
-   * Only ever `false`, and only when one of the guards declares `static agents = false`: a person-only act. Resolved
-   * here for the same reason `mcp` is — the reader holds guard names, not classes.
-   */
+  /** Only ever `false`, when a guard declares `static agents = false` (a person-only act). */
   agents?: false;
 }
 export interface SerializedSlice extends SerializedSignalOption {
-  /**
-   * Present when the slice declared `.live()`. `sort` is the allowlist of sort keys a subscriber may place a new
-   * row under itself; on any other sort an insertion refetches instead of guessing where the row goes. `pauseOn`
-   * names the arguments that switch the room off while they carry a value, and travels only when there are any.
-   */
+  /** `sort`: keys a subscriber may place a new row under itself (others refetch); `pauseOn` travels only when set. */
   live?: { sort: string[]; pauseOn?: string[] };
 }
 
@@ -172,23 +152,20 @@ export interface SerializedArg {
   nullable?: boolean;
   example?: string | number | boolean | Date;
   enum?: string;
-  /** The values this arg accepts, when they are a fixed list the caller has to pick from. */
   oneOf?: (string | number)[];
-  /** For an id a filter declared against a model: the model it points at, so a UI can offer a picker. */
+  /** The model a filter's id argument points at, so a UI can offer a picker. */
   ref?: string;
 }
 export interface SerializedEndpoint extends SerializedSignalOption {
   type: "query" | "mutation" | "pubsub" | "message";
   returns: SerializedReturns;
+  /** Milliseconds; the client sizes its request budget from it. */
+  timeout?: number;
 }
 export interface SerializedFilter {
-  /** Every filter query the model declares, by key, with the args each one takes. */
   filter: { [key: string]: SerializedArg[] };
   sortKeys: string[];
-  /**
-   * The field map behind each sort key, which a live subscriber needs to place a new row without asking the server
-   * where it goes. Only the keys a `.live({ sort })` allowlist names are ever compared against it.
-   */
+  /** The field map behind each sort key, which a live subscriber needs to place a new row itself. */
   sorts?: { [key: string]: { [path: string]: 1 | -1 } };
 }
 
@@ -202,10 +179,7 @@ export interface SerializedSignal {
   createGuards?: string[];
   updateGuards?: string[];
   removeGuards?: string[];
-  /**
-   * Which generated CRUD verbs this model keeps off the agent shelf. Carried on the signal because the endpoints
-   * it names do not exist until `FetchClient.getBaseEndpoint` synthesizes them. Only the `false` keys travel.
-   */
+  /** Generated CRUD verbs kept off the agent shelf, carried here because `FetchClient.getBaseEndpoint` synthesizes them. */
   mcp?: SerializedSignalMcp;
   /** Which generated CRUD verbs a person-only guard protects, by the same verb map; only the `false` keys travel. */
   agents?: SerializedSignalMcp;
@@ -224,11 +198,8 @@ export type SignalType = "restapi" | "websocket";
 export type WebsocketReqData = { key: string; data: unknown[]; subscribe?: boolean };
 export type WebsocketMessageData = { type: "msg"; key: string; data: object | object[] };
 /**
- * One document change, as one live room sees it.
- *
- * The verb is relative to the room and not to the database: a row edited out of a filter arrives as `leave` in the
- * list it left and `enter` in the one it joined, and a soft delete is a `leave` everywhere. `invalidate` carries no
- * document at all — it is what a room that cannot be routed in memory sends instead, and it means refetch.
+ * `op` is relative to the room, not the database: a row edited out of a filter is `leave` there and `enter` where it
+ * joined, a soft delete is `leave` everywhere, and `invalidate` (no document) means refetch.
  */
 export interface LiveEventPayload {
   op: "enter" | "update" | "leave" | "invalidate";
@@ -237,9 +208,8 @@ export interface LiveEventPayload {
 }
 
 /**
- * `roomId` is the room the server actually joined; `requestRoomId` is the one the client built from the arguments
- * it sent. They differ only for a live room, whose id also carries the caller's resolved internal arguments so
- * that two subscribers of the same `inSelf` slice do not share one room. The client re-keys on the pair.
+ * `roomId` is the room the server joined, `requestRoomId` the one the client built; they differ only for a live room,
+ * whose id also carries the caller's internal arguments. The client re-keys on the pair.
  */
 export type WebsocketSubscribeAck = {
   type: "sub";

package/store/SliceRequest.ts

@@ -1,17 +1,7 @@
-/**
- * Which list request for one slice is the current one.
- *
- * Every paging action reads state, fires a fetch, and writes the answer back. Two of them in flight — a user
- * clicking page 2 then page 3 — race, and the *slower* response used to win: the list from one page landed under
- * the page number of another, and the spinner was cleared by whichever finished last. Nothing in the state could
- * say which request a response belonged to, so a ticket says it instead.
- *
- * One per slice rather than per action, because every one of them writes the same `<model>List`.
- */
+/** Which of a slice's in-flight list requests is current, so a slower, older response is dropped. */
 export class SliceRequest {
   #latest = 0;
 
-  /** Takes the next ticket and makes it the current one, so every earlier request is now stale. */
   claim(): number {
     this.#latest += 1;
     return this.#latest;