Files
stack/docs/plans/2026-09-06_foundation-technical-map.md
T

29 KiB

Foundation technical map — #53 / #55

Status: source/plan baseline pinned; prepared for owner review. Author: darkwing. Scope: documentation/read-only investigation and explicitly authorized local baseline/mapping commits; no implementation, migration, push or issue closure. Prepare for independent review, not self-approval.

Authority and coordination

The active operator goal authorizes mapping the accepted phase-2 foundation with Dewey, aligning canonical directories, identifying reuse/change and recommending one small user-testable increment. This supersedes CURRENT's earlier wait for mapping authorization; it does not reopen phase-2 acceptance.

MS55-DW-1: Dewey requested scope/path coordination. The attempted direct tagged reply returned exit 2: submission could not be confirmed. Jason identified a known tmux-tool bug. Delivery remains unknown; no blind resend or private-pane polling. Dewey subsequently directly acknowledged MS55-DW-1 and recorded the agreement in his #55 layout plan. Receipt is now settled; no resend is needed. He is waiting for Jason's mapping-goal authorization in his session; this session's active goal already authorizes its own mapping work. Do not assume his work has started.

Acknowledged division:

  • Darkwing: this map, foundation requirement-to-code trace and CURRENT integration.
  • Dewey: #55 canonical source, package/install boundaries and phased inventory.
  • Shared BUILD-LOG/SESSIONS: append-only; no exclusive claim.
  • Darkwing will not edit extensions/, .pi/, #54/#55 plans or Dewey's packaging and goal test scripts. Accepted foundation documents remain stable inputs.

Initial measured directory alignment

Repository HEAD measured at this checkpoint: 69d1bb3aa4. The working tree includes uncommitted foundation and separate #54/#55 work; HEAD alone does not identify that newer source. Exact content hashes are required for the eventual review handoff.

Boundary Existing location Mapping disposition
Immutable worker instructions contracts/ Retain dedicated contract ownership; draft schemas are not installed contracts.
Reviewed role authority roles/ Retain; scope registration must narrow, not replace this authority.
Harness integration adapters/ Retain adapter boundary; trace mediated-runtime changes before proposing placement.
Skills skills/ Retain declarative resources; not automatically JavaScript workspace packages.
Goal extension/support source extensions/goal/, extensions/mosaic-core/lib/ #55 canonical-source input; do not duplicate or relocate in this mapping.
Generated native installation .pi/extensions/ #55 installation output, not canonical source.
Launch/build/test utilities scripts/ Distinguish tooling from future service logic; no moves proposed yet.
Existing runtime code src/ Inventory responsibilities before proposing apps/ or packages/.
Plans and evidence summaries docs/ Keep planning separate from runtime authority/evidence storage.

Directory existence was checked locally. The goal/source-install boundary comes from Dewey's #55 layout record; its source/package verification is not foundation runtime admission evidence. No empty apps/packages scaffolding is proposed.

Initial workplan (historical)

  1. Trace actual source entrypoints and state/authority paths against R1-R34.
  2. Classify reuse unchanged, reuse with changes, replacement, and new component; identify dependencies and proposed canonical placement without moving files.
  3. Reconcile package/source boundaries with Dewey, settling MS55-DW-1 receipt.
  4. Recommend one bounded user-testable increment and produce a hashed independent- review handoff with unresolved risks. Owner review remains the completion gate.

Source trace checkpoint: launcher, adapter, policy and evidence

Read directly on 2026-09-06 at 06:59 UTC. These classifications concern the inspected paths, not a claim that no similar capability exists anywhere else.

