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

Feature Specification: M2 Marketplace — First Wedge

Feature Branch: 001-market-first-wedge

Created: 2026-07-02

Status: Draft

Input: User description: "M2 Marketplace first wedge: schemas, m2-ledger, commercialize curation, market:catalog + m2-market CLI, cargstore revival to M2 Store, 3-5 seeded Solutions, Solution Scout v0, one real paid install between two operators" (CONCEPT.md v0.2 §12)

User Scenarios & Testing (mandatory)

User Story 1 - Paid install via CLI (Priority: P1)

An operator (buyer) searches the catalog for a capability they need, inspects a listing's evidence and price, and installs it. The install debits their credit wallet, credits the seller (minus platform cut), grants a license, and applies the Solution bundle to their machine through the existing sync/apply path. This is the commercial loop's spine — every other story feeds it.

Why this priority: Without buy→debit→grant→apply working end-to-end, nothing else in the marketplace has meaning. It is independently valuable: even with zero storefront UI and zero Scout, two operators can transact via CLI.

Independent Test: On a machine with a funded wallet, run m2-market search <term>, m2-market show <listing>, m2-market install <listing>; verify ledger shows the debit and seller credit, a license grant exists, and the bundle's files/config are applied and invocable.

Acceptance Scenarios:

1. Given a listed Solution priced at 40 credits and a buyer wallet holding ≥40 credits, When the buyer runs m2-market install <listing-id>, Then the ledger records a debit of 40 from the buyer, a credit of 36 to the seller and 4 to the platform (10% cut), a license grant is recorded, and the bundle is applied idempotently to the buyer's machine.
2. Given a buyer wallet holding fewer credits than the listing price, When they attempt install, Then the install is refused before any apply happens and no ledger transaction or license grant is created.
3. Given a completed install, When the same install is re-run, Then the apply is idempotent (no duplicate debit; re-apply is safe or a no-op with the existing license).
4. Given an applied Solution, When the operator invokes its documented entrypoint, Then the packaged outcome executes on their machine.

---

User Story 2 - Publish a Solution with evidence (Priority: P1)

A builder packages a proven outcome (e.g. the mm-pdf branded-report generator) as a Solution: a manifest-superset bundle with price, seller, license, and provenance evidence. They submit it for listing; it passes the curation pipeline (scored PR, human veto) with the commercialize disposition and lands in the registry of record and the semantic catalog.

Why this priority: Supply side of the loop. Story 1 cannot demo without at least one real listing; seeding 3–5 Solutions from proven outcomes is part of this wedge.

Independent Test: Package one existing proven outcome, submit it, approve the listing PR, and verify it is retrievable via m2-market search with its evidence and price visible.

Acceptance Scenarios:

1. Given a valid Solution bundle with price and provenance, When the builder submits it for listing, Then a review PR is created carrying evidence, price, permissions, and rollback info, and the listing is NOT discoverable until the PR is merged.
2. Given a submitted listing missing provenance evidence, When it enters curation, Then it is rejected by validation before human review.
3. Given a merged listing, When any operator searches the catalog semantically, Then the listing is returned with name, summary, price, rating placeholder, and evidence summary.
4. Given tenant-derived work, When submission is attempted by anyone other than the owning operator, Then the submission is refused (tenant firewall).

---

User Story 3 - Credit wallets and starter grants (Priority: P2)

Each operator has a wallet. The platform issues starter grants to active operators so the economy can bootstrap. Balances derive from an append-only transaction log; a daily snapshot is committed to the registry host for audit.

Why this priority: Story 1 needs wallets to debit, but a minimal hardcoded grant would suffice for the very first transaction; full wallet lifecycle is its own increment.

Independent Test: Issue a starter grant to a fresh operator id; verify balance query returns the grant amount; verify the daily snapshot job writes a balance file into version control.

Acceptance Scenarios:

1. Given a new operator id, When a starter grant (default 100 cr) is issued, Then their balance reflects it and the grant appears as an append-only transaction with reason grant.
2. Given any sequence of transactions, When balances are queried, Then they equal the fold of the transaction log (no stored balance drifts from derived balance).
3. Given a day with ≥1 transaction, When the snapshot job runs, Then a balance snapshot is committed to the audit repo.

---

User Story 4 - M2 Store (cargstore revival) on canaries (Priority: P3)

An operator on a canary desktop opens the M2 Store app, browses the catalog rendered from market:catalog, opens a Solution page showing evidence, price, and permissions diff, and installs with one click — same ledger + apply path as the CLI.

Why this priority: The storefront makes the loop humane but the CLI already closes it. Canary-only (chris-m2o, gunnar-m2o) per the constitution's deployment principle.

