@voltro/protocol 0.54.0 → 0.55.0

package/dist/rest.d.ts

@@ -1000,21 +1000,52 @@ declare type Subject = typeof Subject.Type;
 
 declare type Target<Input = unknown, Row = unknown> = TargetSpec<Input, Row> | ReadonlyArray<TargetSpec<Input, Row>>;
 
+/**
+ * ONE declared many-to-many relation of a write target: the junction table
+ * plus its two reference columns.
+ *
+ * **Why the columns are declared and not derived.** The server can derive
+ * them (`store.relationLinks` reads the junction's `reference()` targets),
+ * and it still does — but the same declaration drives JUNCTION AUTO-OPTIMISTIC
+ * in the BROWSER, and the browser has no table registry to derive from
+ * (`@voltro/database` is server-only by construction). Guessing a column name
+ * from the table name is the failure mode this codebase refuses everywhere
+ * else, so the pair is stated. It is not taken on trust: before it writes, the
+ * server compares the declaration against the junction's real reference
+ * columns and refuses — naming the right pair — if they disagree. A wrong
+ * declaration is a boot-loud error, never a silent client/server divergence.
+ */
+declare interface TargetRelation {
+    /** The junction (link) table. */
+    readonly junction: string;
+    /** The junction's reference column pointing at the TARGET's own table. */
+    readonly anchorColumn: string;
+    /** The junction's other reference column — the linked row's id. */
+    readonly targetColumn: string;
+}
+
 /**
  * Declared many-to-many RELATIONS of a write target: `{ inputField:
- * junctionTable }`. After the executor succeeds — inside the SAME
+ * TargetRelation }`. After the executor succeeds — inside the SAME
  * transaction — the framework reconciles the junction's links for the
  * written row against `input[inputField]` (an array of target ids) via the
  * diff-based `store.relationLinks`, so a form's multi-reference field saves
- * in one mutation with no hand-written junction code. The anchor column is
- * derived from the junction's `reference()` targets (a self-junction is
- * refused, never guessed).
+ * in one mutation with no hand-written junction code.
+ *
+ * The SAME declaration drives the client's junction auto-optimistic: the
+ * cache reconciles the junction rows of every subscription sourced on
+ * `junction` the moment the mutation is sent, so a multi-reference field
+ * flips as instantly as a scalar one instead of waiting for the server delta.
+ * Those patches ride the ordinary optimistic lane (staged under the mutation
+ * id): reverted on failure, kept on success until the base actually moves.
  *
  * An ABSENT input field leaves the links untouched (absent ≠ empty — an
  * empty array is the explicit "clear them all"). The row id is the
- * executor's `output.id`, falling back to `input.id`.
+ * executor's `output.id`, falling back to `input.id`; the client, which
+ * cannot see `output` yet, uses `input.id` (and, for an insert, the same
+ * optimistic id it stamped on the new row).
  */
-declare type TargetRelations = Readonly<Record<string, string>>;
+declare type TargetRelations = Readonly<Record<string, TargetRelation>>;
 
 declare type TargetSpec<Input = unknown, Row = unknown> = InsertTarget<Input, Row> | UpdateTarget<Input, Row> | DeleteTarget<Input>;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@voltro/protocol",
-  "version": "0.54.0",
+  "version": "0.55.0",
   "description": "The Voltro wire + plugin contract — defineQuery/Mutation/Action/Stream, definePlugin, sessions / JWT / API-keys, and the RPC protocol.",
   "keywords": [
     "voltro",
@@ -54,8 +54,8 @@
   },
   "dependencies": {
     "@effect/sql": "^0.52.0",
-    "@voltro/database": "0.54.0",
-    "@voltro/logger": "0.54.0",
+    "@voltro/database": "0.55.0",
+    "@voltro/logger": "0.55.0",
     "jose": "^6.2.8"
   },
   "peerDependencies": {