Version. 0.1 Date. 2026-05-28 Status. Working draft. Opens the next working session.
This document carries the state of the Loomworks build forward into a new chat session. It exists because the previous session ran long, through a cascade of six findings that began as a single test and ended with real fixes landed on two repositories and a record update. The discipline is a fresh chat for each new arc; the four items left open are a new arc, so this handoff opens it clean.
What the previous session accomplished: the file upload pathway, which had never actually run from end to end against the live system, now works. Getting there meant fixing three development-environment configuration problems, starting a storage service that was not running, restoring a route that had been made unreachable, and fixing a database-transaction bug in the upload handler. All of it is recorded in the queued-directions document at version 0.18.
What this session does first: the four open items below, in the recommended order. The smallest and lowest-risk one — the configuration-drift remediation — goes first because until it is done, every fresh checkout of the code reproduces the same three problems the previous session spent time clearing.
What decision is needed from the Operator at the start of this session: confirm the sequence below, or reorder it. Everything is queued; nothing is mid-flight.
| Repository | Main head | What it is |
|---|---|---|
| Engine (loomworks-engine) | 040d675 | The substrate. Python, FastAPI, PostgreSQL. The upload-handler transaction fix landed here. |
| Operator Layer (loomworks) | 2186d13 | The Operator-facing frontend. Next.js, TypeScript. The route restoration landed here. |
| Workshop (loomworks-ui) | frozen pre-rename | The older four-room view. Intentionally frozen; carries the original Memory contribution surface. |
| Record (loomworks-record) | 8fc2b76 | The canonical document home. Queued-directions version 0.18 landed here. |
These four services were running when the previous session closed. If this session opens on a fresh machine state, they will need restarting — see the configuration-drift item below, because the restart will reproduce the drifts unless the remediation has landed.
| Service | Port | Process identifier | Note |
|---|---|---|---|
| Engine | 8000 | 62250 parent, 62252 worker | Carries the .env corrections from the previous session, not yet checked in |
| Operator Layer | 3001 | 27054 | |
| Workshop | 3000 | 34740 | Optional; only needed to compare against the original Memory contribution surface |
| Storage (MinIO) | 9000 (interface), 9001 (console) | 37440 | Data directory /Users/dunin7/minio-data; credentials are the development defaults |
The production passkey path does not work against the local development environment — the Operator has no real passkey registered there, and the existing credential record is a fixture. Use the development shortcut: open http://localhost:3001/auth, enter the Operator's person identifier 6d867b23-655a-440a-b377-e6bf4fb3882b, submit. This mints a session that lasts one hour. This is recorded as open work in the queued-directions document, section 13.2.
The session began as a test of the file upload pathway and became a cascade of six findings, none visible at the outset. Recorded here so this session does not re-derive them.
.env file — but the source-code defaults still carry the old values, so a fresh checkout reproduces all three. This is the first open item below.The key lesson, worth preserving for any Discovery record built from this work: the upload pathway had never run end to end against the live system before. The earlier verification on 2026-05-14 was at the surface level only — the icons appeared and the file pickers opened, but no file was ever processed through the live engine and storage. Each infrastructure layer masked the next, and the test suite was green throughout while the real path was broken.
Recorded at queued-directions section 13.2.
What it is. Three development-environment settings have source-code defaults that reflect an older environment. The corrections live only in the engine's .env file and are not checked in, so every fresh checkout reproduces all three problems. The three: the passkey origin defaults to port 3000 while the Operator Layer runs on port 3001; the storage access key and secret key default to empty strings while the storage service needs credentials; and one test asserts against port 3000.
What to do. Either update the source-code defaults to match the current development environment, or check in a development-environment reference document (an example environment file, or a short development-environment note) that names every override a fresh checkout needs.
Why first. It is the lowest-risk item — no production behaviour changes — and it stops the reproduction. Until it lands, the next person to clone the repository hits all three drifts before reaching any substantive work.
Recorded at queued-directions section 15.2.
What it is. The upload-handler bug was invisible because the test fixtures did not mirror the production database-session behaviour. The five upload-test fixtures have now been corrected, but whether other test fixtures across the engine suite have the same divergence is unaudited.
What to do. Find every place the test suite overrides the database-session dependency, and verify each one mirrors the production envelope — the production session commits on a clean return and rolls back on an exception. Fix any that diverge.
Why second. It is bounded inspection-then-fix work with a clear completion condition and no architectural decisions. It naturally follows the configuration item because both are engine-side cleanup.
Recorded at queued-directions section 15.1, second sequenced action.
What it is. The upload affordance currently lives on the restored /chat?project= surface. The architecture specification names a different destination: file upload through the in-engagement composer itself, so files come in through the same surface as conversation rather than through a separate one. The in-engagement composer is hand-built and does not currently reuse the upload components, so this port has surface implications that will likely surface further gaps.
What to do. This is phase-shaped work, not a fix. It deserves a scoping conversation, then a scoping note, then a Change Request, before any execution. Three fix shapes are already named in the record: extend the in-engagement composer with the upload affordance; refactor the in-engagement composer to reuse the existing upload components; or keep both surfaces. The scoping conversation chooses among them.
Why third. It is the only genuinely architectural item, and it should not be done as a quick fix — that pattern is exactly what produced the transaction bug that hid for two weeks.
Recorded at queued-directions section 15.1, third sequenced action.
What it is. A methodology lesson, not a build task: when a Change Request changes how an existing route resolves, the reachability of any affordance that depended on the old route should be explicitly verified — preserved, migrated, or named as deferred — before the Change Request closes. Two correct-in-isolation changes combined to delete the upload affordance's reachability, and neither change had responsibility for the boundary between them.
What to do. Fold this into the version 0.21 methodology consolidation whenever that consolidation happens. It does not travel with the build session.
loomworks-queued-directions-and-deferred-work-v0_18.md in the record repository. Sections 13.2, 15.1, and 15.2 carry the four open items.040d675 — the upload-handler transaction fix.2186d13 — the route restoration.8fc2b76 — queued-directions version 0.18.loomworks-candidate-seed-v0_9 — the foundation document, read first in any session that touches settled commitments.loomworks-architecture-specification-v0_4.md — governs where the seed is silent; its section 13 ("Memory population surface unification") is the framing for the third open item.For any Discovery record built from the previous session:
DUNIN7 · Loomworks · Session Handoff 2026-05-28 · v0.1