PROTOCOL.md
J-Space Collections
PROTOCOL.md
1 # Collection and action protocol
2
3 Author: **Komorebi P.**
4
5 ## Typed objects and collections
6
7 An object stores its source identifier, origin identifier, frame dimensions, and explicit `[row, column, color]` pixels. Pixels are sorted and duplicate coordinates are rejected. The source is the typed input grid's hash. Component extraction creates the origin identifier from that source and the original pixels. Translation and recoloring retain the origin identifier while changing the current object value.
8
9 The object representation can carry multiple colors. The supplied component extractor creates same-color objects. Requesting one color from a multicolor object returns an ambiguity error.
10
11 Collection kinds include `list[object]`, `list[index]`, `list[scalar]`, `list[grid]`, and the other supported base kinds. Elements are typed values. An empty collection retains its declared element type:
12
13 ```json
14 {"kind": "list[index]", "data": []}
15 ```
16
17 There is no inferred conversion between a scalar, color, index, or Boolean flag.
18
19 ## Collection nodes
20
21 A map binds each element to the operation's `item` parameter:
22
23 ```json
24 {
25 "id": "shifted",
26 "map": {
27 "op": "object.translate",
28 "items": "selected",
29 "bindings": {"offset": "offset"}
30 }
31 }
32 ```
33
34 The result has the operation's output type wrapped in a collection. Operations returning another collection are not accepted by map in this version.
35
36 A filter's operation must return a flag:
37
38 ```json
39 {
40 "id": "selected",
41 "filter": {
42 "op": "keep_large",
43 "items": "objects",
44 "bindings": {"minimum": "minimum"}
45 }
46 }
47 ```
48
49 A fold binds both `item` and `state`. The operation must preserve the state type:
50
51 ```json
52 {
53 "id": "placed",
54 "fold": {
55 "op": "object.paint",
56 "items": "shifted",
57 "state": "cleared",
58 "bindings": {"background": "background", "overwrite": "overwrite"}
59 }
60 }
61 ```
62
63 An empty map or filter returns an empty typed collection. An empty fold returns its initial state. Unused per-item bindings are not evaluated, although all graph bindings and types are still validated. Per-item calls share the normal execution budget and have trace paths such as `root/shifted/item_0`.
64
65 `object.paint` with `overwrite: false` requires destination pixels to equal the supplied background color. With `overwrite: true`, later items can overwrite earlier ones. `object.erase` checks the object's current pixel colors against the accumulator before replacing them with background. All operations produce new values. A failure partway through a fold can appear in the inspection trace but cannot partially commit a workspace revision.
66
67 ## Observe
68
69 ```json
70 {"action": "observe", "workspace": "objects"}
71 ```
72
73 Observation returns the current revision, registry identity, typed inputs, graph, outputs, potential dependencies, and the executed trace. Potential dependencies include branches that may not have executed.
74
75 ## Propose
76
77 ```json
78 {
79 "action": "propose",
80 "workspace": "objects",
81 "expected_revision": "r000002",
82 "updates": {"offset": {"kind": "point", "data": [0, 2]}},
83 "locked_outputs": ["original"],
84 "require_target_match": false
85 }
86 ```
87
88 Optional fields are `graph_edits`, `targets`, and `atol`. Targets map output names to typed expected values. Setting `require_target_match` to true requires at least one supplied target. The default scalar tolerance is 10⁻⁹. Protected outputs must exist both before and after the proposal.
89
90 A proposal is evaluated without changing the bank. Successful execution can still be rejected if a target requirement or protected output fails. Its feedback contains:
91
92 - Before and after target comparisons, when targets were supplied.
93 - Observed output and intermediate-value differences.
94 - The actual execution trace, including filter decisions and fold steps.
95 - Protected-output checks.
96 - A receipt containing the exact candidate, predicted outputs, constraints, and source identities.
97
98 Residuals report missing outputs and shape mismatches explicitly. Cell coordinates are capped at 256 entries with a truncation flag. No matching score is reported for an absent target. Scalar errors and categorical cell mismatches are kept separate.
99
100 ## Edit graph structure
101
102 The `graph_edits` list applies up to 64 edits in order to a copy of the graph. Supported forms are:
103
104 ```json
105 {"kind": "rebind", "node": "product", "argument": "b", "ref": "a"}
106 ```
107
108 ```json
109 {"kind": "replace_node", "node": "product", "value": {"id": "product", "op": "number.add", "args": {"a": "a", "b": "b"}}}
110 ```
111
112 ```json
113 {"kind": "add_node", "value": {"id": "total", "op": "number.add", "args": {"a": "a", "b": "b"}}}
114 ```
115
116 ```json
117 {"kind": "remove_node", "node": "unused"}
118 ```
119
120 ```json
121 {"kind": "set_output", "output": "answer", "ref": "total"}
122 ```
123
124 The resulting graph must still have valid names, references, types, and no cycles. Rebinding operates on explicit named arguments. To change a map, filter, fold, or choice configuration, replace that node. Input updates must refer to existing declared inputs.
125
126 ## Commit
127
128 ```json
129 {"action": "commit", "receipt": {"proposal_id": "...", "payload": {"...": "..."}}}
130 ```
131
132 Commit checks that the receipt payload has not changed, that the original revision and registry still match, and that the candidate executes with its predicted outputs and constraints. Only then does the ordinary edit mechanism create a new revision. A rejected or stale receipt cannot commit.
133
134 The command-line `--commit proposal.json` option accepts either a receipt or a complete proposal response. A proposal response is portable across process restarts because its data and source identities are serialized. Proposal receipts are not automatically stored inside the bank.
135
136 The registry identity is conservative. Adding a function under a new name preserves existing operation definitions but changes the registry identity, so previously prepared receipts must be proposed again.
137
138 ## Other actions
139
140 ```json
141 {"action": "fork", "workspace": "objects", "name": "trial", "expected_revision": "r000003"}
142 ```
143
144 ```json
145 {"action": "undo", "workspace": "trial", "expected_revision": "r000003"}
146 ```
147
148 ```json
149 {"action": "compare", "a": "objects", "b": "trial"}
150 ```
151
152 These wrap the existing bank operations. Creating workspaces, checking out arbitrary saved revisions, and registering functions remain available through the original CLI and Python API.
153
154 ## What a future controller must supply
155
156 The interface does not decide which operation, object representation, input edit, or graph structure to try. It also does not infer goals or supply hidden answers. A future controller must construct the proposal from observations and available evidence. The machinery executes it, exposes its consequences, and preserves the selected computation if committed.