# Embeddable-Marketplace SDK + Docs — Loop Automation Plan

Status: **HISTORICAL / EXECUTED 2026-06-09** (Loops 0–5 built on branch `feat/marketplace-sdk`, local only).
Decisions locked 2026-06-09.

> Current-state note: this plan is retained as implementation history. The live
> full surface is now 84 instructions, `@tetsuo-ai/marketplace-sdk` is 0.6.0
> locally, and the package README is the current SDK status surface.

> Historical execution summary: `packages/sdk-ts` = `@tetsuo-ai/marketplace-sdk` v0.1.0 (publish-ready).
> Codama-generated `@solana/kit` client (77 instructions at that time) + facade wrapping **75/77**
> instructions (the 2 unwrapped — `claim_task` fail-closed, `complete_task_private` ZK — are
> intentional). **98 tests green: 89 structural + 9 REAL on-chain e2e** (register, create-listing,
> hire→settle, manual-validation, dispute→resolve, bonds) that execute the compiled program in
> litesvm via kit txs and assert decoded on-chain state (revert-sensitivity proven). tsc clean,
> tsup builds ESM/CJS+dts, drift gate in sync, TypeDoc reference (0 errors), compiled example +
> quickstart, drift-watchdog CI, **`npm audit` 0 vulnerabilities**. Commits `b10b603` (Loop 0) →
> `4d552b3`. Nothing pushed/merged/deployed.

- **Location:** a monorepo package **`packages/sdk-ts`** inside `agenc-protocol` (next to
  `packages/protocol`, which already ships the canonical IDL). Docs as `packages/sdk-docs`
  (or a generated SDK section inside `agenc-docs`).
- **Approach:** **Codama-generated core** (targets `@solana/kit`) + a **thin hand-written
  facade** for embeddable ergonomics. Never edit generated files.
- **Core principle:** **the IDL is the single source of truth.** Every loop's gate is
  "regenerate from the IDL → diff/coverage → `tsc` → tests." This is why co-location wins:
  one repo, one CI, IDL always fresh.

Pinned tool versions (live npm, 2026-06-09 — re-pin before building): `codama@1.7.0`,
`@codama/nodes-from-anchor@1.5.0`, `@codama/renderers-js@2.2.0`, `@solana/kit@6.9.0`,
`litesvm@1.1.0`, `tsup@8.5.1`, `typedoc@0.28.x`, `vitest@4.x`. Program IDL:
`artifacts/anchor/idl/agenc_coordination.json` (77 instructions at that time, 38 accounts, 287 errors,
program `HJsZ53Zb27b8QMRbQpuDngE44AdwCGxvEZr61Zmxw1xK`).

> Stack note: Codama's JS renderer targets **`@solana/kit`** (web3.js v2). The existing
> published `@tetsuo-ai/sdk` v1.4.0 is `@coral-xyz/anchor` + web3.js **v1** — a different
> stack. This new package does **not** reuse that code; it is the modern marketplace client.

---

## Target layout

```
agenc-protocol/
  packages/
    protocol/            # existing — @tetsuo-ai/protocol, ships the IDL
    sdk-ts/              # NEW — @tetsuo-ai/marketplace-sdk (@solana/kit)
      src/
        generated/       # Codama output — AUTOGENERATED, never hand-edit
        facade/          # hand-written ergonomic layer (createTask, hire, postBond, …)
        index.ts
      tests/             # vitest + litesvm
      codama.js          # codegen config
      package.json       # tsup build; @solana/kit as peerDependency
    sdk-docs/            # NEW — TypeDoc reference + guides + compiled examples
  scripts/
    sdk-generate.mjs     # IDL -> src/generated/ (Codama), then prettier
    sdk-coverage.mjs     # facade-vs-IDL flow diff (work queue + gate)
    sdk-drift-check.mjs  # regen to temp + `git diff --exit-code`
```

---

## Codegen pipeline (the spine)

`scripts/sdk-generate.mjs` (programmatic Codama):

```
createFromRoot(rootNodeFromAnchor(idl))     // @codama/nodes-from-anchor
  .accept(renderVisitor('packages/sdk-ts/src/generated'))   // @codama/renderers-js
```

- `npm run sdk:generate` → regenerates `src/generated/` from the IDL, then prettier.
- `npm run sdk:drift` → regenerate to a temp dir, `git diff --exit-code` vs committed
  `src/generated/`. Non-empty diff = "SDK is stale vs the program." This generalizes the
  existing `scripts/check-canary-idl.mjs` surface check.
- Commit `src/generated/` (reviewable, diffable, powers the gate).

---

## The series of loops

Each loop is **scoped, idempotent, commit-as-you-go, with a machine-checkable gate**.
Run interactively via `/loop` (short phases) or headless `claude -p --bare` + the Claude
Agent SDK in CI for durable runs. Copy-pasteable loop prompts below.

