SY-3833-2: Add Schematic Action Codec and Dispatch Endpoint

Lays the server-side foundation for granular schematic mutations.

Oracle codegen:
- Adds the 'action' grammar production to the oracle DSL alongside fields,
  domains, and field omissions inside struct bodies.
- Adds resolution.Action and analyzer.collectAction. resolveTypeRefs now
  walks action payload field types so cross-references inside action bodies
  resolve correctly to their qualified names.
- New oracle/plugin/go/actions plugin generates a discriminated-union
  codec (Action envelope, Reduce, ReduceAll, NewXxxAction constructors)
  for any struct that declares actions. Optional fields use the same
  pointer-prefix logic as gotypes (skip slice / map / msgpack.EncodedJSON).
- Formatter learns to emit action blocks so 'oracle fmt' / 'oracle sync'
  preserves them.

Schematic schema and runtime:
- schemas/schematic.oracle declares six actions: SetNodePosition, AddNode,
  RemoveNode, SetEdge, RemoveEdge, SetProps. Hand-written Handle methods
  live in core/pkg/service/schematic/actions.go alongside the ScopedAction
  envelope used for cluster broadcast.
- Writer.Dispatch applies a sequence of actions atomically inside a single
  gorp transaction, rejects snapshots, and notifies actionObserver on
  success. SetData remains in place; no callers are migrated yet.
- Service wires actionObserver to a signals translator that publishes
  scoped action sequences to sy_schematic_set / sy_schematic_delete when
  cfg.Signals is non-nil.
- API exposes Dispatch as a new freighter endpoint
  (/api/v1/schematic/dispatch) registered alongside the existing
  SetData endpoint.

Author: emilbon99

client/ts/package.json

@@ -37,6 +37,7 @@
     "@synnaxlabs/freighter": "workspace:^",
     "@synnaxlabs/x": "workspace:^",
     "async-mutex": "catalog:",