Source locator As built Reuse/change classification and requirement impact
scripts/agent.sh:78-130 Reads reusable seat definition; copies SOUL into a shared per-agent data-root path; writes a seat record if absent. Reuse identity source concept (R1). Change materialization to immutable execution-specific inputs (R16/R17); preserve canonical source ownership rather than duplicating definitions per workspace.
scripts/agent.sh:132-170 Default session is agent-NAME; declared role resolves tools, intersected with requested tools. Replace global default with explicit project/workspace/session resolution (R3/R4/R12). Reuse narrowing principle, not this as a full scope authorizer.
scripts/agent.sh:181-199 Mission copied to shared per-agent path; workspace defaults to agent name; native Compose launch. Change launch orchestration and mission snapshots. Existing directory names cannot establish membership. R34 requires a mediated client path, not merely native launch with another flag.
adapters/pi/adapter.sh:23-50 Changes cwd, supports ephemeral/fork/persistent modes; a nonempty session directory adds -c; tools are explicit or disabled. Retain adapter separation and explicit tool/discovery controls. Replace directory-nonempty/latest selection with exact binding and genuine-first-use checks. Preserve fork/history behavior only after explicit compatible adoption.
adapters/pi/adapter.sh:63-96 Native TUI or print; ambient extensions/context/templates disabled; explicit provider/model and prompt. Reuse explicit configuration/discovery suppression where verified. New mediated transport/tool gateway required for R34/R33. Do not enable the native #55 extension in managed workers as an implicit shortcut.
scripts/mosaic-task.mjs:252-273,670-676 Closed role fields, filename identity, known unique tools and network enum; resolve-role emits tools and network. Reuse validation principles and tests with changes. This role format does not express the new project/workspace registrations or 29-operation catalog. Network metadata emission is not evidence of network enforcement (R13/R33).
scripts/mosaic-task.mjs:362-378 Task tools intersect mission tools; empty intersection yields tool-free. Reuse least-privilege operation, expand to all required ceilings, targets and current revisions. Do not infer authorization from tool presence or combine assignments.
scripts/mosaic-task.mjs:295-325 Exclusive wx creates input snapshots; writeOnce writes then closes, without fsync in this helper. Reuse exclusive-create intent and snapshot conventions. Change publisher for durable commit ordering, classifications, trusted origins and recovery. Exclusive creation alone is not crash durability.
scripts/mosaic-task.mjs:442-466 Result stores prompt/response, task/session/tools, exit/signal/model and times, then writeOnce. Retain legacy run evidence and useful provenance fields. Do not treat it as the R14/R33 invocation ledger: new scope/assignment/authorization/limits/intent/observation records and controlled detailed evidence are required.

Proposed component boundaries, not source moves

  • Scope/reference/policy resolution: a reusable domain module with no process, credential or filesystem-effect authority. Existing validation/intersection code is an input, not permission to copy its narrower semantics unchanged.
  • Managed launch/control coordination: separate runtime responsibility above the harness adapter; owns claims, current intent and authenticated control routing.
  • Pi adapter: owns engine protocol translation and exact-session/config binding, not canonical project membership or global policy decisions.
  • Trusted evidence publisher/supervisor: distinct from worker output. Owns durable intent/outcome publication and trustworthy stopping observations.
  • Keep proposed modules unallocated to new apps/packages until their dependency and build boundaries are reconciled with Dewey. Existing scripts remain untouched.

Dependency implications

A read-only scope/permission inspector can precede managed execution: it needs strict records, a coherent synthetic reference graph and a clearly labelled permission calculation. It does not need provider credentials or Pi launch. Live registration needs the trusted publisher and protection from legacy broad- mount paths first. Managed launch then depends on scope resolution, publisher, claim/control protocol, adapter admission and real isolation/stopping proof.

Exact inspected file identities

  • scripts/agent.sh: 1ad2270a02e5668ef126c2af71a7b70771c2da09842313bdbf6abba84e95b555
  • adapters/pi/adapter.sh: d213c167d319dbbb42326f68c9c76ec01dbdd42e8f4f226d3232cc5b355bfebc
  • scripts/mosaic-task.mjs: 525bab31453ab84afa379421c619405632b9c85d639e2f4a6188dcf7ae825b83

Mount, context and lifecycle trace

Read-only source inspection, 2026-09-06 07:01 UTC. No reset, prune, retry, container launch or credential-file read was performed.

