stack/docs/plans/2026-09-10_m20-increment1-charter.md

M20 packages/mosaic auth/provider/harness — increment 1 charter (#1499)

Status: DRAFT FOR OWNER APPROVAL. Baseline: commit 21461c8674 on refactor. Governing plan: docs/plans/2026-09-03_auth-provider-harness-registry.md (all ten gates owner-resolved 2026-09-10). Nothing in this charter authorizes implementation until Jason approves it.

User-visible outcome

A real packages/mosaic module exists with the registry's core schemas, validation, and a fail-closed CLI slice, proven by suites — the foundation every later increment (materializers, harness install, refresh service) builds on. Nothing user-facing in daily flows changes yet.

Increment 1 scope (allowed paths)

• packages/mosaic/ (new): package scaffolding, TypeScript config, and the auth/provider/harness domain module:
  • provider record schema (native + custom-endpoint kinds, allowInsecureTransport flag),
  • account metadata schema (split account.json; credential-file schema shape, not contents),
  • settings-profile schema (allowedAccounts, defaultAccounts, providers, models),
  • seat selection schema (per-execution semantics, fork-pin field),
  • harness manifest schema (id, executable, adapter, version range, materializers),
  • validation engine: unknown keys, ID regex ^[a-z0-9][a-z0-9._-]{0,63}$, path/name match, provider-kind-specific required fields, reference integrity (account under provider, profile references resolvable).
• packages/mosaic/src/cli/ (new): read-only registry validate + registry list subcommands operating on a --registry-root directory argument (default: configured dataRoot). No mutation commands in this increment.
• package.json, RELEASE-adjacent pin files: pi dependency moves to exactly 0.85.1 (type tests and offline fixtures updated accordingly; runtime image rebuild is out of scope).
• scripts/auth.sh: untouched in this increment (shim conversion is a later increment).
• Suites: packages/mosaic/tests/ with fixture-based negative/positive cases mirroring the plan's "Registry schemas" acceptance list.

Explicitly out of scope

No materializer, no auth.json/models.json generation, no OAuth login/refresh execution (the pi auth check driver is specified but not wired), no harness detect/install, no seat migration to agentVersion 2, no mosaic top-level CLI aliasing beyond the registry subcommands, no container image build/release, no deployment, no live credential use, no writes to ~/.pi or dataRoot at runtime (validate/list read only), no changes to existing suites' behavior.

Roles

• Author: Darkwing (or delegated to Rocko under a bounded task; charter amendment records any delegation).
• Independent reviewer: Filbert.
• Operator/acceptance: Jason.

Test obligations

• New package suites green: schema acceptance list from the plan (unknown keys, mismatch, symlink/traversal simulation at the validation layer, wrong perms representation, duplicate IDs, missing provider, unsupported credential type, allowInsecureTransport required for plain-http baseUrl).
• Existing suites remain green (config, task, release, conductor, auth, foundation, launcher fixtures).
• Node version pinned per repo canon; no network in tests (fixtures only).
• Secret non-disclosure: fixtures contain fake markers; suites assert they never appear in stdout/JSON output.

Rollback

Single-purpose commits on refactor; revert the increment commits to restore baseline. No data migrations, no runtime state written, so rollback is purely source-level.

Protected operations / boundaries

No credential reads or writes anywhere in this increment. Validation reads registry JSON from a supplied root; malformed input refuses with nonzero exit and no partial writes (there are no write paths at all).

Acceptance criteria

1. packages/mosaic typechecks and its suites pass covering the plan's registry-schema acceptance list.
2. registry validate exits 0 on a fully valid fixture tree and refuses each invalid fixture with a precise error, no stack-trace spew, no secret echo.
3. registry list prints providers/accounts/profiles without any credential-shaped fields.
4. Pi pin is exactly 0.85.1 and all dependent fixtures/tests updated.
5. Independent review APPROVED on the exact candidate; Jason accepts the charter completion before any increment 2 planning.

CI note

No CI workflow exists for this repo; suites run locally per canon. That gap is noted, not widened by this charter.