+    "immer": "catalog:",
     "zod": "catalog:"
   },
   "devDependencies": {

client/ts/src/schematic/actions.gen.ts

@@ -0,0 +1,190 @@
+// Copyright 2026 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+// Code generated by Oracle. DO NOT EDIT.
+import { caseconv, control, record, spatial, zod } from "@synnaxlabs/x";
+import { produce } from "immer";
+import { z } from "zod";
+
+import {
+  handleAddNode,
+  handleRemoveEdge,
+  handleRemoveNode,
+  handleSetAuthority,
+  handleSetEdge,
+  handleSetLegend,
+  handleSetNodePosition,
+  handleSetProps,
+} from "@/schematic/actions";
+import { edgeZ, legendZ, nodeZ, type Schematic } from "@/schematic/types.gen";
+
+/** SetNodePosition moves a node to a new position. */
+export const setNodePositionPayloadZ = z.object({
+  key: z.string(),
+  position: spatial.xyZ,
+});
+
+export type SetNodePositionPayload = z.infer<typeof setNodePositionPayloadZ>;
+
+/**
+ * AddNode appends a node to the schematic. If props is non-empty it is stored
+ * under the node's key in the schematic props map.
+ */
+export const addNodePayloadZ = z.object({
+  node: nodeZ,
+  props: caseconv.preserveCase(zod.nullToUndefined(record.unknownZ())),
+});
+
+export type AddNodePayload = z.infer<typeof addNodePayloadZ>;
+
+/** RemoveNode removes a node and any props stored under its key. */
+export const removeNodePayloadZ = z.object({
+  key: z.string(),
+});
+
+export type RemoveNodePayload = z.infer<typeof removeNodePayloadZ>;
+
+/**
+ * SetEdge inserts the edge if no edge with the same key exists, otherwise
+ * replaces the existing edge with the same key.
+ */
+export const setEdgePayloadZ = z.object({
+  edge: edgeZ,
+});
+
+export type SetEdgePayload = z.infer<typeof setEdgePayloadZ>;
+
+/** RemoveEdge removes the edge with the given key, if present. */
+export const removeEdgePayloadZ = z.object({
+  key: z.string(),
+});
+
+export type RemoveEdgePayload = z.infer<typeof removeEdgePayloadZ>;
+
+/** SetProps sets the props entry for the given node or edge key. */
+export const setPropsPayloadZ = z.object({
+  key: z.string(),
+  props: caseconv.preserveCase(record.nullishToEmpty()),
+});
+
+export type SetPropsPayload = z.infer<typeof setPropsPayloadZ>;
+
+/** SetAuthority sets the control authority level for this schematic. */
+export const setAuthorityPayloadZ = z.object({
+  value: control.authorityZ,
+});
+
+export type SetAuthorityPayload = z.infer<typeof setAuthorityPayloadZ>;
+
+/** SetLegend replaces the schematic's control-legend overlay configuration. */
+export const setLegendPayloadZ = z.object({
+  legend: legendZ,
+});
+
+export type SetLegendPayload = z.infer<typeof setLegendPayloadZ>;
+
+export const ACTION_TYPES = {
+  set_node_position: "set_node_position",
+  add_node: "add_node",
+  remove_node: "remove_node",
+  set_edge: "set_edge",
+  remove_edge: "remove_edge",
+  set_props: "set_props",
+  set_authority: "set_authority",
+  set_legend: "set_legend",
+} as const;
+
+export const actionZ = z.discriminatedUnion("type", [
+  z.object({
+    type: z.literal("set_node_position"),
+    setNodePosition: setNodePositionPayloadZ,
+  }),
+  z.object({ type: z.literal("add_node"), addNode: addNodePayloadZ }),
+  z.object({ type: z.literal("remove_node"), removeNode: removeNodePayloadZ }),
+  z.object({ type: z.literal("set_edge"), setEdge: setEdgePayloadZ }),
+  z.object({ type: z.literal("remove_edge"), removeEdge: removeEdgePayloadZ }),
+  z.object({ type: z.literal("set_props"), setProps: setPropsPayloadZ }),
+  z.object({ type: z.literal("set_authority"), setAuthority: setAuthorityPayloadZ }),
+  z.object({ type: z.literal("set_legend"), setLegend: setLegendPayloadZ }),
+]);
+
+export type Action = z.infer<typeof actionZ>;
+
+export const setNodePosition = (payload: SetNodePositionPayload): Action => ({
+  type: "set_node_position",
+  setNodePosition: payload,
+});
+
+export const addNode = (payload: AddNodePayload): Action => ({
+  type: "add_node",
+  addNode: payload,
+});
+
+export const removeNode = (payload: RemoveNodePayload): Action => ({
+  type: "remove_node",
+  removeNode: payload,
+});
+
+export const setEdge = (payload: SetEdgePayload): Action => ({
+  type: "set_edge",
+  setEdge: payload,
+});
+
+export const removeEdge = (payload: RemoveEdgePayload): Action => ({
+  type: "remove_edge",
+  removeEdge: payload,
+});
+
+export const setProps = (payload: SetPropsPayload): Action => ({
+  type: "set_props",
+  setProps: payload,
+});
+
+export const setAuthority = (payload: SetAuthorityPayload): Action => ({
+  type: "set_authority",
+  setAuthority: payload,
+});
+
+export const setLegend = (payload: SetLegendPayload): Action => ({
+  type: "set_legend",
+  setLegend: payload,
+});
+
+export const reduce = (state: Schematic, action: Action): Schematic => {
+  switch (action.type) {
+    case "set_node_position":
+      handleSetNodePosition(state, action.setNodePosition);
+      break;
+    case "add_node":
+      handleAddNode(state, action.addNode);
+      break;
+    case "remove_node":
+      handleRemoveNode(state, action.removeNode);
+      break;
+    case "set_edge":
+      handleSetEdge(state, action.setEdge);
+      break;
+    case "remove_edge":
+      handleRemoveEdge(state, action.removeEdge);
+      break;
+    case "set_props":
+      handleSetProps(state, action.setProps);
+      break;
+    case "set_authority":
+      handleSetAuthority(state, action.setAuthority);
+      break;
+    case "set_legend":
+      handleSetLegend(state, action.setLegend);
+      break;
+  }
+  return state;
+};
+
+export const reduceAll = (state: Schematic, actions: Action[]): Schematic =>
+  produce(state, (draft) => actions.forEach((action) => reduce(draft, action)));

client/ts/src/schematic/actions.ts

@@ -0,0 +1,82 @@
+// Copyright 2026 Synnax Labs, Inc.
+//
+// Use of this software is governed by the Business Source License included in the file
+// licenses/BSL.txt.
+//
+// As of the Change Date specified in that file, in accordance with the Business Source
+// License, use of this software will be governed by the Apache License, Version 2.0,
+// included in the file licenses/APL.txt.
+
+import { z } from "zod";
+
+import {
+  type AddNodePayload,
+  actionZ,
+  type RemoveEdgePayload,
+  type RemoveNodePayload,
+  type SetAuthorityPayload,
+  type SetEdgePayload,
+  type SetLegendPayload,
+  type SetNodePositionPayload,
+  type SetPropsPayload,
+} from "@/schematic/actions.gen";
+import { keyZ, type Schematic } from "@/schematic/types.gen";
+
+export const scopedActionZ = z.object({
+  key: keyZ,
+  sessionKey: z.string(),
+  actions: actionZ.array(),
+});
+
+export interface ScopedAction extends z.infer<typeof scopedActionZ> {}
+
+export const handleSetNodePosition = (
+  state: Schematic,
+  payload: SetNodePositionPayload,
+): void => {
+  const node = state.nodes.find((n) => n.key === payload.key);
+  if (node != null) node.position = payload.position;
+};
+
+export const handleAddNode = (state: Schematic, payload: AddNodePayload): void => {
+  state.nodes.push(payload.node);
+  if (payload.props != null) state.props[payload.node.key] = payload.props;
+};
+
+export const handleRemoveNode = (
+  state: Schematic,
+  payload: RemoveNodePayload,
+): void => {
+  const idx = state.nodes.findIndex((n) => n.key === payload.key);
+  if (idx !== -1) state.nodes.splice(idx, 1);
+  delete state.props[payload.key];
+};
+
+export const handleSetEdge = (state: Schematic, payload: SetEdgePayload): void => {
+  const idx = state.edges.findIndex((e) => e.key === payload.edge.key);
+  if (idx !== -1) state.edges[idx] = payload.edge;
+  else state.edges.push(payload.edge);
+};
+
+export const handleRemoveEdge = (
+  state: Schematic,
+  payload: RemoveEdgePayload,
+): void => {
+  const idx = state.edges.findIndex((e) => e.key === payload.key);
+  if (idx !== -1) state.edges.splice(idx, 1);
+};
+
+export const handleSetProps = (state: Schematic, payload: SetPropsPayload): void => {
+  state.props[payload.key] = payload.props;
+};
+
+export const handleSetAuthority = (
+  state: Schematic,
+  payload: SetAuthorityPayload,
+): void => {
+  state.authority = payload.value;
+};
+
+export const handleSetLegend = (state: Schematic, payload: SetLegendPayload): void => {
+  state.legend = payload.legend;
+};

client/ts/src/schematic/client.ts

@@ -11,6 +11,7 @@ import { sendRequired, type UnaryClient } from "@synnaxlabs/freighter";
 import { array } from "@synnaxlabs/x";
 import { z } from "zod";
 
+import { type Action, actionZ } from "@/schematic/actions.gen";
 import { symbol } from "@/schematic/symbol";
 import {
   type Key,
@@ -29,6 +30,11 @@ const renameReqZ = z.object({ key: keyZ, name: z.string() });
 const setDataBodyZ = schematicZ.omit({ key: true, name: true, snapshot: true });
 export type SetDataBody = z.input<typeof setDataBodyZ>;
 const setDataReqZ = z.object({ key: keyZ, data: setDataBodyZ });
+const dispatchReqZ = z.object({
+  key: keyZ,
+  session_key: z.string(),
+  actions: actionZ.array(),
+});
 const deleteReqZ = z.object({ keys: keyZ.array() });
 
 const copyReqZ = z.object({
@@ -105,6 +111,16 @@ export class Client {
     );
   }
 
+  async dispatch(key: Key, sessionKey: string, actions: Action[]): Promise<void> {
+    await sendRequired(
+      this.client,
+      "/schematic/dispatch",
+      { key, session_key: sessionKey, actions },
+      dispatchReqZ,
+      emptyResZ,
+    );
+  }
+
   async retrieve(args: RetrieveSingleParams): Promise<Schematic>;
   async retrieve(args: RetrieveMultipleParams): Promise<Schematic[]>;
   async retrieve(

client/ts/src/schematic/external.ts

@@ -7,6 +7,8 @@
 // License, use of this software will be governed by the Apache License, Version 2.0,
 // included in the file licenses/APL.txt.
 
+export * from "@/schematic/actions";
+export * from "@/schematic/actions.gen";
 export * from "@/schematic/client";
 export * from "@/schematic/symbol";
 export * from "@/schematic/types.gen";

core/pkg/api/grpc/grpc.go

@@ -106,6 +106,7 @@ func NewTransport(channelSvc *distchannel.Service) (api.Transport, []grpc.Bindab
 	a.SchematicRetrieve = fnoop.UnaryServer[schematic.RetrieveRequest, schematic.RetrieveResponse]{}
 	a.SchematicRename = fnoop.UnaryServer[schematic.RenameRequest, types.Nil]{}
 	a.SchematicSetData = fnoop.UnaryServer[schematic.SetDataRequest, types.Nil]{}
+	a.SchematicDispatch = fnoop.UnaryServer[schematic.DispatchRequest, types.Nil]{}
 	a.SchematicCopy = fnoop.UnaryServer[schematic.CopyRequest, schematic.CopyResponse]{}
 
 	// SCHEMATIC SYMBOL

core/pkg/api/http/http.go

@@ -113,6 +113,7 @@ func NewTransport(router *fhttp.Router, ch *distchannel.Service) api.Transport {
 		SchematicDelete:   fhttp.UnaryServer[schematic.DeleteRequest, types.Nil](router, "/api/v1/schematic/delete"),
 		SchematicRename:   fhttp.UnaryServer[schematic.RenameRequest, types.Nil](router, "/api/v1/schematic/rename"),
 		SchematicSetData:  fhttp.UnaryServer[schematic.SetDataRequest, types.Nil](router, "/api/v1/schematic/set-data"),
+		SchematicDispatch: fhttp.UnaryServer[schematic.DispatchRequest, types.Nil](router, "/api/v1/schematic/dispatch"),
 		SchematicCopy:     fhttp.UnaryServer[schematic.CopyRequest, schematic.CopyResponse](router, "/api/v1/schematic/copy"),
 
 		// SCHEMATIC SYMBOL

core/pkg/api/layer.go

@@ -110,6 +110,7 @@ type Transport struct {
 	SchematicDelete   freighter.UnaryServer[schematic.DeleteRequest, types.Nil]
 	SchematicRename   freighter.UnaryServer[schematic.RenameRequest, types.Nil]
 	SchematicSetData  freighter.UnaryServer[schematic.SetDataRequest, types.Nil]
+	SchematicDispatch freighter.UnaryServer[schematic.DispatchRequest, types.Nil]
 	SchematicCopy     freighter.UnaryServer[schematic.CopyRequest, schematic.CopyResponse]
 	// SCHEMATIC SYMBOL
 	SchematicCreateSymbol        freighter.UnaryServer[schematic.CreateSymbolRequest, schematic.CreateSymbolResponse]
@@ -292,6 +293,7 @@ func (l *Layer) BindTo(t Transport) {
 		t.SchematicDelete,
 		t.SchematicRename,
 		t.SchematicSetData,
+		t.SchematicDispatch,
 		t.SchematicCopy,
 
 		// SCHEMATIC SYMBOL
@@ -438,6 +440,7 @@ func (l *Layer) BindTo(t Transport) {
 	t.SchematicDelete.BindHandler(l.Schematic.Delete)
 	t.SchematicRename.BindHandler(l.Schematic.Rename)
 	t.SchematicSetData.BindHandler(l.Schematic.SetData)
+	t.SchematicDispatch.BindHandler(l.Schematic.Dispatch)
 	t.SchematicCopy.BindHandler(l.Schematic.Copy)
 
 	// SCHEMATIC SYMBOL

core/pkg/api/schematic/schematic.go

@@ -110,6 +110,31 @@ func (s *Service) SetData(ctx context.Context, req SetDataRequest) (res types.Ni
 	})
 }
 
+// DispatchRequest carries an action sequence to apply to a single schematic.
+// SessionKey identifies the originating client so cluster broadcasts can be
+// deduplicated against the local optimistic update.
+type DispatchRequest struct {
+	Key        uuid.UUID          `json:"key" msgpack:"key"`
+	SessionKey string             `json:"session_key" msgpack:"session_key"`
+	Actions    []schematic.Action `json:"actions" msgpack:"actions"`
+}
+
+// Dispatch applies the action sequence to the target schematic atomically.
+// Subscribers to the schematic action signals receive the sequence after the
+// transaction commits.
+func (s *Service) Dispatch(ctx context.Context, req DispatchRequest) (res types.Nil, err error) {
+	if err = s.access.Enforce(ctx, access.Request{
+		Subject: auth.GetSubject(ctx),
+		Action:  access.ActionUpdate,
+		Objects: []ontology.ID{schematic.OntologyID(req.Key)},
+	}); err != nil {
+		return res, err
+	}
+	return res, s.db.WithTx(ctx, func(tx gorp.Tx) error {
+		return s.internal.NewWriter(tx).Dispatch(ctx, req.Key, req.SessionKey, req.Actions)
+	})
+}
+
 type (
 	RetrieveRequest struct {
 		Keys []uuid.UUID `json:"keys" msgpack:"keys"`