Edition README
J-Space Collections
README.md
1 # J-space collections and actions v0.7
2
3 Author: **Komorebi P.** · 2026-09-06
4
5 This machinery release adds **typed object collections** and a **common workspace action interface**. Programs can extract objects, filter them, apply a function to each object, and accumulate their results into a grid. Controllers can observe a workspace, propose input or graph edits, inspect their consequences, and commit a matching saved proposal.
6
7 No training was performed. Object grouping, the example programs, and the example proposals are supplied. The frozen learned kernels from v0.5 remain unchanged. This is a foundation for a future controller, not an autonomous solver or an ARC performance result.
8
9 ## Run
10
11 Extract the ZIP and open PowerShell in this directory:
12
13 ```powershell
14 .\Run_Machinery.ps1 -Mode demo
15 .\Run_Machinery.ps1 -Mode test
16 .\Run_Machinery.ps1 -Mode verify
17 ```
18
19 The wrapper creates a local Python environment and installs NumPy when needed. It requires Python 3.10 or newer and does not modify your execution policy. Direct Python commands are also available:
20
21 ```powershell
22 python -m pip install -r requirements.txt
23 python demo.py
24 python -m unittest -v test_machinery.py test_collections.py
25 python verify_release.py
26 ```
27
28 After dependency installation, all runtime operations are local and need no API key or network connection. Python was tested on Linux. The PowerShell wrapper was inspected but not executed on Windows.
29
30 ## What is new
31
32 | Machinery | Purpose |
33 |---|---|
34 | Object values | Keep pixels, coordinate frame, source identity, and transformation lineage together |
35 | Typed collections | Carry up to 64 objects, scalars, grids, masks, or other supported base values |
36 | `map` | Apply a registered operation or function to each item |
37 | `filter` | Keep items selected by a Boolean predicate |
38 | `fold` | Carry an accumulator through a collection, such as painting objects into a scene |
39 | Object operations | Extract components, inspect area/color/bounds, translate, recolor, erase, and paint |
40 | JSON action interface | Observe, propose, commit, fork, undo, and compare |
41 | Proposal receipts | Bind a candidate to its source revision, operation library, predicted outputs, and constraints |
42 | Residual feedback | Report target mismatches by output type, including changed cells and shape failures |
43 | Protected outputs | Reject a proposal that changes an output the caller required to preserve |
44
45 Existing named bindings, functions, conditional execution, bounded repetition, branch history, previews, pure-operation caching, and atomic saves remain available.
46
47 ## Concrete demonstration
48
49 The example scene contains three same-color components. An authored function keeps the two objects with area at least two. A map translates them, and two folds erase their original pixels and paint their new pixels. The smaller distractor remains in place.
50
51 The action interface previews a supplied two-column translation against a supplied target. It reports ten mismatching cells before the edit and zero afterward. The bank is unchanged during preview. A saved receipt then commits after the bank is reloaded. Collision attempts, unmet target requirements, and attempts to reuse a stale receipt are rejected.
52
53 **The correct offset and target are provided by the example. The runtime does not discover them.** These are behavioral checks of the machinery.
54
55 `demo.py` writes a new directory under `runs/`. The shipped `examples/recorded_run/` already contains a complete run, including initial and final values, the proposal, commit, rejected attempts, branch comparison, and persistent bank.
56
57 ## Use the action interface
58
59 Start a fresh demonstration bank:
60
61 ```powershell
62 python cli.py --bank my_workspaces.json init
63 python control.py --bank my_workspaces.json --request examples/observe_objects.json --response observation.json
64 python control.py --bank my_workspaces.json --request examples/move_proposal.json --response proposal.json
65 python control.py --bank my_workspaces.json --commit proposal.json --response commit.json
66 python cli.py --bank my_workspaces.json run objects
67 python cli.py --bank my_workspaces.json inspect objects root/shifted
68 ```
69
70 Response files are written only to new paths. The example request is based on revision `r000002`, which is the object workspace in a freshly initialized bank. After changing the workspace, observe it again and update `expected_revision` in your request. Stale proposals are deliberately rejected.
71
72 The response contains the full proposal receipt and inspection data. The console prints a short status when `--response` is used. Without it, the complete response is printed as JSON. A successful bank write and a response-file write are separate filesystem operations. If response export fails after a bank write, the error includes `bank_updated: true`.
73
74 Direct workspace editing is still supported:
75
76 ```powershell
77 python cli.py --bank my_workspaces.json fork objects alternative
78 python cli.py --bank my_workspaces.json preview alternative --patch examples/offset_2.json
79 python cli.py --bank my_workspaces.json edit alternative --patch examples/offset_2.json
80 python cli.py --bank my_workspaces.json compare objects alternative
81 python cli.py --bank my_workspaces.json graph objects
82 python cli.py --bank my_workspaces.json trace objects --output object_trace.json
83 python cli.py --bank my_workspaces.json undo alternative
84 ```
85
86 The direct editor applies the requested change without the optional target/lock constraints of a proposal. Use the action interface when those constraints should govern the edit.
87
88 ## Python integration
89
90 ```python
91 from collection_scenarios import make_bank, proposal
92 from machinery.actions import Actions
93
94 bank = make_bank()
95 interface = Actions(bank)
96 observation = interface.apply({"action": "observe", "workspace": "objects"})
97 preview = interface.apply(proposal(bank))
98
99 if preview["status"] == "ready":
100 result = interface.apply({"action": "commit", "receipt": preview["receipt"]})
101 ```
102
103 `proposal(bank)` in this example supplies a hand-authored edit. A future controller would construct that request itself. Functions can still be registered through `Store.define_function` or the existing CLI `define` command.
104
105 ## Scope and limits
106
107 - Component extraction is an authored same-color connected-component algorithm. Connectivity is explicitly 4 or 8. This is not learned object discovery.
108 - Object source and origin identifiers record provenance. Regrouping a changed scene creates new identifiers, so they are not persistent physical-object identities across observations.
109 - Collections have one level and at most 64 entries. Nested collections are rejected. Map and filter preserve order; fold processes items in that order.
110 - Grids are at most 128 by 128, with integer colors 0 through 9. Graphs permit at most 256 nodes and share a 2,048-step execution budget. Existing iteration and function-depth bounds remain.
111 - Translation must keep every object pixel in its coordinate frame. Painting checks frame compatibility and can reject occupied destinations. Erasing checks that the selected source pixels still match.
112 - Scalar tolerances are explicit in proposal constraints. Grid and mask comparisons are exact. Feedback is reported by output type without pretending that scalar error and cell mismatch counts share one unit.
113 - Proposal hashes detect accidental changes. They are not signatures or authorization credentials. Commit rechecks the revision, library, execution result, targets, and protected outputs.
114 - A receipt becomes stale after its workspace changes. Restoring exactly the original revision can make that same proposal applicable again. Receipts are not single-use tokens.
115 - Native operations remain trusted local Python. JSON requests can select registered operations and edit graphs, but cannot introduce arbitrary Python code.
116 - The action interface currently edits existing inputs and graph structure. Autonomous search, action selection, representation learning, learned stopping conditions, and training updates are not included.
117 - v0.6 bank files are not silently converted to this version. Its complete original ZIP is preserved under `previous/`. The v0.6 programs and example outputs were checked in the new runtime, but automatic bank migration remains unfinished.
118
119 The demonstration registry contains **29 supplied native operations, three frozen learned kernels, and three authored functions**. It does not contain 35 newly learned operations.
120
121 Read `PROTOCOL.md` for request and node formats and `VERIFICATION.md` for the checks and their limits.