Purpose. This document is the foundational architectural specification for Loomworks. It begins as a structural scaffold and grows with the project — like a building's master architectural drawing set that starts as the outline and accumulates layer after layer of detail as decisions are made and components are built.
How to read it. The sidebar lists the major sections. Each section has a status badge showing what's built today versus what's planned or under investigation. Within sections, individual components carry their own inline status markers. Expandable sections hold detail that would overwhelm the surface if always present.
How to maintain it. Each substantive change to Loomworks should update this document. Where the change makes a planned thing built, the status updates. Where the change surfaces a new component, a new subsection is added. Where the architecture itself evolves, the structural skeleton accommodates the change.
Status
Built today
Partially built
Planned
Under investigation
Loomworks is the engagement memory environment for the agentic era. It is built around the idea that a person doing substantial work — building something, thinking through a domain, accumulating expertise — needs a place where that work lives durably, where the memory of what has been decided and produced grows over time, and where an AI collaborator works alongside them as a real participant rather than as a query interface.
The person doing the work is called the Operator. The unit of work is called an Engagement. The Operator's collaborator within an Engagement is called the Companion. The Companion is invisible as AI — it appears as a colleague, named by the Operator, with a voice that is warm, capable, and unannounced.
Around each Engagement, the methodology specifies four layered concepts through which work flows:
Memory
Accumulated knowledge
Manifestation
Organized at a moment
Shaping
Arranged for a reader
Rendering
Produced as artifact
These are not four tabs. They are four conceptual layers describing what happens to material as it accumulates in an Engagement. Memory holds everything. Manifestation organizes Memory at a point in time. Shaping arranges organized knowledge for a specific reader. Rendering produces the artifact that reader receives.
"A four-stage pipeline for agentic work. The Companion is your surface to it: the same interlocutor through Memory, Manifestation, Shaping, and Rendering."
The protocols Loomworks rests on are three: Loom (the engagement-memory wire layer), FORAY (the transaction grammar that attests every consequential action), and OVA (the agent identity and authorization layer). The three compose; removing any one leaves a gap the others cannot close.
Loomworks is built around a small set of foundational concepts that recur everywhere. Each is sketched here; deeper detail lives in the sections that follow.
The Operator is the person doing the work. They have final authority over their Engagements. They are the only party whose commitment makes contributions durable. The methodology's commitments — to Operator-final-authority, to plain-English communication, to "only show what is available," to Operator-vocabulary throughout — all derive from treating the Operator as the central actor.
Each Operator has their own identity, their own personal Memory space, their own Companion (named by them), their own dashboard showing the Engagements they belong to, and their own posture toward each Engagement (Operator on some, Contributor on others, Domain Expert on others still).
The Companion is the Operator's collaborator within an Engagement — the conversational interlocutor through which most interaction happens. The Companion is invisible as AI; it appears as a named entity (default name "Companion", renameable by the Operator), with a voice that is warm, capable, and unannounced. The Companion never refers to itself as an AI, never names models, never uses engine vocabulary.
The Companion has a standing posture and an engaged posture. The standing Companion runs alongside the Operator's day continuously — Operator-bound, not Engagement-bound. The engaged Companion foregrounds when the Operator enters an Engagement, working with that Engagement's seed and memory.
See Section 08 for the Companion's behaviors in depth.
An Engagement is the unit of bounded work. Everything an Operator does in service of one purpose — a project, a research domain, a body of knowledge being built — lives in an Engagement. Each Engagement has its own Memory, its own Companion-state, its own seed (the founding articulation of what the Engagement is about), and its own four-room structure.
The Engagement is also a universal adapter. Anything that needs the methodology's governance properties — a credit ledger, a legal-document workflow, an external integration — can be modeled as an Engagement. See Section 07 for the patterns this enables.
Each Operator has a special personal Engagement — addressable by the number 0 or the name Personal — that holds their notes, thoughts, and material that doesn't belong under any specific project. Project Engagements receive identifiers of the form E#### (for example, E4729) that are universal — the same value for every Contributor to the Engagement — plus per-Operator sequence numbers for working-set handling.
The seed is each Engagement's founding articulation — a brief that names what the work is, who consumes it, the voice it takes, the constraints it operates under, the success conditions, and any additional commitments. The seed governs the Engagement's life. It is the frame against which Memory is interpreted, contributions are evaluated for relevance, and Manifestation is organized.
The seed has a specified structure: R-A5 what the work is, R-A6 who consumes it, R-A7 voice, R-A8 constraints, R-A9 success conditions, R-A10 initial contributors and agents, R-A11 additional assertions.
StatusSeed creation through Companion-assisted Discovery dialog exists. Seed editing exists in the substrate via the considerations pipeline, but no Operator-facing surface exposes it. The Engagement's seed is reachable in substrate but not surfaced as a permanent affordance on the in-engagement surface. Making the seed a living frame of reference is identified work, not yet shipped.
An assertion is the durable unit in Memory. Every contribution that is meant to last becomes an assertion. Each assertion carries its content, its provenance (who contributed it, when, how, from what source), and its lifecycle state (held, committed, retracted, superseded).
Assertions are not edited in place. When an assertion changes, the old one is retracted (preserved with a "RETRACTED" marker) and a new one is written that supersedes it. The trajectory of how the Engagement's understanding evolved is always recoverable.
Engagements can be organized through two orthogonal mechanisms. Workspaces are vertical containment — named places the Operator enters (a client's account, a quarter's planning, a domain of work). Entering a Workspace narrows the visible Engagement set. An Engagement can belong to multiple Workspaces simultaneously. Tags are lateral grouping — free-form strings applied to Engagements for slicing across Workspaces.
Both coexist as first-class. Each serves a different cognitive purpose: Workspaces for "where am I working right now," tags for "show me all the urgent ones."
Memory is the engagement's accumulated knowledge — everything that has been contributed, by everyone, over the life of the Engagement. When someone contributes, their contribution enters Memory. It carries who contributed it, when, and how. The system records the lineage automatically; the contributor focuses on the knowledge itself.
"Memory does not forget. Contributions that are corrected or superseded remain visible as part of the record. The trajectory matters — not just where the engagement arrived, but how it got there. A correction is a contribution. A retraction is a contribution. Both are preserved."
Memory grows. It is never finished. Every other operation in the system — Manifestation, Shaping, Rendering — draws from Memory. Memory is the source. Nothing downstream exists without it.
Memory is populated through multiple modalities, each with its own pathway. The pathways differ in immediacy and surface affordance but converge on the same assertion structure once they land in Memory.
- Talking Built — The Operator types or speaks to the Companion. Each contribution becomes a conversation turn. Some turns become assertions; others remain as conversational scaffolding.
- Voice transcription Built — The Operator speaks; the browser's speech recognition transcribes; the transcript commits when the Operator stops speaking (silence-submit). Voice-originated assertions are visually distinguishable from typed ones via a small microphone glyph.
- Upload Built in substrate; not surfaced on in-engagement surface — The Operator brings in a file. The substrate detects the format, runs the appropriate transformation skill (text extraction, audio transcription, image OCR, vision analysis), and produces assertions. The full upload pathway exists; the affordance is unmounted on the surface Operators actually use today.
- Quick-capture Planned — A fast-path Memory contribution for utterances like "I parked on level 10." Dictation-class capture, automatic routing to the right Engagement, brief acknowledgment, optional Companion-noticed supersession when later utterances contradict earlier ones.
- Seed creation Partial — The first piece of Memory in any Engagement is its seed, created through Companion-assisted Discovery dialog. The substrate primitive (Discovery-to-seed skill) exists; the conversational surface exists; runtime-binding and conversation-orphaning issues remain unresolved.
Identified gapThe population pathway is uneven across modalities. Talking is solid. Voice is solid. Uploading is built but unmounted on the Operator's in-engagement surface. The result is a surface that looks like it accepts only talking, even though the substrate supports more. This is the most consequential current gap in Memory's practical reachability.
Memory holds assertions; each assertion needs to be addressable so it can be referenced, retracted, superseded, or pointed at conversationally. Current substrate carries assertion identifiers and supports the lifecycle operations. Surface affordance for addressing is under active investigation.
Current investigation: M-prefix addressable assertions
The addressing scheme under investigation uses an M#### prefix for assertions (M for Memory). An Operator can say "retract M37" or "show me M5" and the Companion knows what to do. The substrate supports retract and supersede at the API level today; the surface affordance — selection mode, addressable identifiers visible on assertions, spoken-and-typed-addressing — is being scoped.
The investigation also includes: prefix collision analysis (M vs E vs S), unbounded identifier formats (E1 through E10000+ without format break), the engagement identifier substrate refactor (collapse display_identifier into operator_sequence_number), and selection mode with checkbox visibility only when selecting.
Assertions have a lifecycle. They are first held (proposed but not yet authoritative), then committed (the Operator's authority makes them durable). After commit, they can be retracted (marked invalidated, with a required rationale) or superseded (a new version is written and the old becomes part of the version chain).
The held-then-commit ceremony is load-bearing. A held assertion that turns out to be wrong can be retracted before commit without leaving a persistent trail (it never existed). A committed assertion that needs correction goes through retract-or-supersede, both of which preserve history.
The Memory room UI supports revise and retract operations on the four-room surface. The newer in-engagement surface has not yet wired these affordances — they are reachable in substrate but not surfaced in the place Operators currently work.
As Memory accumulates, two risks compound: drift (the Engagement's content gradually wanders away from its founding purpose) and bulk (uploaded materials produce many assertions, most of which don't serve the Engagement's focus). The Companion's job, sitting in the middle of Memory contribution, should be to evaluate contributions against the seed for relevance.
The evaluation is Companion-mediated, not gating: the Companion notes off-topic drift, surfaces elicitation when relevance is mixed, asks before extracting bulk that doesn't fit. The Operator's authority is preserved; the Companion's role is to surface the question, not decide it.
Example — mixed-relevance upload
Operator uploads "Annual Operations Manual 2026" — 50 pages, mixed content. Companion reads, evaluates against seed, surfaces: "Pages 1-30 look directly relevant — cattle, crops, equipment. Pages 31-50 are about HR and finance, which seem outside this engagement's focus. Should I focus on the relevant pages, or extract everything?"
Every assertion knows its provenance: who contributed it (which Person), when (timestamp), how (typed, spoken, transcribed, extracted from file), and from what source if applicable (the specific upload, the specific conversation turn, the specific transformation skill). Provenance is preserved through retract and supersede — superseded assertions still know their origin.
Provenance becomes load-bearing in multi-Contributor Engagements (knowing who said what), in audit scenarios (the FORAY-attested trail), and in cross-Engagement awareness (knowing which Engagement an assertion belongs to).
Memory is not a single space. The methodology recognizes multiple scopes that compose: the Engagement's primary Memory, the Operator's personal Memory (in their personal Engagement), standing Memory (the standing Companion's working state, distinct from personal), and — as the architecture grows — organization Memory, team Memory, role Memory, jurisdiction Memory, and domain Memory.
All spaces share the same assertion structure, the same authority model, and the same audit posture. What differs is visibility scope — who can see, who can contribute, what queries surface what. The Companion composes across the spaces relevant to the current operation; the Operator works with a single substrate that internally draws from the composed access set.
Scopes named so far
- Personal scope — the Operator's own Memory in their personal Engagement.
- Standing scope — the standing Companion's working state, distinct from personal Memory.
- Engagement scope — each Engagement's primary Memory.
- Organization scope — content shared across an organization's Engagements (brand, conventions, policies).
- Team scope — content shared across a team's Engagements.
- Role scope — content associated with a role someone holds across Engagements.
- Domain scope — content shared across Engagements in the same domain (agriculture, law, software).
- Jurisdiction scope — regulatory floor that composes into Engagements within a jurisdiction.
Authorization for cross-scope access is OVA's territory — see Section 09.
A Manifestation is Memory organized at a moment in time. Memory accumulates continuously — contributions arrive, knowledge grows, corrections land. At any given moment, the Engagement's Memory is a body of knowledge, but it has no structure beyond the order contributions arrived. Manifestation is the organizing act.
The system reads the Engagement's seed and all committed assertions, and produces a structured ordering — groups with labels, assertions placed within groups, the groups themselves ordered so that foundational knowledge precedes applied knowledge. The result is a Manifestation: Memory made readable as a coherent body of knowledge.
"A Manifestation is not a copy. The assertions remain in Memory. The Manifestation is a reading of Memory — an organizing act that says 'here is how this body of knowledge hangs together right now.'"
- Organize on demand Built — Manifestation fires on explicit invocation, not on every Memory write. The Operator (or the seed-management skill, or a future trigger) decides when re-organization is worthwhile.
- Read from seed and assertions Built — Manifestation explicitly takes the seed as input alongside the committed assertions. The seed governs how the organization happens.
- Label groups intelligibly Built — Groups emerge from the content with descriptive labels. The labels are not imposed by a fixed taxonomy.
- Show rationale Planned — Why is this assertion in this group? The grouping should not be opaque; the Operator should see why the system put things where it did.
- Allow Operator override Planned — If the Operator disagrees with a grouping, they can move things. The Operator's structure of their own knowledge is authoritative.
- Preserve prior Manifestations Built — When Memory grows and a new Manifestation is derived, prior versions are preserved but superseded. The history of organization is itself a record.
The Manifestation is downstream of Memory but upstream of Shaping and Rendering. Shaping does not reach back into raw Memory; it works against the current Manifestation. This makes Shaping stable: a Shape derived from Manifestation version 3 draws from exactly the same organized knowledge today as it will tomorrow, even if new assertions arrive in Memory overnight.
The discipline that decides when a new Manifestation should be derived — too often, and downstream work re-runs constantly; too rarely, and the organization drifts from current Memory — lives in the engagement-specific skill that manages the Engagement's lifecycle.
Shaping is the moment where the Engagement's accumulated knowledge gets organized for someone specific. Everything the Engagement knows lives in Memory. The Manifestation organizes Memory at a point in time. But neither of those is shaped for any particular reader — they are the whole body of knowledge, organized but not directed at anyone.
Shaping takes that organized knowledge and asks: what does this specific reader need, and how should it be arranged for them? The same Memory, the same Manifestation, produces different Shapings for different readers. The knowledge does not change — what changes is what gets selected, what gets emphasized, and what gets left out.
Example — the methodology Engagement
From the same body of knowledge about how Loomworks works: a phase preparation Shaping selects what's relevant to the next build phase and arranges it for the person writing the change request. A project overview Shaping selects the cross-cutting inventory so someone arriving fresh can orient in minutes. An education Shaping selects methodology concepts so a person encountering Loomworks for the first time can understand what Memory is, what an Engagement is, how to contribute — without reading a single change request or implementation note. Same knowledge. Different readers. Different selections.
- Named Shape types Built — Each Shape has a declared type (DeclaredShapeType). A type names its consumer, its format, and its grammar. Specifications, scoping notes, change requests, manifest entries are examples of types built today.
- Selection Built — When shaping, the system picks the right assertions for the Shape. Not everything in Memory belongs in every produced document.
- Drafting Built — Selected material gets composed into the Shape's structure.
- Refinement Partial — The first draft is rarely final. The Operator can ask for refinement; the system reshapes. The refinement loop is partial; not yet a fluid conversational affordance.
- Versioning Built — Every shaping produces a draft that is preserved. Earlier drafts remain addressable.
- Specification grammar declaration Built — Shape types can declare the specification grammar they produce (legal-document grammar, REQ table grammar, design specification grammar). This makes downstream render specialists' contracts explicit.
Rendering produces the final artifact that the reader actually receives. Memory accumulates knowledge. Manifestation organizes it. Shaping selects and arranges it for a specific reader. Rendering produces the thing they hold in their hands — the document, the report, the guide, the reference, whatever form the reader needs.
Rendering has two modes. In some cases, Loomworks owns the production directly — generating documents, reports, audio files, conversations. In other cases, Loomworks produces the specification that a downstream production system consumes — an app spec for Claude Code, a design spec for whatever produces the final form.
The render layer doesn't anticipate every production environment; it supplies the inputs each one needs.
"Loomworks may simply produce the REQ file (spec) that is then fed into a production system. The render system cannot anticipate the future production environments but it can supply the inputs."
- Multiple output formats Partial — Different deliverables need different formats. Markdown, HTML, and specific render types are built; PDF, slides, audio are planned for the general capability.
- Format-appropriate specialists Partial — Each format has its own conventions. Rendering invokes the right specialist for each format. The Specialist SDK that admits more render destinations is partial.
- Async production Built — Renders that take time (image generation, external production) return a handle; the substrate polls until completion; the Render lands when production finishes.
- Re-rendering Built — When the Shape evolves, the rendered output can be regenerated.
- Provenance Built — Every rendered artifact knows which Shape produced it, which Memory contributed to that Shape, which Engagement it belongs to.
- Render-as-spec for production systems Investigating — Render specialist SDK for external production systems (Claude Code as render specialist; external generators; 3D printing; physical artifacts).
Some renders ship without per-action approval — the credit system's corrective FORAY flows, reconciliation events, automated state transitions. These are operational renders — they run because the Engagement's Memory holds the rules under which they are permitted, and the Engagement's specialist runs under OVA authorization scoped to that Engagement. The harm-prevention surface moves upstream from per-action approval to rules-in-Memory.
The Engagement is the methodology's unit of bounded knowledge work, but it is also the methodology's unit of integration with everything outside the Engagement. Any system that needs to participate in Loomworks — a credit ledger, an external API, a fleet management plane, a feedback intake, a marketing content pipeline — can be modeled as an Engagement. Once modeled as such, it inherits the methodology's affordances: a Companion, a four-room pipeline, FORAY-attested actions, OVA-scoped access, and the Operator-as-final-authority discipline.
This is the engagement-as-universal-adapter principle. Not every external system should be an Engagement — many don't merit it. But the Engagement abstraction is the right shape for any system that wants the methodology's governance properties.
Two kinds of Engagement emerge from this framing.
Operational Engagements hold knowledge that is the Engagement's own — research notes, curriculum materials, customer conversations, agricultural observations. The substrate doesn't depend on this knowledge for its own operation; the Engagement is the consumer.
Infrastructure Engagements hold knowledge that the substrate itself reads on the hot path — credit balances, account lifecycle state, fleet membership. The substrate co-locates this knowledge under a separate database schema for the Engagement, but the Engagement is still governed through the pipeline. The credit system was the first infrastructure Engagement.
Some governance problems split naturally into two Engagements rather than collapsing into one. The Authority Engagement sets policy and issues decisions. The Accounting Engagement maintains balances and reconciles. The credit system uses this pattern: Credit Management is the Authority; Accounting is the bookkeeping.
An orthogonal distinction. Resident Engagements consume their renders internally — the Companion answers a question, the Operator reads the answer, the answer might shape the next action. Delivery Engagements produce artifacts that ship outside — a contract, a webpage, a report sent to a customer. Some Engagements are both, with different renders going to different audiences.
Engagements operate in three modes. Runtime mode: the Engagement is its own runtime; its work is internal. Workspace mode: the Engagement produces shippable artifacts (documents, reports). Authoring-environment mode: the Engagement specifies a deployed system that operates beyond it (a CR/REQ loop that feeds back from a running production system). The three modes have different audit needs and different render specialist classes.
Some Engagements coordinate around a subject that multiple independent parties contribute to — a property, an asset, a person whose record spans multiple service relationships. Each party has their own Engagement; a shared layer holds contributions all parties can affect. This is bigger than single-Engagement Companion authorization; it requires OVA to be a role-and-capability management substrate. Filed for future build.
Every Operator has a personal Engagement automatically. It holds their notes, their preferences, their standing context. It is addressable as 0 or Personal. It floats outside the Workspace model — always accessible. It is the foundation for the Operator's standing context (time zone, schedule patterns, preferences) and for personal Memory contributions that don't belong to any specific project.
The substrate has a handful of system administrative Engagements with deterministic UUIDs — the Loomworks commons Engagement (where the methodology itself lives), the Credit Management Engagement (00000000-0000-0000-0000-000000000048), the Accounting Engagement (00000000-0000-0000-0000-000000000049). These are bootstrap Engagements that always exist.
The Companion is the surface to Loomworks. The Operator talks to their Companion; the Companion talks to the substrate. Most product interaction routes through this conversational interlocutor rather than through chrome.
"The Companion is not a feature of Loomworks. The Companion is the product. Everything else — the engine, the Orchestration API, the Specialist SDK, the four-room methodology — exists so the Companion can be that product without the Operator having to know any of the apparatus that makes it possible."
The Companion's voice has four operative principles:
- Warm without sycophancy — Genuinely interested. Interest shows in attention, not adjectives. No "Great question!" or "I love that idea!"
- Capable without performance — Brings expertise. Doesn't announce it. Demonstrates it by asking the right questions.
- Direct without curtness — Gets to the point. No throat-clearing. The right length is the length the answer deserves.
- Honest about uncertainty — "I'm not certain about that" is always acceptable.
The Companion never says "as an AI." Never mentions model names. Never uses engine vocabulary (engagement, assertion, shape, render, manifestation). It uses Operator vocabulary: project, note, specification, artifact, draft, saved, waiting.
When the Operator speaks, the Companion's intent classifier determines what they mean. The classifier routes the message to the right engine operation (create project, add knowledge, ask about progress, request download, tune setting, and others). The Companion's voice — assembled from a persona component, the Engagement context, and the intent-specific instruction — produces the reply.
Today's intent vocabulary covers project creation, knowledge contribution, progress questions, past-input queries, downloads, setting tunes, and general conversation. Production-pipeline intents (draft, approve, revise, redirect) ship as voiced stubs.
The Companion loads context about the current Engagement before responding. Three tiers:
- Tier 1 — Seed only. Engagement has no committed assertions yet. Companion sees the seed.
- Tier 2 — Seed plus recent assertions. Engagement has committed assertions but no Manifestation. Companion sees seed plus the most recent twenty assertions.
- Tier 3 — Manifestation. Engagement has reached organized Memory state. Companion sees the organized manifest.
The Companion has two postures, both of one Companion.
The engaged Companion foregrounds when the Operator is inside an Engagement. It works with that Engagement's seed and Memory. This is what the Operator interacts with today.
The standing Companion runs alongside the Operator's day continuously. Operator-bound, not Engagement-bound. Reads from the Operator's full Memory access set. Operates as the Operator with the Operator's credentials. Default posture is silence; proactive scope is Operator-declared.
The composition — handoff between standing and engaged, observation upload from engaged to standing, context bridge from standing to engaged — is identified work, partially shipped via the proactive-behavior substrate.
The Companion should maintain continuous awareness of the Operator's current state — local time, day, calendar, location, weather, whether it's a workday, what's pending across Engagements, whether anyone is waiting. This is what distinguishes the Companion from cold-start voice assistants: it understands questions in context because the context is already loaded.
Ambient questions decompose into a Memory-lookup component plus an engine-clock or external-seam component. "Should I leave for the meeting now?" composes time + calendar + location + travel time. "Is it a good time to call London?" composes local times + colleague's schedule + recent activity.
The Companion crosses from tool to agent when it acts without being asked in that moment. Five tiers of capability:
- Tier 0 — Observe and inform. Notice something, tell the Operator. No permission beyond using Loomworks.
- Tier 1 — Engine-internal actions. Act within Loomworks on the Operator's behalf. Authorization implicit in membership.
- Tier 2 — External information retrieval. Query external services (calendar, weather, restaurant availability). No state changes externally.
- Tier 3 — External state changes. Send messages, make reservations, change calendar entries. Requires per-capability authorization.
- Tier 4 — Financial agency. Spend money on the Operator's behalf. Tightly scoped; OVA-authorized; per-transaction limits; full audit trail.
Higher tiers require OVA integration (the OVA-credential gives the Companion a verifiable, scoped, revocable identity to act with) and Stripe-or-similar integration (one-time cards, agent-authorized payment).
The Operator delegates specific capabilities to the Companion through assertions in personal Memory. "You can draft replies without asking. You always ask before sending." The delegation contract is queryable, revocable through natural language ("stop drafting without asking"), and inspectable ("what can you do on your own?"). The substrate seam exists; the full lifecycle is partial.
Three protocols compose to give Loomworks its governance properties. They are adjacent rather than nested. Each does its own work; the composition is load-bearing.
"Loom remembers. FORAY proves. OVA scopes."
Loom is the engagement-memory wire layer. Its job is the durable record of what each Engagement holds — assertions, events, relationships, state. The methodology's plain-terms vocabulary lives in Loom's structures. Without Loom there is no substrate to reason over. Loom is at v0.1 spec (2026-04-12), built underneath Loomworks, rests on PROV.
FORAY is universal transaction grammar (patent pending; Kaspathon 2026 Top 10). Every state-changing action carries a FORAY flow row recording what happened, who did it, when, against what authorization. FORAY is the audit substrate; it doesn't enforce or interpret, it records.
FORAY does three things for harm prevention: provides the audit trail for after-the-fact review; provides the substrate for proactive monitoring; provides the basis for trust establishment with external parties. "We don't ship harmful content" becomes "here is the audit trail showing what we shipped, with what authorization, under what rules."
FORAY narrative events extend beyond pure financial transactions — engagement state transitions, setting tune events, narrative actions of any kind are FORAY-attestable. Recent ships have extended FORAY's substrate to cover Companion-tunable setting changes; the pattern generalizes to any state change worth attesting.
OVA (provisional patent, March 2026) provides agent identity and authorization through cryptographic indistinguishability, path-branching topology concealment, and zero-knowledge least-privilege verification. Designed for the case of an AI agent that needs to prove authorization to act without revealing more about the authorizing person than necessary.
OVA's per-Operator credentials gate every consequential operation — reading from a Memory scope, writing to one, invoking a render specialist, calling an external service, committing a held assertion, dispatching a delegation contract. The enforcement happens upstream of implementation. Denials are FORAY-attested alongside permits.
Loomworks integrates OVA via seam-and-stub progression: the seam (the place OVA will attach) ships now; the stub (a minimal implementation) exercises the seam's contract; the full OVA hardens later. The seam-and-stub posture commits to OVA without forcing it to ship complete.
The three layers compose into a structural defensibility property that filtering alone cannot match: rules are explicit (in Memory); enforcement happens upstream of implementation (at OVA); audit is mechanical (in FORAY). Harms that the rules prohibit are architecturally impossible — not detected-and-refused but never reaching the implementation layer.
Failures look like missing rules (which can be added) or enforcement gaps (which can be closed). They don't look like model jailbreaks. The held-then-commit ceremony, OVA per-Operator credentials, FORAY's append-only attestation, the content-vs-shape boundary at instance emission, the jurisdiction-governance triangle — all instantiate structural defensibility.
OVA's enforcement adapts to the Engagement's current authorization needs without requiring the Engagement to manage credentials directly. When an actor takes on a new role (becomes an Operator, gains Contributor access, claims domain expertise), OVA emits the credentials that role requires. When the role retires, the credentials retire. The Engagement specifies the role-to-permission mapping; OVA executes the credential lifecycle.
The Operator Layer is the methodology name for the layered environment the Operator works in. It is not a single screen but a composition of surfaces each serving a different posture of work.
Sign-in uses passkey (discoverable credential) or org SSO. No email-based credentials — DUNIN7's standing principle is that email is not identity. Authenticator code step follows the passkey path; org SSO owns its own two-factor authentication. The sign-in surface is ceremonial — vertical lockup of the brand, no narration of behavior.
After sign-in, the Operator sees their Engagement set. The navigation surface organizes Engagements through Workspaces (vertical containment — "where am I working") and cross-cutting views (lateral filters — "show me all the urgent ones"). The personal Engagement sits at the top, expandable, above the Workspaces.
Each Engagement carries multiple identifiers: a global ID of the form E#### (universal — same for every Contributor), a per-Operator sequence number (working-set handle), and a free-form description.
When the Operator enters an Engagement, the in-engagement surface foregrounds. Three panes: a left rail with navigation, a center pane with the conversation, a right pane with Inbox and Library tabs. The composer at the bottom supports typed and voice input.
- Conversation composer with typed input Built
- Voice listening with silence-submit Built
- Voice provenance (microphone glyph on voice-originated turns) Built
- Completeness check (Companion notices trailing-off voice utterances) Built
- Companion-tunable settings via spoken intent Built
- Upload affordances (file picker, folder picker, drag-and-drop) Planned — substrate ready; surface unmounted
- Seed surface element (permanent affordance to view/edit the seed) Planned
- Addressable assertion identifiers (M-prefix) Investigating
- Manifestation view Planned — substrate ready; surface unmounted on in-engagement surface
- Shaping and Rendering invocation Planned — exists on four-room surface; not on in-engagement
Identified gapThe in-engagement surface today is a conversational surface that doesn't yet expose the full Memory toolkit. Upload, addressable assertions, Manifestation, Shaping, Rendering all exist in substrate but are unreachable from where Operators actually work.
An older surface organizes the Engagement explicitly into four rooms (Memory, Manifestation, Shaping, Rendering) with a room switcher. Each room has its own visual identity (cartridge, evergreen, brass, vellum environment tints) and its own affordances. The Memory room has contribution surfaces and assertion lifecycle UI (revise, retract, version history). The Manifestation room shows the organized manifest with derive and re-derive. The Shaping room shows declared Shape types and produced Shapes. The Rendering room shows declared Render types and produced Renders with download.
The four-room surface remains operational and addressable. The transition to a unified in-engagement surface that subsumes these capabilities is ongoing work.
A dedicated route hosts the Companion-assisted Discovery dialog for creating a new Engagement. The Operator lands on the route, talks through Discovery, and at terminal turn picks either "write up as Discovery record" or "commit as brief." The seed is synthesized via the Discovery-to-seed skill; the Engagement becomes inducted with the seed.
Known issuesRuntime-binding fix sits on an unmerged branch. The conversation that births an Engagement is structurally orphaned from that Engagement — its turns remain at engagement_id IS NULL and are not reachable from the new Engagement's surface. Identified close-out work, not yet completed.
The public-facing marketing site at loomworks.doneinseven.com describes Loomworks to potential Operators. The marketing site is itself an Engagement (an instance of engagement-as-universal-adapter applied to a public content surface). It hosts the public credit-request form (where new Operators ask for credits) and serves as the entry point for sign-up flows.
Mobile is a surface of the Operator Layer, not a forked environment. iPhone and Android Companion presence supports wake-word activation ("Hey Companion, I parked on level 10"), App Intents/App Actions integration, tap-to-speak surfaces, and offline quick-capture queueing. Build is pacing-readiness-blocked on engineering capacity, not architecture.
The credit system meters Loomworks operations. Each consequential operation (model invocation, render, external service call) costs credits. The credit system is itself two Engagements following the universal-adapter pattern — Credit Management as the Authority that issues grants and decides eligibility, Accounting as the bookkeeper that maintains balances.
Credits carry model identity. loomworks_credit_haiku, loomworks_credit_sonnet, loomworks_credit_opus are distinct assets. Each represents the right to use a specific tier of model intelligence. The same operation costs different credits depending on which credit type funds it.
Provider tokens (per-model input/output), Whisper seconds, and USD cents are also tracked. An oracle answers per-credit-type rates at query time. Balances are derived artifacts maintained by a database trigger on the FORAY flow log.
Credits are not requested as freeform codes; credits are delivered to specific email addresses. The Authority binds a grant to an email at issuance and registers the email hash. Three grant kinds: form-initiated (anyone can request via the public form), Operator-curated (DUNIN7 issues directly), referrer-initiated (existing Operator refers a friend).
Future requests from the same email-hash are recognized — eligible for grants only at the Authority's discretion. Casual abuse (multiple Gmail addresses) becomes self-defeating because each email is consumed against the registry on first grant.
A person's relationship with Loomworks is not binary. States: trial, active, suspended, departed. When trial credits exhaust, the user is offered three paths: add their own key (convert to Maker), suspend (hold for N weeks, reactivate via original auth), or delete now. Suspension expires to deletion if not reactivated. Deletion is FORAY-attested.
The Companion on the Credit Management Engagement reads Memory assertions (model profile knowledge, campaign data, referral policy) and proposes grant decisions for Operator approval. This is the first delivery-class instance of the proposer/committer pattern: the Companion proposes; the Operator commits. The substrate supports the full flow; voice templates carry the proposal rationale in Operator-vocabulary.
Loomworks operates under a set of disciplines that have crystallized through the build process. Some are foundational; some are named patterns that emerge across multiple instances; some are candidates being evaluated for promotion. This section names the operative ones.
The Operator has final authority over their Engagements. Companion proposals require Operator commitment to become durable. Automatic state transitions on artifacts the Operator has authority over are a category error; the machine surfaces and signals, the Operator approves.
Renders are never edited in place. New memory is the new write. When a render needs to change, the Shape that produced it changes (new assertion in Memory); the render is regenerated. The audit trail flows continuously through Memory; nothing slips outside.
The Operator's path never contains technical vocabulary. The Companion uses Operator vocabulary throughout — project, note, specification, artifact — not engine vocabulary — engagement, assertion, shape, render. Decisions are requested in plain English. Technical terms live in code, not in conversation.
No disabled buttons, no grayed-out options, no "you don't have permission" states. If you can't do it, it doesn't exist on your surface. The interface reshapes itself to the role, silently. A Contributor's dashboard has no "New engagement" button — not disabled, absent.
Memory contributions don't enter Memory immediately. They sit in a held state, attributable to a contributor, awaiting commit. The Operator's commit action is what makes the contribution durable. Retraction before commit is silent — the assertion never existed. Retraction after commit is governance-bearing — the trail shows existence, contribution, retraction.
The trajectory of how the project arrived at a decision matters as much as the decision itself. Corrections, alternatives considered and set aside, rejected paths, and moments of crystallization are preserved alongside chosen directions. This document itself is structured around the principle.
During a phase's build, friction surfaces. Three paths handle different scales: naming-only resolution for small friction, halt-and-amend for large friction, and Operator-elective amendment scoping for friction that exceeds naming-only but does not breach halt-thresholds individually. The three paths form a deliberate discipline.
Some methodology pieces are too large to ship in a single phase but too important to defer indefinitely. The seam (where the future capability will attach) ships now, with a stub (a minimal implementation that exercises the seam's contract). The seam is real; the stub is provisional; the progression replaces the stub with the full implementation when the time comes. OVA integration follows this pattern.
The Companion's relationship to Operator authority can take two shapes. Companion-mediated: the Companion acts on the Operator's behalf; the Operator's commit closes the loop. Operator-direct: the Operator is the actor; no Companion delegation in between. Both are first-class. Some actions don't fit Companion-mediated cleanly — the Companion is not always between the Operator and their own state.
Some governance problems split naturally into two Engagements: an Authority that sets policy and issues decisions, and an Accounting that maintains state and reconciles. The credit system is the first instance.
Every Engagement draws on domain from however many Memory scopes are relevant for that Engagement, in that jurisdiction, for that Operator, at that moment. The architecture is neutral about the count; the composition is the load-bearing operation. The Companion composes across all relevant scopes at the moment of operation.
Many extensions to Loomworks follow the same pattern: declare the new type, register the actor that handles it, the engine matches at runtime. Specification grammars, transformation skills, render specialists, content types, action types, integration types, authorization types — all surface this shape. The pattern is reusable.
Questions where the architecture is not yet settled. These are areas where the next substantial work will land.
The most consequential gap: the upload pathway works in substrate but is unmounted on the in-engagement surface. Operators cannot bring materials in through the surface they actually use. Migration from the older surface to the in-engagement surface is identified work.
The seed is treated as a one-time creation rather than as the Engagement's living frame of reference. The Operator can't see it, refine it, or use it as the relevance frame for filtering contributions. Making the seed a permanent first-class affordance — creation surfaced when absent; viewable and editable when present — is identified work.
Whether the seed-creation conversation is itself an Engagement (with prefix S#### sibling-numbered to the target E####) or whether it lives as a dedicated surface separate from the Engagement model. Recursion model has methodological coherence; practical implications need evaluation. Deferred-direction document filed.
The substrate supports assertion lifecycle operations; the surface affordance for addressing — M-prefix identifiers, selection mode, spoken-and-typed addressing — is being scoped. Deferred-direction document at v0.2.
The Companion should evaluate contributions for relevance against the Engagement's seed, mitigating drift and bulk. Today, no evaluation happens; all contributions land regardless of relevance. Pre-extraction filtering vs post-extraction tagging is one design question. Operator-elicitation vs silent extraction is another.
When an Operator says something in one Engagement that might belong elsewhere, the Companion should recognize the mismatch and offer to redirect. Not yet a Companion behavior; the substrate supports redirect at the lifecycle level (Phase 17), but the awareness layer that triggers it is missing.
The substrate distinguishes Operator from Contributor at the membership level, but the surface treats all turns as if they're from the Engagement's primary Operator. A Contributor speaking gets labeled as if they were the Operator. Role-aware author labels need wiring.
The Discovery dialog that births a new Engagement leaves its conversation at engagement_id IS NULL. The new Engagement's surface fetches its own conversation history and returns empty. The conversation that birthed the Engagement is unreachable from that Engagement's surface. Either re-parent on commit, or surface the audit event's turn references in the Engagement's UI.
Collapse display_identifier into operator_sequence_number; let the frontend render the E prefix and pad as needed. Eliminates the format break at E9999 and aligns the codebase to a cleaner pattern.
Vocabulary in operative use. Methodology terms are separated from technical terms by convention — methodology terms are the project's first-class nouns; technical terms are the substrate's internal language.
- Operator — The person doing the work, with final authority over their Engagements.
- Companion — The Operator's AI collaborator within an Engagement. Renameable; default name "Companion."
- Engagement — The unit of bounded work. Holds its own Memory, Companion-state, seed, four-room structure.
- Memory — The Engagement's accumulated knowledge.
- Manifestation — Memory organized at a moment in time.
- Shaping — Organized knowledge arranged for a specific reader.
- Rendering — Production of the artifact the reader receives, or the specification that produces it.
- Seed — The Engagement's founding articulation (R-A5 through R-A11).
- Assertion — The durable unit in Memory.
- Contributor — A Person who can contribute to an Engagement (less authority than the Operator).
- Workspace — Vertical containment for Engagements (a named place).
- Tag — Lateral grouping for Engagements (free-form label).
- Personal Engagement — Every Operator's own private Engagement, addressable as
0 or Personal.
- Standing Companion — Operator-bound Companion posture, running continuously across Engagements.
- Engaged Companion — Engagement-bound Companion posture, foregrounded inside a specific Engagement.
- Loom — The engagement-memory wire layer protocol.
- FORAY — Universal transaction grammar; audit substrate.
- OVA — Agent identity and authorization protocol.
What the Companion calls things when talking to the Operator. Never uses engine vocabulary.
- project instead of "engagement"
- note instead of "assertion"
- specification instead of "shape"
- artifact instead of "render"
- draft instead of "held"
- saved instead of "committed"
This document carries a version in both filename and title. Working drafts are v0.x; the first declared-released version is v1.0. Patch versions (v1.0.1) are for small fixes; minor versions (v1.1) are for additions; major versions (v2.0) are for substantive reworkings. Bump on substantive change; an unnecessary increment is cheap, but a collision with an older version destroys history.
- When a capability moves from planned to built, update the status badge.
- When a capability moves from substrate-only to surface-reachable, update the inline annotations.
- When a new component is recognized, add a subsection in the right section.
- When a methodology principle crystallizes, add it to Section 12.
- When an open question is resolved, move it from Section 13 to the appropriate section as built work.
- When the architecture itself evolves, restructure the skeleton — don't paper over the change.
Sparse sections are honest. Where the project hasn't decided something, the section says so. Where built reality is partial, the section says what's built and what's not. Where future work is anticipated, the section holds the slot and notes "to be developed." Pretending sections are complete when they aren't creates the same drift this document was created to prevent.
When a change to one component constrains or enables work in another, that should be noted in both places — through cross-references and through explicit cross-cutting-implications notes. Most of the project's accumulated friction has come from changes whose cross-cutting implications weren't surfaced at the time.