Independent Test: On one canary desktop, open the store, find a seeded listing, click install, and verify the same post-conditions as Story 1's scenario 1.

Acceptance Scenarios:

1. Given the store app pointed at the live catalog, When it renders the front page, Then seeded listings appear with name, summary, category, price.
2. Given a Solution page, When the operator clicks Install, Then the identical debit→grant→apply sequence of Story 1 executes and the UI reports success/failure truthfully.
3. Given an install failure after debit, When the failure is detected, Then the operator sees a clear error and a compensating refund transaction is recorded.

---

User Story 5 - Solution Scout v0 on one canary (Priority: P3)

While an operator works, a per-desktop watcher summarizes session intent from structured lifecycle/run summaries (never raw keystrokes), matches it against tenant-allowed catalog listings, and — on a high-confidence hit — shows a non-blocking proposal with a deep link to the listing. Propose-only, opt-in, rate-limited.

Why this priority: Demand-side engine; valuable but the wedge's success criterion only requires discovery "via Scout or Hermes/CLI". Ships last, on one canary.

Independent Test: On an opted-in canary, run a session that resembles a seeded listing's intent; verify a proposal appears within the session with a working deep link, and that opting out or exceeding the daily rate cap suppresses proposals.

Acceptance Scenarios:

1. Given an opted-in desktop and a session whose summary semantically matches a listing above threshold, When the match fires, Then a non-blocking notification with the listing's name, rating, coverage, and price appears with an install deep link.
2. Given an opted-out desktop, When the same session runs, Then no session data leaves the machine and no proposal is shown.
3. Given N proposals already shown today (rate cap), When another match fires, Then it is suppressed.
4. Given a proposal, When the operator dismisses or accepts it, Then the outcome is recorded as listing-quality evidence (conversion signal).

---

Edge Cases

• Install interrupted between ledger debit and apply completion → apply must be resumable or a compensating refund recorded; never a paid-but-not-applied end state without a visible remediation path.
• Listing updated (new version) after purchase → existing license covers which versions? (v1: license covers the purchased major version; updates within it are free re-applies.)
• Seller delists a purchased Solution → existing licenses and installed bundles remain valid.
• Two installs of the same listing racing on one machine → second is a no-op under the existing idempotent apply semantics.
• Catalog index diverges from registry of record → registry wins; index must be rebuildable from it (constitution II).
• Buyer and seller are the same operator (self-purchase) → allowed but flagged; conversion signals from self-purchases are excluded from listing quality metrics.
• Scout matches against a listing the tenant may not see → must be impossible by construction: matching runs against tenant-allowed listings only.

Requirements (mandatory)

Functional Requirements

• FR-001: The system MUST define a frozen v1 solution.schema.json as a superset of the fedlearn manifest, adding at minimum: price, seller/operator id, license terms, and revenue-split fields.
• FR-002: The system MUST define a frozen v1 listing.schema.json covering catalog presentation: id, name, summary, category, keywords, price, seller, evidence references, rating/conversion placeholders, and install reference.
• FR-003: The system MUST provide an append-only credit ledger recording transactions {ts, from, to, amount, reason: install|payout|grant|route|earn, ref} with balances always derived from the log.
• FR-004: The ledger MUST authenticate API callers (per-key auth) and MUST commit a daily balance snapshot to the version-controlled audit location.
• FR-005: Installing a listing MUST atomically-in-effect: verify funds, debit the buyer, credit the seller minus the platform cut (default 10%, configurable), record a license grant, then trigger the existing sync/apply path; on apply failure a compensating refund transaction MUST be recorded.
• FR-006: The curation pipeline MUST support a third disposition commercialize alongside promote-to-core and reject/park, using the existing PR + human-veto flow, with a listing PR template requiring evidence, price, permissions, and rollback notes.
• FR-007: The system MUST index merged listings into a semantic catalog partition (market:catalog) searchable by meaning, scoped to tenant-allowed listings, and fully rebuildable from the registry of record.
• FR-008: The system MUST provide an m2-market CLI with at minimum search, show, and install commands, where install performs the FR-005 sequence.
• FR-009: Operators MUST have wallets keyed to operator identity (fleet tenancy model), and the platform MUST be able to issue starter grants (default 100 cr).
• FR-010: The storefront (M2 Store, evolved from cargstore) MUST render the catalog, show listing detail with evidence/price/permissions, and drive installs through the same ledger + apply path as the CLI; deployment is canary-only in this wedge.
• FR-011: The Solution Scout MUST run per-desktop, opt-in via desktop policy config, consume only structured session/run summaries (never raw keystrokes or raw client data), summarize on-box before any egress, match only tenant-allowed listings, be rate-limited (default: max 5 proposals/day), and be propose-only (install always requires a human click).
• FR-012: Accepted and dismissed Scout proposals MUST be recorded as listing quality evidence (proposal→install conversion).
• FR-013: At least 3 Solutions packaged from already-proven outcomes MUST be listed with real evidence (proposed set: mm-pdf branded-report generator, agent-scaffold workspace generator, competitor-scan report).
• FR-014: Install telemetry (who/when/machine/outcome) MUST land back in the memory system as pricing/quality evidence attached to the listing.
• FR-015: Tenant-derived work MUST be commercializable only when owner-initiated and doubly-scrubbed; submissions violating the tenant firewall MUST be rejected automatically.

