mosaicstack/stack
16
0
Fork 1
Code Issues 330 Pull Requests 12 Actions Packages Projects Releases 15 Wiki Activity

config.json master config registry: schema v1 (D3:O1 ruled, config-registry proposal) #1382

New Issue
Open
opened 2026-08-24 15:44:03 +00:00 by orch-01 · 0 comments
orch-01 commented 2026-08-24 15:44:03 +00:00
Contributor
Copy Link
Copy Source

Ruled D3:O1 by the operator on 2026-08-24 (program map decision record): approve the proposed config.json schema and file it upstream as the config-registry proposal's schema section. Source document: mosaic-brain docs/plans/2026-08-22_config-json-schema.md (stage S2 -> S3 with this issue).

Contract

~/.config/mosaic/config.json is the ONE user-updatable file in ~/.config/mosaic (operator ruling 2026-08-22): master base configuration dictating brain location and instance registry. Deny-wins carve-out: an upgrade never overwrites user content in this file (same contract as CONSTITUTION.md, credentials.json). The carve-out lands in the installer before the first consumer (S4 precondition).

Schema v1

{
  "$schema": "mosaic-config-v1",
  "mosaicHome": null,
  "brainHome": "~/.mosaic",
  "instances": {
    "gitea": {
      "mosaicstack": { "url": "https://git.mosaicstack.dev" }
    }
  },
  "fleet": {
    "socket": "mosaic-fleet"
  },
  "harnessConfig": {
    "pi":    { "agentDir": "~/.mosaic/config/pi/agent" },
    "claude": { "configDir": null, "secureStorageDir": "~/.mosaic/auth/claude" }
  }
}

All keys OPTIONAL; null/absent = framework default.

Key Type Consumer (S4) Replaces today
brainHome path launchers, fleet split, wrappers MOSAIC_BRAIN_HOME env-only plus ~/.mosaic existence probe
instances.gitea.<name>.url url git wrappers instance-to-host mapping hardcoded INSTANCE_URL tables
fleet.socket string seat-up, watchers, fleet-pulse MOSAIC_FLEET_SOCKET env / literals
harnessConfig.<h>.* path seat launchers MOSAIC_SEAT_CONFIG idiom, per-seat env

Resolution contract (must not drift)

  1. MOSAIC_<KEY>_OVERRIDE env always wins (operator one-shot, test hermeticity)
  2. config.json key
  3. Framework default (today's behavior, unchanged)

Validation: JSON parse at read; unknown top-level keys produce a loud warning, not an error (forward compat: newer framework reading older config); ~/ paths expand at read, never rewritten at write.

Deliberate exclusions

  • Credential values: never in this file; token resolution stays in seat slots.
  • Model/effort defaults: per-seat launch env, a seat property not a host property.
  • fleet.rosterPath: removed; roster location is owned by native brain-home routing.
  • mosaicHome: reserved, default null; no consumer exists.

Rule for growth: every key must name a consumer that exists at S4. No speculative keys.

Exit

S4: first consumer (launcher reads brainHome/instances). S5: retire the interim bridges once native routing lands.

Ruled D3:O1 by the operator on 2026-08-24 (program map decision record): approve the proposed config.json schema and file it upstream as the config-registry proposal's schema section. Source document: mosaic-brain docs/plans/2026-08-22_config-json-schema.md (stage S2 -> S3 with this issue). ## Contract `~/.config/mosaic/config.json` is the ONE user-updatable file in `~/.config/mosaic` (operator ruling 2026-08-22): master base configuration dictating brain location and instance registry. Deny-wins carve-out: an upgrade never overwrites user content in this file (same contract as CONSTITUTION.md, credentials.json). The carve-out lands in the installer before the first consumer (S4 precondition). ## Schema v1 ```json { "$schema": "mosaic-config-v1", "mosaicHome": null, "brainHome": "~/.mosaic", "instances": { "gitea": { "mosaicstack": { "url": "https://git.mosaicstack.dev" } } }, "fleet": { "socket": "mosaic-fleet" }, "harnessConfig": { "pi": { "agentDir": "~/.mosaic/config/pi/agent" }, "claude": { "configDir": null, "secureStorageDir": "~/.mosaic/auth/claude" } } } ``` All keys OPTIONAL; null/absent = framework default. | Key | Type | Consumer (S4) | Replaces today | |---|---|---|---| | `brainHome` | path | launchers, fleet split, wrappers | `MOSAIC_BRAIN_HOME` env-only plus `~/.mosaic` existence probe | | `instances.gitea.<name>.url` | url | git wrappers instance-to-host mapping | hardcoded INSTANCE_URL tables | | `fleet.socket` | string | seat-up, watchers, fleet-pulse | `MOSAIC_FLEET_SOCKET` env / literals | | `harnessConfig.<h>.*` | path | seat launchers | `MOSAIC_SEAT_CONFIG` idiom, per-seat env | ## Resolution contract (must not drift) 1. `MOSAIC_<KEY>_OVERRIDE` env always wins (operator one-shot, test hermeticity) 2. `config.json` key 3. Framework default (today's behavior, unchanged) Validation: JSON parse at read; unknown top-level keys produce a loud warning, not an error (forward compat: newer framework reading older config); `~/` paths expand at read, never rewritten at write. ## Deliberate exclusions - Credential values: never in this file; token resolution stays in seat slots. - Model/effort defaults: per-seat launch env, a seat property not a host property. - `fleet.rosterPath`: removed; roster location is owned by native brain-home routing. - `mosaicHome`: reserved, default null; no consumer exists. Rule for growth: every key must name a consumer that exists at S4. No speculative keys. ## Exit S4: first consumer (launcher reads brainHome/instances). S5: retire the interim bridges once native routing lands.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
bug
Defect in framework tooling or delivered code
 fleet-enhancement
Fleet-wide reliability/speed/cost improvements surfaced by the nightly enhance pass
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
code-be-01 (Mosaic fleet seat code-be-01) code-be-02 (Mosaic fleet seat code-be-02) code-infra-01 (Mosaic fleet seat code-infra-01) fargo fred gate-merge-01 (Mosaic fleet seat gate-merge-01) happy jason.woltje (Jason Woltje) merge-gate ops-01 (Mosaic fleet seat ops-01) ops-02 (Mosaic fleet seat ops-02) ops-03 (Mosaic fleet seat ops-03) ops-ci-01 (Mosaic fleet seat ops-ci-01) ops-deploy-01 (Mosaic fleet seat ops-deploy-01) pepper rev-code-01 rev-code-02 rev-security-01 rev-security-02 rev-security-03 (Mosaic fleet seat rev-security-03) sanity scooby (Scooby) scrappy shaggy tiny velma veronica (Mosaic fleet seat veronica) vision woodpecker
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: mosaicstack/stack#1382