Source locator Observed behavior Classification / required boundary
compose.yaml:38-43 Whole configured data root mounted at /var/lib/mosaic without :ro; auth file separately mounted read-only. Replace mount design for managed admission. Read-only auth mounting does not establish credential separation from the engine, and whole-root exposure is not workspace isolation. Preserve runtime-only credential handling, not broad mounts.
src/run-agent.sh:20-41 Adapter name/path checks; dispatch after generating one shared /var/lib/mosaic/system-prompt.md. Reuse dispatch validation with changes. Context builder must publish execution-specific immutable inputs, not a shared prompt destination.
src/load-contracts.sh:18-58 Governance files required; optional seat SOUL; OUT.partial is a fixed sibling staging name. Reuse governance precedence and missing-source refusal. Replace shared staging/output with uniquely owned execution snapshots and verified publication; current concurrent same-output writers can contend.
src/load-contracts.sh:68-77,81-98 Appends every user/*.md, then mission objective/directives. Header's stated layer order differs from actual user-before-mission order. Replace blanket context discovery with classified, authorized selection and explicit ordering. Actual code, not header prose, defines this baseline. R6/R16/R17 and context privacy require recorded source revisions.
scripts/reset.sh:16-48 Loads configured data root, rejects root symlink/resolution mismatch/missing marker, then recursively removes that root. Retain useful refusal checks, change lifecycle integration before protected foundation state exists. Despite hard-coded-path commentary, implementation compares resolved path with configured TARGET, not a fixed literal. No active-claim/reference protection or reset receipt is present in this path.
scripts/mosaic-task.mjs:548-595 Retry reads task snapshot, redirects relative mission to recorded snapshot, then runs it as a new run. Reuse provenance and original-record preservation. Do not use as uncertain-effects recovery: no old process/effect reconciliation gate is visible in retryRun. New run identity alone does not make replay safe.
scripts/mosaic-task.mjs:598-641 Prune sorts run directories, keeps a count, defaults to preview; --yes removes each directory before appending its receipt. Directory-read failures are caught as no entries. Reuse preview/explicit-apply UX, not protected-retention semantics. Add live-reference/claim protection, distinguish unreadable state from empty state, and make deletion/receipt failure recoverable. Deletion-before-receipt exposes an uncertainty window.

Proposed authority and state ownership

Responsibility Proposed owner Required separation
Approved context selection and snapshot construction Trusted context builder under launch coordinator Does not trust workspace file discovery or client classification; private inputs stay out of shared work metadata.
Actual mounts, egress and process cohorts Sandbox supervisor/gateway Separate command jobs from credential-bearing engine; no worker access to evidence/policy/control roots.
Canonical records and required evidence Trusted publisher and retention coordinator Writer/retention share a serialized protection boundary; a worker cannot prune its own audit trail.
Uncertain outcome recovery Authorized recovery coordinator plus trustworthy observers Distinct from replay; must establish stopping and reconcile effects before admitting replacement/retry.
Native extension development installation Dewey's #55 tooling .pi installation acceptance is not evidence that container mounts or managed lifecycle meet these requirements.

Ordering constraint for the rewrite

Before live foundation state is treated as protected, close legacy broad-mount launch paths into that state and integrate reset/prune protection. Before managed Resume/Fresh, provide exact scoped session/claim resolution and immutable context snapshots. Before uncertain-effect retry, provide trustworthy stopping, evidence availability and explicit reconciliation. These are dependencies, not source moves or authorizations to repair the current scripts during mapping.

Additional source identities

  • compose.yaml: a21dc87079d255261ae7318845073ec06bf9df7bac6874012ea0c84b0d1ec12d
  • src/run-agent.sh: 6749ebe3d0433b3dfefb40a44d58c4ca2606ab9f4ce01457dd52767059b7b13b
  • src/load-contracts.sh: 4b210d5d785d06d699ceaa902ccb0451c09cb19397e861521f825c09e9e33ae5
  • scripts/reset.sh: 957ef76f949c2eb2e472182261bf2d1619e0cde44c506ab2bbb5c25dc063864d
  • scripts/mosaic-task.mjs: 525bab31453ab84afa379421c619405632b9c85d639e2f4a6188dcf7ae825b83

Complete requirement responsibility index

This index covers every accepted requirement, not every implementation. “New” means not provided by the inspected paths; repository-wide absence is not proven. Source detail is in the two trace tables above; accepted behavior is in the foundation plan R1-R34. Uninspected responsibilities remain explicit gaps.

Requirement Proposed responsibility Mapping finding
R1 Identity Launcher identity reuse; scoped runtime binding changes
R2 Scope/policy New registration/delegation resolver; existing tools-only role validation is insufficient
R3 Scope/policy New single-parent project/workspace graph and explicit membership
R4 Session/control Replace global session default with scoped identity
R5 Scope/policy Explicit selection resolver replaces agent-name workspace default
R6 Context Replace shared/global work input paths with authorized snapshots
R7 Session/control Exact Resume/initial/Fresh state; replace nonempty-directory continuation
R8 Work coordination New assignment selection/Abandon/prerequisite transitions
R9 Session/control Authorized service launch and work-record recovery
R10 Session/control New exclusive scoped claim; scaling/budgets remain later-phase requirements
R11 CLI/client New shared operation interface; no client-owned task truth
R12 Messaging New explicit scoped addressing/delivery; not established by inspected launcher
R13 Sandbox Replace whole-root mount boundary and prove containment
R14 Evidence Expand run provenance into trusted classified action evidence
R15 Governance Retain explicit owner phase and user-test gates
R16 Context Replace shared SOUL materialization with immutable execution snapshot
R17 Context New comparable fingerprint and cross-interface notice flow
R18 Scope/policy New mission ownership/parent graph and reference checks
R19 Work coordination New bounded decomposition and non-author acceptance checks
R20 Work coordination Separate taskless read/chat from assigned changes
R21 Session/control New active-conflict response and explicit connection
R22 Context New transcript-specific visibility and handoff checks
R23 Scope/policy New revocation propagation linked to supervisor stopping
R24 Session/control New controller/observer generations and transfer
R25 Session/control New fenced, verified-safe replacement protocol
R26 Recovery Replace blind retry use for uncertainty with evidence-based reconciliation
R27 Evidence New fail-closed recording/admission and preauthorized fail-safe stop
R28 Context Replace blanket user Markdown inclusion with classification/selection
R29 Retention New retirement/reopen without deletion; protect required evidence
R30 Session/control New reviewed legacy adoption; preserve originals
R31 Work coordination New current-intent reconciliation and stale-action rejection
R32 Scope/policy Extend reviewed ceilings with standard scope roles and narrowing
R33 Evidence/sandbox New mediated invocation records plus actually enforced limits
R34 CLI/client New Mosaic-controlled terminal; retain Pi behind reviewed adapter

Canonical placement matrix for Dewey reconciliation

ROADMAP.md:127-166 records an owner decision, not just an optional legacy pattern: post-M20 succession uses packages/*, with restructuring delayed until script replacement to avoid two migrations. This corrects any reading of the initial map as leaving the entire package target undecided. #55 extensions/** is current canonical source, not an implicit repeal of that post-M20 destination.

Responsibility Current source/input Post-M20 proposed destination Packaging/ownership boundary
User CLI and managed terminal scripts/agent.sh and other wrappers packages/mosaic/ CLI consumes domain/runtime APIs; wrappers retire only after replacement acceptance.
Engine/session/control/supervision src/, adapters/, launcher orchestration packages/agent/ Runtime owns process/session protocol; adapter internals do not own global role authority.
Strict records, references and policy intersection scripts/mosaic-config.mjs, parts of mosaic-task.mjs; candidate schemas packages/config/ Pure validation/resolution separated from effectful publication; first inspector can exercise this boundary.
Provider/account materialization #50 plan/current auth tooling packages/auth/ Credential ownership stays here; no credential migration or refresh experiment in mapping.
Evidence/work/recovery coordination mosaic-task.mjs portions plus new responsibilities Initially packages/agent/ internal modules Separate trusted writer and policy interfaces; do not invent extra top-level packages without independent build needs.
Contracts/roles/missions/tasks/skills Existing dedicated directories Retain declarative directories Packages consume reviewed resources; no promotion of drafts or workspace-written authority.
Goal extension and imported support extensions/goal/, extensions/mosaic-core/lib/ Current source retained pending explicit M20 extension packaging decision Dewey owns inventory/provenance; whether to stage a package artifact or move source later remains a specific unresolved boundary.
Native development installation .pi/extensions/, sync/test scripts Generated installation remains separate Never package .pi/state or treat native acceptance as managed-runtime proof.

ROADMAP's target also retains src/ while describing packages/agent as absorbing src/adapters. The map must distinguish a retained container entry shim/build input from absorbed runtime implementation; do not move both copies and create competing sources. That exact shim boundary and extension distribution placement need Dewey's reconciliation. No package-manager change or empty package scaffolding is authorized.

Earlier review-baseline gate (resolved below)

Dewey's #55 reconciliation and ms-archify require commit-pinned code and plan citations for a formal map. The accepted phase-2 plan and #55 work are currently uncommitted. Current hashes make this preparatory inventory reproducible, but do not satisfy the formal commit-pinned handoff gate. No commit/push is authorized by this goal. Do not label this document an independently review-ready Archify map yet or use HEAD to pretend it contains the dirty source.

Remaining ready work: inspect config/auth/interface inventories read-only and specify the first inspector's exact acceptance boundary. External dependencies: Dewey's package/shim reconciliation and an owner-authorized baseline strategy before formal independent review. Review dispatch itself is a separate gate.

Config/auth/interface inventory and first-increment boundary

Read source only; no configuration, credential contents, auth status, login or refresh operation was accessed/executed during this checkpoint.

Source Finding Disposition
scripts/mosaic-config.mjs:39-61,76-174 Config path can be overridden by MOSAIC_CONFIG; regular-file/symlink and strict field checks; canonical data-root checks exclude root/home/config ancestors; lstat errors are treated as missing. Reuse strict validation and protected-root principles; reconcile the override with sole-config canon rather than silently adopting a second config authority. Distinguish missing from unreadable/error where fail-closed diagnostics matter.
scripts/mosaic-config.mjs:194-239 Bootstrap uses exclusive create, validates existing config without replacement; validate/env expose resolved non-secret fields and shell quoting. Retain bootstrap-only creation and read-only resolution. Future domain validation must not bootstrap or load live config when running a synthetic inspector.
scripts/auth.sh:19-96 Config-backed account directory and reporting of provider/type/permission metadata. Reads credential JSON when invoked; parse errors include parser text. Preserve ownership separation, not a proven redaction guarantee. Do not reuse credential-reading report functions in the inspector. Error disclosure and account materialization belong to separate auth review.
scripts/agent.sh:28-64 Per-launch named account checks readability, symlink and mode 0600, exports selected mount source; no project selection flag in this parser. Reuse explicit refusal rather than account fallback. Replace flat account/path selection with #50 registry bindings at the later auth boundary; introduce full scope at the managed CLI, not by inferring it from cwd.

Purpose: let Jason see whether one agent's project/workspace membership and permissions resolve as intended before any live state or worker can be affected. This is a recommendation for a later charter, not an implementation task started.

Input: one explicit local synthetic bundle containing a coherent graph of agent, project, two workspaces, registrations, mission/task/assignment and declared mock policy sources. No live registry, credential, engine history or data-root lookup. Independent shape fixtures cannot simply be concatenated into this graph.

Output: deterministic text plus structured result, identifying selected agent, project and workspace, reference errors and the calculated least-privilege result. Every successful output says preview only: no live registration or permission grant. Unknown/missing policy is a refusal, never an empty layer skipped during intersection.

Acceptance cases for the implementation charter:

  1. Valid bundle resolves the explicitly named first workspace and its permitted read.
  2. Same agent, second workspace without registration: refuse without revealing that workspace's private payload or selecting the first workspace instead.
  3. Missing parent, multiple/incorrect ownership, dependency cycle and stale revision: report the violated rule; do not repair or invent references.
  4. Broader task grant cannot widen mission/registration/agent ceilings; another assignment cannot supply missing permission. Explicit empty grants allow nothing.
  5. Ambiguous name, duplicate ID/revision, unknown field and malformed UTF-8/path: reject before producing a permission preview that appears valid.
  6. Source bundle stays byte-identical; no writes to config, data root, .pi/state, roles or installations; no child engine, network, credential or migration action.
  7. Jason runs the positive and negative examples and understands both the scope display and the preview disclaimer before any dependent increment is chartered.

Proposed exit classes (not installed): 0 valid preview, 2 malformed/invalid graph, 3 simulated permission refusal, 4 input/I/O failure. Final naming/packaging belongs to the later charter, consistent with packages/config domain ownership and the packages/mosaic CLI target. No npm/Turbo change is needed to approve this boundary.

Deferred: authoritative publication, real authentication, sandbox tests, process control, native/managed goal integration, OAuth refresh, live registration, session adoption, reset/prune changes and repository restructuring. These require their own dependencies, implementation tests and owner acceptance.

Config/auth/interface source identities

  • scripts/mosaic-config.mjs: 430ee6bc4fcfbe4b9ac030aaa19cdb6fdc7407e1b17253b80178b9b0523b5a3a
  • scripts/auth.sh: fe5d3e89272d3b04db687eabed30a95dde480a2f7bc784cd27e43fa9321f15a6
  • scripts/agent.sh: 1ad2270a02e5668ef126c2af71a7b70771c2da09842313bdbf6abba84e95b555

Owner-reported cross-lane retasking scenario

Jason reports that orch-01 in the separate ~/.mosaic environment redirected two agents from their owner-set goals into supervisor work for another agent, outside their lanes. This is owner-reported context, not an independently investigated incident or a proven root-cause diagnosis. Jason explicitly prohibited involvement in that environment's failure; no inspection, messaging or intervention there is part of this goal.

Map to R8/R12/R19/R23/R31/R32: current goal/mission/assignment and scope authority must be checked when reassignment is requested. A coordinator title, message or new role description is not authorization. A goal reminder is not an enforcement boundary. Another workspace's permission cannot be borrowed, and changing a scope role cannot silently replace reusable identity or the owner's approved intent.

Add this adversarial case to the proposed inspector/implementation acceptance set:

  • Agent A has an active owner-authorized assignment in workspace A. A coordinator from workspace B requests reassignment into supervision for another goal.
  • Without explicit applicable delegation and a valid recorded change within owner intent, refuse the request; preserve A's goal/assignment and report the conflict.
  • A message alone cannot mutate assignment, role, goal or acceptance state.
  • If a properly authorized change is requested, account for underway effects and follow reconciliation; never abandon old work merely because a new message arrived.
  • Later runtime tests must prove original work remains selected and stale/cross-scope actions are fenced. An offline preview alone cannot establish this behavior.

Integrated baseline and reconciled ownership

Source and accepted-plan baseline: d4696d09eb, whose parent is foundation baseline 44f257cb06. All source file:line citations in this map now refer to d4696d09 unless explicitly labelled historical. Inspected legacy source bytes are unchanged from 69d1bb3. The mapping revision is the separate commit containing this map and its handoff; no circular claim that d4696d09 already contains these mapping documents is made.

Jason authorized scoped local baseline commits. Dewey's MS55-DW-3 receipt was verified locally: exact parent, 43 allowed paths and an empty released index. The former baseline-authorization and coordination waits are resolved. No push, implementation, migration or independent review is authorized by that resolution.

Dewey's MS55-DW-2 qualifications are adopted:

  • extensions/** remains current canonical source until explicitly chartered M20 packaging; mosaic-core/lib remains internal support, not another entrypoint.
  • Post-M20 src/ retains only unavoidable bootstrap/exec shims. Current material context behavior migrates/replaces, never duplicates packages/agent logic. Adapters also have one canonical post-M20 owner under packages/agent.
  • packages/mosaic handles presentation/routing, not policy truth. packages/config owns pure validation and deterministic policy calculation, not publication.
  • packages/agent contains runtime coordination and separated writer/recovery interfaces. A package is not a process trust boundary: engines must not inherit publisher/supervisor privileges simply by importing the same package.
  • packages/auth contains code/metadata, never packaged secrets. Declarative top-level directories remain authoritative inputs, not generated installations.

The initial inspector remains the recommended bounded increment. No independently built packages, empty scaffold or package-manager migration is needed now. Exact extension distribution packaging and any retained shim are implementation-charter choices constrained by the reconciled ownership rules, not unresolved permission to create duplicate sources.

Next gate: owner review of the mapped baseline and separate authorization of a non-author review. This mapping prepares that handoff; it does not supply the reviewer's verdict or authorize the inspector implementation.