@synnaxlabs/client 0.56.1 → 0.57.0

package/src/arc/ir/types.gen.ts

@@ -9,7 +9,7 @@
 
 // Code generated by Oracle. DO NOT EDIT.
 
-import { array, record, zod } from "@synnaxlabs/x";
+import { zod } from "@synnaxlabs/x";
 import { z } from "zod";
 
 import { types } from "@/arc/types";
@@ -35,7 +35,10 @@ export enum Liveness {
 }
 export const livenessZ = z.enum(Liveness);
 
-/** Handle is a reference to a specific parameter on a specific node in the dataflow graph. */
+/**
+ * Handle is a reference to a specific parameter on a specific node in the dataflow
+ * graph.
+ */
 export const handleZ = z.object({
   /** node is the node identifier. */
   node: z.string(),
@@ -51,17 +54,12 @@ export const bodyZ = z.object({
 });
 export interface Body extends z.infer<typeof bodyZ> {}
 
-/**
- * Node is a concrete instantiation of a function with typed parameters and
- * configuration values.
- */
+/** Node is a concrete instantiation of a function with typed parameters and values. */
 export const nodeZ = z.object({
   /** key is the unique identifier for this node instance. */
   key: z.string(),
   /** type is the function type being instantiated. */
   type: z.string(),
-  /** config contains configuration parameter values. */
-  config: types.paramsZ,
   /** inputs contains input parameter type signatures. */
   inputs: types.paramsZ,
   /** outputs contains output parameter type signatures. */
@@ -76,7 +74,7 @@ export const authoritiesZ = z.object({
   /** default is the default authority for all write channels not explicitly listed. */
   default: zod.uint8.optional(),
   /** channels maps channel keys to their specific authority values. */
-  channels: record.nullishToEmpty(z.uint32(), zod.uint8),
+  channels: z.record(z.uint32(), zod.uint8).default(() => ({})),
 });
 export interface Authorities extends z.infer<typeof authoritiesZ> {}
 
@@ -96,8 +94,8 @@ export const transitionZ = z.object({
   /** on is the dataflow handle whose truthy value fires this transition. */
   on: handleZ,
   /**
-   * targetKey is the sibling step key to activate. Null when the transition
-   * exits the scope, yielding to the parent.
+   * targetKey is the sibling step key to activate. Null when the transition exits the
+   * scope, yielding to the parent.
    */
   targetKey: z.string().optional(),
 });
@@ -111,9 +109,7 @@ export const functionZ = z.object({
   /** key is the function identifier (template name). */
   key: z.string(),
   /** body is raw source code for user-defined functions. */
-  body: bodyZ.optional(),
-  /** config contains configuration parameter definitions. */
-  config: types.paramsZ,
+  body: bodyZ,
   /** inputs contains input parameter definitions. */
   inputs: types.paramsZ,
   /** outputs contains output parameter definitions. */
@@ -123,20 +119,19 @@ export const functionZ = z.object({
 });
 export interface Function extends z.infer<typeof functionZ> {}
 
-export const nodesZ = array.nullishToEmpty(nodeZ);
+export const nodesZ = nodeZ.array().default(() => []);
 export type Nodes = z.infer<typeof nodesZ>;
 
-export const edgesZ = array.nullishToEmpty(edgeZ);
+export const edgesZ = edgeZ.array().default(() => []);
 export type Edges = z.infer<typeof edgesZ>;
 
-export const functionsZ = array.nullishToEmpty(functionZ);
+export const functionsZ = functionZ.array().default(() => []);
 export type Functions = z.infer<typeof functionsZ>;
 
 /**
- * Member is a tagged union representing a single child of a Scope. Exactly one
- * of nodeKey or scope is set. The member's lookup key (used as the
- * target of `=> name` transitions) is derived from the set variant via
- * Member.key().
+ * Member is a tagged union representing a single child of a Scope. Exactly one of
+ * nodeKey or scope is set. The member's lookup key (used as the target of `=> name`
+ * transitions) is derived from the set variant via Member.key().
  */
 export interface Member {
   nodeKey?: string;
@@ -144,8 +139,8 @@ export interface Member {
 }
 export const memberZ: z.ZodType<Member> = z.object({
   /**
-   * nodeKey is the key of the referenced node in IR.nodes. Null when this
-   * member is a nested scope.
+   * nodeKey is the key of the referenced node in IR.nodes. Null when this member is a
+   * nested scope.
    */
   nodeKey: z.string().optional(),
   /** scope is set when this member is a nested scope. */
@@ -155,10 +150,9 @@ export const memberZ: z.ZodType<Member> = z.object({
 });
 
 /**
- * Scope is the unified Layer 2 execution primitive. Parameterized by mode
- * (parallel or sequential) and liveness (always-live or gated). Parallel
- * scopes organize members into strata; sequential scopes run one step
- * at a time and advance via transitions.
+ * Scope is the unified Layer 2 execution primitive. Parameterized by mode (parallel or
+ * sequential) and liveness (always-live or gated). Parallel scopes organize members
+ * into strata; sequential scopes run one step at a time and advance via transitions.
  */
 export interface Scope {
   key: string;
@@ -174,29 +168,37 @@ export const scopeZ: z.ZodType<Scope> = z.object({
   key: z.string(),
   /** mode defines whether this scope runs steps in parallel or sequentially. */
   mode: scopeModeZ,
-  /** liveness defines whether this scope is continuously active or must be activated. */
+  /**
+   * liveness defines whether this scope is continuously active or must be activated.
+   */
   liveness: livenessZ,
-  /** activation is the handle whose truthy value activates a gated scope. Unset for always-live scopes. */
+  /**
+   * activation is the handle whose truthy value activates a gated scope. Unset for
+   * always-live scopes.
+   */
   activation: handleZ.optional(),
   /**
-   * strata contains stratified execution layers for parallel scopes. Empty
-   * for sequential scopes. Stratum N depends only on strata 0 to N-1.
+   * strata contains stratified execution layers for parallel scopes. On sequential
+   * scopes, strata hold variable nodes that run every pass alongside the active step.
+   * Stratum N depends only on strata 0 to N-1.
    */
   get strata() {
-    return array.nullishToEmpty(membersZ);
+    return membersZ.array().default(() => []);
   },
   /** steps contains ordered steps for sequential scopes. Empty for parallel scopes. */
   get steps() {
     return membersZ;
   },
-  /** transitions contains state-transition rules for sequential scopes. Empty for parallel scopes. */
-  transitions: array.nullishToEmpty(transitionZ),
+  /**
+   * transitions contains state-transition rules for sequential scopes. Empty for
+   * parallel scopes.
+   */
+  transitions: transitionZ.array().default(() => []),
 });
 
 /**
- * IR is the intermediate representation of an Arc program as a dataflow graph
- * with stratified execution, bridging semantic analysis and WebAssembly
- * compilation.
+ * IR is the intermediate representation of an Arc program as a dataflow graph with
+ * stratified execution, bridging semantic analysis and WebAssembly compilation.
  */
 export const irZ = z.object({
   /** functions contains function template definitions. */
@@ -208,13 +210,12 @@ export const irZ = z.object({
   /** authorities contains the static authority declarations for this program. */
   authorities: authoritiesZ,
   /**
-   * root is the top-level execution context. The root is always a
-   * parallel, always-live Scope whose strata mix module-scope
-   * reactive flow with top-level gated scopes.
+   * root is the top-level execution context. The root is always a parallel, always-live
+   * Scope whose strata mix module-scope reactive flow with top-level gated scopes.
    */
   root: scopeZ,
 });
 export interface IR extends z.infer<typeof irZ> {}
 
-export const membersZ = array.nullishToEmpty(memberZ);
+export const membersZ = memberZ.array().default(() => []);
 export type Members = z.infer<typeof membersZ>;

package/src/arc/text/types.gen.ts

@@ -9,11 +9,30 @@
 
 // Code generated by Oracle. DO NOT EDIT.
 
+import { crdt } from "@synnaxlabs/x";
 import { z } from "zod";
 
+/**
+ * Document is the conflict-free replicated representation of the text: the operations
+ * that reconstruct it when applied to an empty replica. It is the durable source of
+ * truth from which raw is materialized.
+ */
+export const documentZ = z.object({
+  /** inserts are the operations that reconstruct the document's characters. */
+  inserts: crdt.insertZ.array().default(() => []),
+  /** deletes are the operations that tombstone deleted characters. */
+  deletes: crdt.deleteZ.array().default(() => []),
+});
+export interface Document extends z.infer<typeof documentZ> {}
+
 /** Text is text-based Arc source code with optional parsed AST for compilation. */
 export const textZ = z.object({
-  /** raw is the raw Arc source code in text form. */
-  raw: z.string(),
+  /**
+   * doc is the replicated source of truth for the text. It defaults to empty on create,
+   * in which case the server seeds it from raw.
+   */
+  doc: documentZ.prefault({}),
+  /** raw is the materialized Arc source code, derived from doc and not persisted. */
+  raw: z.string().default(""),
 });
 export interface Text extends z.infer<typeof textZ> {}

package/src/arc/types/types.gen.ts

@@ -9,7 +9,7 @@
 
 // Code generated by Oracle. DO NOT EDIT.
 
-import { array, record, zod } from "@synnaxlabs/x";
+import { zod } from "@synnaxlabs/x";
 import { z } from "zod";
 
 export enum Kind {
@@ -25,16 +25,18 @@ export enum Kind {
   f32 = 9,
   f64 = 10,
   string = 11,
-  chan = 14,
-  series = 15,
-  variable = 16,
-  numeric_constant = 17,
-  integer_constant = 18,
-  float_constant = 19,
-  exact_integer_float_constant = 20,
-  function = 21,
-  sequence = 22,
-  stage = 23,
+  chan = 12,
+  series = 13,
+  variable = 14,
+  numeric_constant = 15,
+  integer_constant = 16,
+  float_constant = 17,
+  exact_integer_float_constant = 18,
+  function = 19,
+  sequence = 20,
+  stage = 21,
+  var_ref = 22,
+  bool = 23,
 }
 export const kindZ = z.enum(Kind);
 
@@ -42,19 +44,23 @@ export enum ChanDirection {
   none = 0,
   read = 1,
   write = 2,
+  read_write = 3,
 }
 export const chanDirectionZ = z.enum(ChanDirection);
 
-/** Channels contains channel declarations for reading from and writing to Synnax channels. */
+/**
+ * Channels contains channel declarations for reading from and writing to Synnax
+ * channels.
+ */
 export const channelsZ = z.object({
   /** read contains readable channel indices mapped to parameter names. */
-  read: record.nullishToEmpty(z.uint32(), z.string()),
+  read: z.record(z.uint32(), z.string()).default(() => ({})),
   /** write contains writable channel indices mapped to parameter names. */
-  write: record.nullishToEmpty(z.uint32(), z.string()),
+  write: z.record(z.uint32(), z.string()).default(() => ({})),
 });
 export interface Channels extends z.infer<typeof channelsZ> {}
 
-/** Dimensions contains physical dimension exponents for dimensional analysis (SI base quantities). */
+/** Dimensions contains dimension exponents for dimensional analysis. */
 export const dimensionsZ = z.object({
   /** length is the length dimension exponent (meters). */
   length: zod.int8,
@@ -62,20 +68,22 @@ export const dimensionsZ = z.object({
   mass: zod.int8,
   /** time is the time dimension exponent (seconds). */
   time: zod.int8,
-  /** current is the electric current dimension exponent (amperes). */
+  /** current is the electric current dimension exponent (Amperes). */
   current: zod.int8,
-  /** temperature is the temperature dimension exponent (kelvin). */
+  /** temperature is the temperature dimension exponent (Kelvin). */
   temperature: zod.int8,
   /** angle is the angle dimension exponent (radians). */
   angle: zod.int8,
-  /** count is the count dimension exponent (dimensionless quantity). */
+  /** count is the count dimension exponent. */
   count: zod.int8,
   /** data is the data size dimension exponent (bytes). */
   data: zod.int8,
 });
 export interface Dimensions extends z.infer<typeof dimensionsZ> {}
 
-/** Unit is a physical unit with dimensions and scale factor for unit-aware computation. */
+/**
+ * Unit is a physical unit with dimensions and scale factor for unit-aware computation.
+ */
 export const unitZ = z.object({
   /** dimensions contains physical dimension exponents. */
   dimensions: dimensionsZ,
@@ -89,16 +97,12 @@ export interface Unit extends z.infer<typeof unitZ> {}
 /** FunctionProperties contains common parameter definitions for function-like types. */
 export const functionPropertiesZ = z.object({
   /** inputs contains input parameter definitions. */
-  get inputs(): z.ZodOptional<typeof paramsZ> {
-    return paramsZ.optional();
+  get inputs(): z.ZodDefault<typeof paramsZ> {
+    return paramsZ.default([]);
   },
   /** outputs contains output parameter definitions. */
-  get outputs(): z.ZodOptional<typeof paramsZ> {
-    return paramsZ.optional();
-  },
-  /** config contains configuration parameter definitions. */
-  get config(): z.ZodOptional<typeof paramsZ> {
-    return paramsZ.optional();
+  get outputs(): z.ZodDefault<typeof paramsZ> {
+    return paramsZ.default([]);
   },
 });
 export interface FunctionProperties extends z.infer<typeof functionPropertiesZ> {}
@@ -113,20 +117,24 @@ export const typeZ = functionPropertiesZ.extend({
   get constraint(): z.ZodOptional<typeof typeZ> {
     return typeZ.optional();
   },
-  chanDirection: chanDirectionZ.optional(),
+  chanDirection: chanDirectionZ,
 });
 export interface Type extends z.infer<typeof typeZ> {}
 
 /** Param is a named, typed parameter with optional default value. */
-export const paramZ = z.object({
+export interface Param {
+  name: string;
+  type: Type;
+  value: unknown;
+}
+export const paramZ: z.ZodType<Param> = z.object({
   /** name is the parameter name. */
   name: z.string(),
   /** type is the parameter type. */
   type: typeZ,
   /** value is an optional default value. */
-  value: z.unknown().optional(),
+  value: z.unknown(),
 });
-export interface Param extends z.infer<typeof paramZ> {}
 
-export const paramsZ = array.nullishToEmpty(paramZ);
+export const paramsZ = paramZ.array().default(() => []);
 export type Params = z.infer<typeof paramsZ>;

package/src/arc/types.gen.ts

@@ -9,18 +9,31 @@
 
 // Code generated by Oracle. DO NOT EDIT.
 
-import { status } from "@synnaxlabs/x";
+import { uuid } from "@synnaxlabs/x";
 import { z } from "zod";
 
 import { graph } from "@/arc/graph";
 import { program } from "@/arc/program";
 import { text } from "@/arc/text";
 import { ontology } from "@/ontology";
+import { status } from "@/status";
+import { task } from "@/task";
 
 export const MODES = ["text", "graph"] as const;
 export const modeZ = z.enum(MODES);
 export type Mode = z.infer<typeof modeZ>;
 
+export const EXECUTION_MODES = [
+  "AUTO",
+  "BUSY_WAIT",
+  "HIGH_RATE",
+  "RT_EVENT",
+  "HYBRID",
+  "EVENT_DRIVEN",
+] as const;
+export const executionModeZ = z.enum(EXECUTION_MODES);
+export type ExecutionMode = z.infer<typeof executionModeZ>;
+
 /** StatusDetails contains Arc-specific status details for execution state. */
 export const statusDetailsZ = z.object({
   /** running indicates whether the Arc module is currently executing. */
@@ -34,52 +47,41 @@ export type Key = z.infer<typeof keyZ>;
 export const statusZ = status.statusZ({ details: statusDetailsZ });
 export type Status = z.infer<typeof statusZ>;
 
-/** New contains parameters for creating a new Arc module. */
-export const newZ = z.object({
-  /**
-   * key is an optional key for the module. If not provided, one will be
-   * automatically assigned.
-   */
-  key: keyZ.optional(),
-  /** name is a human-readable name for the module. */
-  name: z.string(),
-  /**
-   * mode specifies the representation mode for this module.
-   * Either "text" for text-based Arc code or "graph" for visual dataflow.
-   */
-  mode: modeZ,
-  /** graph is the visual dataflow graph representation. */
-  graph: graph.graphZ,
-  /** text is the text-based Arc source code. */
-  text: text.textZ,
+export const taskConfigZ = task.persistConfigZ.extend({
+  arcKey: keyZ,
+  hash: z.string().default(""),
+  executionMode: executionModeZ.default("AUTO"),
+  rtPriority: z.int32().default(47),
+  cpuAffinity: z.int32().default(-1),
+  memoryLocked: z.boolean().default(false),
 });
-export interface New extends z.input<typeof newZ> {}
+export interface TaskConfig extends z.infer<typeof taskConfigZ> {}
 
 /**
- * Arc is an Arc module combining visual graph representation and text-based
- * source code for reactive control systems. Compiles to WebAssembly for
- * sandboxed execution.
+ * Arc is an Arc module combining visual graph representation and text-based source code
+ * for reactive control systems. Compiles to WebAssembly for sandboxed execution.
  */
 export const arcZ = z.object({
   /** key is the unique identifier for this module. */
-  key: keyZ,
+  key: keyZ.default(uuid.create),
   /** name is a human-readable name for the module. */
-  name: z.string(),
+  name: z.string().min(1, "name is required"),
   /**
-   * mode specifies the representation mode for this module.
-   * Either "text" for text-based Arc code or "graph" for visual dataflow.
+   * mode specifies the representation mode for this module. Either "text" for
+   * text-based Arc code or "graph" for visual dataflow.
    */
   mode: modeZ,
   /** graph is the visual dataflow graph representation of the module. */
-  graph: graph.graphZ,
+  graph: graph.graphZ.prefault({}),
   /** text is the text-based Arc source code. */
-  text: text.textZ,
+  text: text.textZ.prefault({}),
   /** program is the compiled module output including IR and WebAssembly bytecode. */
   program: program.programZ.optional(),
   /** status is the current execution status of the module. */
   status: statusZ.optional(),
 });
 export interface Arc extends z.infer<typeof arcZ> {}
+export interface New extends z.input<typeof arcZ> {}
 
 export const ontologyID = ontology.createIDFactory<Key>("arc");
 export const TYPE_ONTOLOGY_ID = ontologyID("");

package/src/auth/auth.ts

@@ -11,11 +11,11 @@ import { type Middleware, type UnaryClient } from "@synnaxlabs/freighter";
 import { errors, TimeStamp } from "@synnaxlabs/x";
 import { z } from "zod";
 
-import { ExpiredTokenError, InvalidTokenError } from "@/errors";
+import { AuthError, ExpiredTokenError, InvalidTokenError } from "@/errors";
 import { user } from "@/user";
 
 const credentialsZ = z.object({ username: z.string(), password: z.string() });
-interface Credentials extends z.infer<typeof credentialsZ> {}
+export interface Credentials extends z.infer<typeof credentialsZ> {}
 
 const clusterInfoZ = z.object({
   clusterKey: z.string(),
@@ -30,7 +30,7 @@ const tokenResponseZ = z.object({
   clusterInfo: clusterInfoZ.optional(),
 });
 
-const LOGIN_ENDPOINT = "/auth/login";
+export const LOGIN_ENDPOINT = "/auth/login";
 
 const MAX_RETRIES = 3;
 
@@ -44,20 +44,40 @@ const changePasswordResZ = z.object({});
 const RETRY_ON = [InvalidTokenError, ExpiredTokenError] as const;
 
 type AuthState =
-  | { authenticated: false }
-  | { authenticated: true; user: user.User; token: string };
+  { authenticated: false } | { authenticated: true; user: user.User; token: string };
+
+/** Login outcome hooks. The connection machine is the sole consumer. */
+export interface Observer {
+  /** Fires after every successful login. */
+  onSuccess?: () => void;
+  /** Fires on a definitive credential rejection, never on token self-heal. */
+  onFailure?: (error: Error) => void;
+}
 
 export class Client {
   private readonly client: UnaryClient;
   private readonly credentials: Credentials;
+  private readonly observer: Observer;
   private authState: AuthState = { authenticated: false };
   authenticating: Promise<Error | null> | undefined;
   private retryCount: number;
+  private generation = 0;
 
-  constructor(client: UnaryClient, credentials: Credentials) {
+  constructor(client: UnaryClient, credentials: Credentials, observer: Observer = {}) {
     this.client = client;
     this.credentials = credentials;
+    this.observer = observer;
+    this.retryCount = 0;
+  }
+
+  /** Replaces the stored credentials and clears auth state for a fresh login. */
+  setCredentials({ username, password }: Credentials): void {
+    this.credentials.username = username;
+    this.credentials.password = password;
+    this.authState = { authenticated: false };
+    this.authenticating = undefined;
     this.retryCount = 0;
+    this.generation += 1;
   }
 
   get authenticated(): boolean {
@@ -99,6 +119,9 @@ export class Client {
     const mw: Middleware = async (reqCtx, next) => {
       if (!this.authenticated && !reqCtx.target.endsWith(LOGIN_ENDPOINT)) {
         this.authenticating ??= (async (): Promise<Error | null> => {
+          // logins issued before a setCredentials are stale; their result must
+          // not reach the observer
+          const generation = this.generation;
           try {
             const res = await this.client.send(
               LOGIN_ENDPOINT,
@@ -106,18 +129,27 @@ export class Client {
               credentialsZ,
               tokenResponseZ,
             );
+            if (generation !== this.generation) return null;
             this.authState = {
               authenticated: true,
               user: res.user,
               token: res.token,
             };
+            this.observer.onSuccess?.();
             return null;
           } catch (err) {
-            return errors.fromUnknown(err);
+            const parsed = errors.fromUnknown(err);
+            if (generation === this.generation && AuthError.matches(parsed))
+              this.observer.onFailure?.(parsed);
+            return parsed;
           }
         })();
         const err = await this.authenticating;
-        if (err != null) throw err;
+        if (err != null) {
+          // clear the memoized failure so the next request retries the login
+          this.authenticating = undefined;
+          throw err;
+        }
       }
       reqCtx.params.Authorization = `Bearer ${this.token}`;
       try {