Key Entities

• Solution: installable bundle — intent, agent behavior, tools, runtime refs, memory schema, permissions, deployment recipe, price, evidence. Conforms to solution.schema.json; versioned in the registry of record.
• Listing: the catalog-facing record of a Solution (or other inventory type) — presentation + commercial fields + evidence refs. Conforms to listing.schema.json; truth in the registry, indexed in market:catalog.
• Operator: human identity over N machines (fleet tenancy); may act as buyer, builder, seller, resource owner. Owns exactly one wallet in v1.
• Wallet / Transaction: operator's credit position, derived from append-only transactions {ts, from, to, amount, reason, ref}.
• License Grant: record tying an operator to a purchased listing version, checked by the install/apply path.
• Proposal: a Scout suggestion event — listing, confidence, shown/dismissed/accepted, feeding conversion metrics.

Success Criteria (mandatory)

Measurable Outcomes

• SC-001: One real paid install completes between two distinct operators (e.g. m2bd buys sdjs-operator's package): discovered via CLI/Hermes/Scout, bought with credits, applied via the standard path, ledger reflecting debit/credit/cut — the loop closes commercially once.
• SC-002: ≥3 Solutions listed with real provenance evidence, each passing curation review.
• SC-003: 100% of installs have a matching ledger transaction and license grant; zero applies without a recorded debit (audited from the daily snapshot).
• SC-004: Ledger balances recomputed from the transaction log match reported balances exactly at every daily snapshot.
• SC-005: An operator can go from m2-market search to an invocable installed Solution in under 10 minutes on a canary desktop.
• SC-006: Scout v0 on one canary produces ≥1 correct proposal (matching listing shown for a genuinely related session) with zero raw-input egress, honoring opt-in and rate caps.
• SC-007: Install telemetry from SC-001's install is queryable as evidence on the listing afterward.

Assumptions

Recorded per constitution: recommended defaults from CONCEPT.md §14 open forks are ASSUMED here and flagged until the operator confirms (also mirrored in .m2herd/overview.json open_questions):

• Ledger substrate (operator steer, README 2026-07-02): standalone m2-ledger service (SQLite, API-key auth) NOW; recorded future direction — it may evolve into a crypto-style ledger managed inside extended m2-gpt billing. v1 interfaces must not preclude that migration (keep ledger API separable from storage).
• Pricing v1 (operator steer): fixed price per install as the default; the operator notes that sometimes another m2o takes a job for a solution — service-style fulfillment pricing. v1 transacts fixed-price installs only, but listing.schema.json must not preclude a job/service fulfillment variant (reason codes route|earn already exist).
• Storefront path (operator steer): MVP Electron app (cargstore revival) that connects to Coolify and other platform parts using credentials issued via m2-gpt; web/ variant deferred.
• Scout host: OPEN — operator marked "explore solution" (§14.4). Plan phase must carry a short exploration spike (standalone supervised watcher vs Hermes plugin vs herdr plugin) before Scout implementation; Scout v0 remains last-sequenced so this does not block the wedge.
• First Solutions: mm-pdf, agent-scaffold, competitor-scan (§14.5 proposed).
• Economics: platform cut 10%, starter grant 100 cr, both configurable (§14.6 defaults).
• Dependency: fedlearn MVP rails (manifest schema, m2/m2-core registry, capture CLI, curation PR/veto, m2-core-sync apply, memory partitions) are in herd execution NOW and land before or during this wedge; where a rail is not yet landed, the plan phase must sequence around it or stub against its frozen interface.
• Payout to fiat/external money is out of scope; payouts are manually reconciled.
• Resource/Service inventory types are catalog-schema-ready but not transacted in this wedge; only Solutions are bought/sold.
• Public web marketplace, external payments, and public coin/exchange are out of scope.