Status Current

Path scoping-notes/loomworks-current-engagement-spine-scoping-note-v0_1.html

DUNIN7 · Loomworks · Scoping Note

Current-engagement spine

Version. v0.1
Date. 2026-06-26
Author. Claude.ai (scoping)
For. The Operator, to decide scope before a change request is drafted.
Repository home. loomworks-record/scoping-notes/

Read this first

What this does. It gives each person a single "where I am" — a current engagement the Companion holds onto. Today, every time you talk to the Companion the caller has to say which engagement the turn is about; there is no server-side memory of "the one I'm in right now." This adds that memory: one field, current_engagement_id, on the host_account row. The Companion sets it when you say "open Goosey"; the converse path reads it so an unqualified instruction like "commit held 14" resolves against the engagement you're in, without you naming it again.

Why it matters. This is the keystone the voice-first Companion rests on. Without a server-side "here," voice can't carry unqualified verbs — every spoken command would have to re-name its engagement. With it, "open Goosey" then "commit held 14" works the way speech actually works.

What decision is needed. Two, named in section 6: (1) addressing scope for "open X" — name and E####/UUID resolve today, per-Operator number ("open 7") does not; decide whether to add it or defer. (2) clear-focus semantics — what sets focus back to null, and what converse does when focus is null and the caller also omits project_id.

In scope. One engine field + migration; the converse read defaulting; the Companion write on "open X"; reading "here." Out of scope. A session table; concurrent contexts; gap-4's full referent set (rides on this structure later); reference resolution engine-side (queue item C).

Grounding. Every structural claim below was confirmed against live engine state by Claude Code on 2026-06-26 (read-only inspection). Line numbers and signatures are live, not remembered. Where the handoff carried a claim the live code corrected, the correction is marked.

1. What is settled coming in

From the engagement-identity record (substrate/loomworks-engagement-identity-record-v0_1, commit 8d8fbe9) and last session's Bin-3 findings (investigations/loomworks-companion-bin3-capability-findings-v0_1, commit e3da809):

The structure is decided. Current focus is a field on host_account, single focus per person, not a session table. The session table is deferred until concurrent contexts are a real need — they are not today.
A "conversation" has no server-side state object. It is just the implicit set of conversation_turns for a (person, engagement) pair. This field is the first piece of per-person conversational state to live server-side.
Addressing vocabulary (identity record): an engagement is addressed by name (for speaking), per-Operator number (operator_sequence_number, your "23"; Personal is "0"), and E#### (display_identifier, instance-local label). UUID is the identity but stays invisible to humans.

This note does not reopen any of those. It grounds them against the live engine and scopes the build.

2. Live engine state (grounded 2026-06-26, read-only)

2.1 `host_account` is the natural home — confirmed strongly

host_account already carries a nullable engagements FK and is already loaded on the converse path:

personal_engagement_id — uuid, nullable, FK → engagements(id) (host_account_personal_engagement_id_fkey). ORM at models.py:281: Mapped[UUID | None].
companion_name — text, NOT NULL, default 'Companion'. ORM at models.py:276.
One row per person (PK id = principals.id), so one column = one focus per person — the single-focus rule falls out of the table shape.

current_engagement_id is a structural clone of personal_engagement_id: Mapped[UUID | None] + ForeignKey("engagements.id"), nullable.

engagements PK = id (uuid), engagements_pkey. The FK target is grounded on the real column.
Alembic head (live): 0094. The migration is the next revision after 0094.

2.2 The converse read site already exists

Handler: src/loomworks/orchestration/routers/converse.py:579, async def operator_converse(...).

Today, scope comes from the request body every turn — body.project_id (ConverseRequest, schemas.py:539). At converse.py:643: if body.project_id is not None: → membership verify + context load. The caller supplies the engagement on every call. No server-side focus exists — a grep for current_engagement / focused_engagement / active_engagement returns nothing relevant.

The read site is already in hand. At converse.py:631 the handler loads host_account; at :632 it reads companion_name; at :637 it reads personal_engagement_id. current_engagement_id would be read at :637, beside personal_engagement_id, with no new database load — host_account is already loaded for this person on this call.

2.3 "open X" resolution today — the one correction to carry

