m2-market/specs/001-market-first-wedge/research.md

Research — 001-market-first-wedge (Phase 0)

All NEEDS CLARIFICATION items from Technical Context resolved below. Sources: CONCEPT.md v0.2, context/SYSTEM-MAP.md (verified 2026-07-01), live probes 2026-07-02, operator steer (README §open-forks edit 2026-07-02), Constitution v1.0.0.

R1. Ledger substrate

• Decision: standalone m2-ledger — FastAPI + SQLite (WAL), single-writer Coolify app on the coolify network, X-API-Key auth (same pattern as memory-api). Ledger API kept strictly separable from storage (repository layer) so a future migration into extended m2-gpt billing — including the operator's noted crypto-ledger direction — is a backend swap, not an API break.
• Rationale: operator confirmed standalone-now (README steer); m2-gpt gateway already meters tokens/tenants, so the ledger federates (reads identity, later maybe settlement) rather than duplicating; SQLite is constitution-VII-simple and one service is the only sanctioned new component.
• Alternatives considered: extend m2-gpt billing (rejected for v1: couples marketplace release cadence to gateway deploys; revisit post-wedge per operator note); Forgejo-as-ledger (rejected: git is the audit trail, not a transactional store — race conditions on concurrent installs).

R2. Registry of record (fedlearn absence)

• Decision: create Forgejo repo m2/market-registry: listings/<listing_id>/ directories (listing.json + evidence/ + bundle ref), Solution bundles attached as repo releases (<listing_id>-v<semver>), review = PR, veto = labels (veto, approved), merge = published. Daily ledger snapshots commit to audit/ in the same repo.
• Rationale: verified 2026-07-02 that m2/m2-core does not exist and the fedlearn herd has not started (fleet busy on m2-gpt work) — blocking on it would stall the wedge. Listings are commercial artifacts; a dedicated registry keeps the free-core/paid-market boundary physical (constitution IV). Forgejo is live today (forgejo skill available for API access).
• Alternatives considered: wait for m2/m2-core (rejected: unlanded dependency); listings inside m2-core (rejected: erodes commons boundary); one-repo-per-listing (rejected for v1: heavier to administer; releases-in-one-repo suffices at this scale).
• Integration seam: when fedlearn's curation pipeline lands, its commercialize disposition emits a PR against m2/market-registry — the registry's PR/veto protocol is the frozen interface (contracts/registry-layout.md).

R3. Schema freeze order (manifest superset problem)

• Decision: freeze solution.schema.json v1 in this repo now, embedding the manifest-shaped core fields observed in the fedlearn plan's submission example (schema_version, applicability{image_classes,roles,tool_requirements}, tenant_scope, evidence[], content_hash, scrub status) plus commercial fields (price, seller, license, revenue_split). File a coordination note to the fedlearn effort: its final manifest must remain field-compatible with this core, or a v1→v2 schema migration is planned at integration.
• Rationale: the spec (FR-001) requires a frozen contract; fedlearn's own schema task (their Task 1.1) is unexecuted, so "superset of the manifest" is only satisfiable by freezing our side and coordinating. Frozen interfaces are exactly how the constitution says to sequence around unlanded rails.
• Alternatives considered: wait for fedlearn's freeze (rejected: unbounded wait); schema-less v1 (rejected: FR-001/FR-002 are explicit).

R4. Catalog partition mechanics

• Decision: market:catalog as a memory-api partition (agent_id-style namespace, same BGE-M3 hybrid path as fedlearn:core-index was designed for). Writes go only through m2-market-indexer, which reads merged listings from m2/market-registry; reindex rebuilds the partition from scratch (constitution II rebuildability). Tenant filtering applied at query time via listing tenant_scope payload field.
• Rationale: SYSTEM-MAP confirms memory-api live with partition model; one more partition is the assembly move. Known risk: the memory-api split-brain (two Coolify stacks) — fedlearn task T13 was to resolve it; until then the indexer targets the stack behind memory.machinemachine.ai and reindex makes recovery cheap.
• Alternatives considered: separate Qdrant collection managed directly (rejected: bypasses memory-api auth + embedding pipeline); SQL full-text in the ledger DB (rejected: no semantic match, Scout needs embeddings).