### Loop 0 — Scaffold + codegen smoke test  *(one-time; do interactively)*
Stand up `packages/sdk-ts`; write `sdk-generate.mjs`; run it against the IDL.
**Smoke check (important):** Anchor 0.32.1 emits a newer IDL — confirm Codama handles all
77 instructions / 134 types from this historical cut cleanly; defined types / generics / zero-copy accounts may need
Codama visitors or overrides. **Gate:** `tsc --noEmit` over `generated/` passes and the
client exports a builder for every one of the then-current 77 instructions.

### Loop 1 — Drift gate + IDL-sync wiring
Wire `sdk-drift-check.mjs` + `npm run sdk:check`; add a CI job that runs on any change to
`programs/` or the IDL. **Gate:** clean regen yields zero diff; CI job green.

### Loop 2 — Facade loop  *(self-paced; the workhorse)*
Per embeddable flow, hand-write the facade (`createTask`, `claimTask`, `submitResult`,
`hireFromListing`, `postCompletionBond`, `resolveDispute` **with bond accounts**,
`reclaimCompletionBond`, …) on top of generated builders + PDA helpers; each gets a litesvm
integration test. **Gate + self-termination:** loop ends itself when `sdk-coverage` reports
the target facade flow-list complete AND `tsc`+`vitest` are green.

`/loop` prompt:
```
/loop Build the next un-built facade method in packages/sdk-ts. Source of truth is the
generated client in src/generated/ and the IDL. For each: write the facade wrapper + PDA
helpers, a litesvm test asserting real on-chain effect, run `npm run -w sdk-ts test` and
`tsc --noEmit`, commit. Stop when `node scripts/sdk-coverage.mjs` reports 0 missing flows.
LOCAL ONLY — never push/deploy.
```

### Loop 3 — Reference docs
TypeDoc over `src/index.ts` with `--validation (notExported,invalidLink,notDocumented)
--treatWarningsAsErrors --useTsLinkResolution`; emit Markdown into `sdk-docs`; add an
IDL reference table via Codama-as-reader. **Gate:** zero broken `{@link}`, docs build green.

### Loop 4 — Guides / examples  *(LLM prose, hard-gated)*
Quickstarts + the full embeddable example (create listing → hire → post bond → submit/accept
**or** dispute → resolve-with-bonds → reclaim) as **real compiled `.ts` files** embedded via
region markers. **Gate:** every example compiles (`tsc`) and runs under litesvm; TypeDoc
link-check passes. **LLM writes prose only — never the reference layer**; ground generation
in the actual `.d.ts`/IDL, compile every snippet (mitigates API hallucination).

### Loop 5 — Drift watchdog  *(recurring CI)*
On any IDL change: re-run `sdk:generate` + `sdk:drift` + coverage + TypeDoc validation;
fail CI / open a PR if stale. This keeps the SDK + docs correct as the protocol evolves.

---

## Orchestration mechanics (from the research)

- **Custom subagents** (`.claude/agents/*.md`) — one per loop, each in its own isolated
  context window. This is the main defense against context exhaustion on a long build.
  (Subagents cannot nest — orchestrate from the main thread.)
- **Hooks** (`.claude/settings.json`) as the deterministic gates: `PostToolUse` matcher
  `Edit|Write` runs `tsc --noEmit` + the package vitest and **exit 2** to block on failure;
  a `Stop` hook runs the full build + `sdk:drift` + coverage and blocks the stop until green.
- **`/goal "<command exits 0>"`** for completion conditions — but the condition must be a
  command whose exit code Claude **surfaces in the transcript** (the evaluator can't run
  commands itself), and the orchestrator should re-verify.
- **Driving it:** `/loop` for interactive phases (note: session-scoped, hard-expires at
  7 days, max 50 tasks). For durable/unattended runs use **headless `claude -p --bare` +
  `@anthropic-ai/claude-agent-sdk` in GitHub Actions** (cloud "Routines" can't see local
  files). Budget: from **2026-06-15** Agent-SDK/headless usage draws from a separate credit
  pool on subscription plans.

---

## Decision-independent quick wins (can do immediately, outside the loop)

1. **The published `@tetsuo-ai/sdk` v1.4.0 is broken against the live program** —
   `resolveDispute`/`expireDispute` don't pass the now-required completion-bond accounts
   (protocol `bf1222f`). Patch `agenc-sdk/src/disputes.ts` + a revert-sensitive litesvm test.
   (Separate repo; independent of the new package.)
2. **Regenerate that SDK's stale error snapshot** (230 → 287 errors) via
   `AGENC_IDL_PATH=… npm run errors:generate`.