EngagementList.tsx:137 resolves on display_identifier ?? project_id (E#### / UUID). Not name, not per-Operator number at the address bar.
The in-engagement address resolver (page.tsx:16) tolerates 0, Personal, E####, or a UUID.
Resolution by name exists narrowly: engagement/redirect.py:103 _resolve_engagement_name(...), used by the cross-engagement redirect flow — not the address resolver.
Resolution by per-Operator number exists only as a frontend list-expansion shorthand: voiceRecognizer.ts:13-14 ("engagement N → expand the row whose operator_sequence_number === N"), driving EngagementList.tsx:48,55. It expands a list row; it does not resolve to an address and has no engine-side path.

Handoff correction · drift-surface

The handoff implied the per-person sequence might be host-side. It is not — operator_sequence_number lives on memberships (BIGINT, NOT NULL, UNIQUE per person), the per-person-per-engagement sequence. This does not change the current_engagement_id-on-host_account conclusion, but it means "open 7" (by number) has no resolution path to feed the spine today. That is decision 1 in section 6.

3. What this builds

3.1 Engine

One field on host_account: current_engagement_id, uuid, nullable, FK → engagements(id). Structural clone of personal_engagement_id. ORM beside it in models.py.
One migration (next revision after 0094): add the column + FK constraint. Up/down clean round-trip.
Converse read defaulting at converse.py:637/:643: when the caller omits body.project_id, default scope to host_account.current_engagement_id. Shape: engagement_id = body.project_id or host_account.current_engagement_id. The membership-verify and context-load at :643 then run against the resolved id. (Decision 2 governs what happens when both are null.)
A write path to set focus: an engine operation the Companion calls on "open X" that sets current_engagement_id for the person. (Dedicated endpoint vs. folded into an existing operation is a CR-level detail, section 7.)

3.2 Companion

"open X" → resolve → set focus. The Companion resolves the spoken handle to an engagement, then sets current_engagement_id. Resolution handles governed by decision 1.
Reading "here." "where am I" / "what am I in" surfaces the current engagement (name + per-Operator number + E####, per the identity record; UUID invisible).
Unqualified verbs ride the focus. After "open Goosey," "commit held 14" resolves against the focused engagement with no re-naming.

4. What this does NOT build

No session table. Deferred until concurrent contexts are real. The per-person host_account row is the home.
No concurrent / multiple foci. One focus per person, by construction.
No gap-4 referent set. "the second one" / full reference resolution engine-side (queue item C) rides on this structure later. Not built here.
No composite engagement-state endpoint (queue item D / gap-2). Independent optimization.
No change to body.project_id callers. Existing callers that pass project_id are unaffected — the default only fires when it is omitted. Additive and backward-compatible.

5. Why this is the keystone

The Bin-3 findings cost-sorted the four genuinely-missing capabilities. This is item B, and items C and D extend its structure:

Voice-direct needs a "here" or every spoken verb must re-name its engagement. This supplies the "here."
Reference resolution (C) needs a per-conversation referent set; the focus field is the first server-side conversational-state column, and C's engine side extends the same row.
The handoff's structural insight: gaps 1 (this) and 4 (reference resolution) share a root — no per-conversation server-side state object. Build this, and C's engine side is an extension, not a new structure.

6. Decisions needed before the CR

Decision 1 — Addressing scope for "open X"

The question. Which handles resolve "open X" to an engagement the spine can focus on?

Name — resolves today (redirect.py:103), redirect-flow only; reusable.
E#### / UUID — resolves today (address resolver).
Per-Operator number ("open 7") — does not resolve to an address today; only a list-expansion shorthand on memberships.operator_sequence_number. Adding it means a number→engagement resolution path for this person.

Options

1A — Name + E#### / UUID only (defer number-resolution). Smaller. "open Goosey" and "open E0007" work; "open 7" does not yet.
1B — Add per-Operator number resolution so "open 7" works too. Larger — a number→engagement lookup against memberships for the person, wired into the Companion's resolve step.

Best-guess default: 1A. Ship the handles that already resolve; defer number-resolution to its own small piece. The identity record names all three as valid handles, so 1B is on-trajectory whenever taken — but it is separable, and the spine doesn't need it to stand up. Confirm with one word, or say "1B" to fold it in.

Decision 2 — Clear-focus and null-focus semantics

The question (two halves).

What clears focus (sets current_engagement_id back to null)? Candidates: leaving an engagement in the UI; an explicit "close" / "leave"; nothing (focus persists until next "open"); session boundary.
What does converse do when focus is null AND the caller omits project_id? Candidates: error asking which engagement; fall back to Personal (personal_engagement_id); no-op with a Companion prompt.

Best-guess default

Focus persists until the next "open" or an explicit "close." Simplest, matches "where I am" — you stay where you were until you move. No session-boundary clearing (no session object to hang it on).
Null focus + omitted project_id → the Companion asks which engagement (does not silently fall back to Personal — silent fallback would put commits in the wrong place).

Confirm, or name a different pair.

7. CR-level details deferred (named, not decided here)

Whether the focus-write is a dedicated endpoint or folds into an existing operation.
Exact migration revision id and naming.
Whether reading "here" is a new converse intent or a Companion-side surface read.
Test coverage shape (default-fires-when-omitted; existing-project_id-unaffected; null-focus path per decision 2; migration round-trip).
Frontend render-robustness reminder (identity record): E#### rendering must not assume exactly four digits.

8. Seed alignment

The Loomworks seed governs what the work is, the commons, who consumes it, voice, constraints, declared shape/render-types, success conditions, authorisation. It is silent on current-engagement focus and converse-path addressing — those sit below the seed, under the architecture specification (spec governs when the seed is silent). The one seed-adjacent surface is Companion addressing vocabulary, and the engagement-identity record already governs that (name + per-Operator number + E####; UUID invisible). No conflict with the seed's commitments is visible.

Version caveat · drift-surface

This note was drafted without the canonical seed in hand — the highest seed reachable to the drafting session was v0.8, while canonical is the highest loomworks-candidate-seed-vN_M on loomworks-record main. The spine topic is below the seed regardless of version, so the alignment conclusion holds; but at CR time, the executing session should confirm the canonical seed (and architecture spec v0.4) say nothing this note contradicts.

9. Step-0 inspection — already done

The read-only Step-0 inspection that normally opens a build was run during this scoping pass (2026-06-26). Findings are in section 2, grounded against live code. A CR drawn from this note starts from grounded state; it does not need to re-run Step 0 unless the engine has moved (alembic head was 0094 at grounding).