R5. Install/apply path without m2-core-sync

• Decision: define AdapterProtocol (contracts/apply-adapter.md): plan(bundle) → changeset, apply(changeset) → result, verify(bundle) → bool, rollback(changeset), all idempotent. v1 ships the local adapter: bundle = tarball release containing solution.json + payload/ + recipe.yaml (declarative file placements + post-install checks) applied into the operator's home/agent volume, with a state file (~/.m2-market/state.json) mirroring the fedlearn state.json design. m2core_sync adapter is a stub that errors with "fedlearn rails not landed".
• Rationale: runtime-sync is the only universal path fleet-wide, but its implementation (m2-core-sync) doesn't exist yet; the adapter seam lets the wedge close SC-001 with the local adapter and swap in m2-core-sync without touching CLI or Store.
• Alternatives considered: implement m2-core-sync ourselves (rejected: forks fedlearn's in-plan work, constitution's "consume, not fork"); flatpak-style backend from cargstore (rejected: desktop-app-shaped, not agent-bundle-shaped).

R6. Scout host (operator: "explore")

• Decision: DEFERRED to a time-boxed spike (task in Phase 2; output scout/SPIKE.md) comparing: (a) standalone supervised watcher (hermes-gateway pattern), (b) Hermes plugin, (c) herdr plugin/hook. Spike evaluates: access to structured run summaries, opt-in policy enforcement point, on-box summarization cost, notification surface, and update/rollout story on both image classes. Scout v0 implements the spike's winner on ONE canary.
• Rationale: operator explicitly marked this fork "explore"; Scout is P3/last-sequenced so the spike doesn't block the wedge gate (SC-001).

R7. Store surface

• Decision: fork-branch m2-store on cargstore; keep Electron+React shell, replace Flatpak catalog source with market:catalog (via memory-api HTTP) and add an install backend that shells to m2-market install (one code path for FR-005 semantics). Auth: desktop's existing m2-gpt-issued credentials pattern (operator steer) — the store reads the same key material provisioned on the desktop, never stores its own secrets.
• Rationale: operator steer ("MVP electron app... credentials from m2-gpt"); reusing the CLI for install guarantees ledger semantics are implemented once.
• Alternatives considered: web-first (deferred per steer); re-implementing install in the store's Node side (rejected: two implementations of debit→grant→apply invites drift).

R8. Identity & wallets

• Decision: operator_id = the operator identity from fleet.json tenancy (e.g. m2bd, sdjs-operator); wallets keyed by operator_id in m2-ledger; machine→operator resolution shipped as a small mapping in the CLI config (provisioned, not guessed). Starter grants issued via an admin-authenticated ledger endpoint (default 100 cr — UNCONFIRMED default, flagged).
• Rationale: fleet.json is the existing identity substrate (constitution I); v1 needs no new auth system — API keys per service, operator mapping per machine.

R9. Testing strategy

• Decision: pytest for ledger (property-style tests on derived balances: balance == fold(tx log) under generated tx sequences) and CLI (integration against a real local ledger instance + recorded Forgejo/memory-api fixtures); a scripted quickstart (quickstart.md) as the canary E2E gate; schema validation tests for all seeded bundles.
• Rationale: SC-003/SC-004 are audit properties — property tests are the cheap way to hold them; canary E2E is the constitution-VI rollout gate.

Open coordination items (not blockers)

1. Coordination note → fedlearn effort: manifest/schema field-compat with frozen solution.schema.json v1 core (R3).
2. memory-api split-brain (fedlearn T13): until resolved, indexer pins the public endpoint; reindex is the recovery path (R4).
3. Operator confirmations outstanding: platform cut 10%, starter grant 100 cr (spec Assumptions; ledger ships them as config, not constants).