René's URL Explorer Experiment


Title: PRD: Squad State — Typed StorageProvider Interface with Contract Conformance · Issue #481 · github/squad · GitHub

Open Graph Title: PRD: Squad State — Typed StorageProvider Interface with Contract Conformance · Issue #481 · github/squad

X Title: PRD: Squad State — Typed StorageProvider Interface with Contract Conformance · Issue #481 · github/squad

Description: Squad State: Typed Interface + MarkdownProvider Author: Dina Berry Date: 2026-03-22 Status: Draft — Awaiting Brady's Review Target Repository: bradygaster/squad (packages/squad-sdk/) Related: Full research document in PRD-squad-state.md ...

Open Graph Description: Squad State: Typed Interface + MarkdownProvider Author: Dina Berry Date: 2026-03-22 Status: Draft — Awaiting Brady's Review Target Repository: bradygaster/squad (packages/squad-sdk/) Related: Full ...

X Description: Squad State: Typed Interface + MarkdownProvider Author: Dina Berry Date: 2026-03-22 Status: Draft — Awaiting Brady's Review Target Repository: bradygaster/squad (packages/squad-sdk/) Related: F...

Opengraph URL: https://github.com/github/squad/issues/481

X: @github

direct link

Domain: github.com


Hey, it has json ld scripts:
{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"PRD: Squad State — Typed StorageProvider Interface with Contract Conformance","articleBody":"# Squad State: Typed Interface + MarkdownProvider\r\n\r\n**Author:** Dina Berry\r\n**Date:** 2026-03-22\r\n**Status:** Draft — Awaiting Brady's Review\r\n**Target Repository:** `bradygaster/squad` (`packages/squad-sdk/`)\r\n**Related:** Full research document in `PRD-squad-state.md`\r\n\r\n---\r\n\r\n## 1. Problem Statement\r\n\r\nThe Squad SDK has no centralized state management. Every module that reads or writes `.squad/` files does it independently — 129 read ops and 87 write ops scattered across 29 modules, all direct `fs` calls with no shared code, no abstraction, and no type safety.\r\n\r\n**What's broken:**\r\n- **6 separate directory scans** for the same `.squad/` tree (`LocalAgentSource`, `CharterCompiler`, `AgentLifecycleManager` (stale path!), `nap.ts`, `doctor.ts`, `export.ts` (wrong path!))\r\n- **Parsers are read-only** — markdown → typed objects works, but no serializers exist for the reverse\r\n- **CLI bypasses SDK for writes** — raw string concatenation instead of typed APIs\r\n- **Stringly-typed everywhere** — agent status duplicated 3×, routing tiers duplicated 4×, model tiers duplicated 3×, `WorkType` has a `| string` escape hatch that defeats the union\r\n\r\n**Why now:** The team has converged through three research sessions (2026-03-20 through 2026-03-22). The architecture is validated. Time to build.\r\n\r\n### Why a StorageProvider interface (two independent arguments)\r\n\r\n**POV #1 — Backend Flexibility:** The interface enables swapping storage backends (markdown, SQLite, GitHub API) without changing SDK code. Markdown is the default; others become mechanical implementations against the same contract.\r\n\r\n**POV #2 — Contract Conformance:** The interface defines a testable contract. A provider-agnostic conformance test suite validates that implementations behave correctly — catching bugs in the existing markdown provider (round-trip data loss, edge cases) even if no second backend is ever built. Value on day one.\r\n\r\nPOV #2 is arguably stronger: it delivers value immediately without requiring faith that a second backend will be needed.\r\n\r\n### Scope of this PRD\r\n\r\n**This PRD covers:** The `StorageProvider` typed interface and the `MarkdownStorageProvider` implementation (plus `InMemoryStorageProvider` for tests).\r\n\r\n**This PRD does NOT cover:** Implementation details for SQLite, GitHub API, or other non-filesystem providers. The interface is designed so they CAN be added later — that's a separate future PRD.\r\n\r\n---\r\n\r\n## 2. Goals & Success Metrics\r\n\r\n### Goals\r\n\r\n1. **Define the `StorageProvider` interface** — typed, async, collection-level CRUD with section-level operations\r\n2. **Ship `MarkdownStorageProvider`** — default implementation preserving all current `.squad/` behavior\r\n3. **Ship `InMemoryStorageProvider`** — for fast, deterministic, filesystem-free tests\r\n4. **Build `SquadState` as the typed facade** — one entry point, typed collections, Agent Handle pattern, no `as` casts\r\n5. **Establish conformance test suite** — provider-agnostic tests that validate any implementation\r\n\r\n### Success Metrics\r\n\r\n| Metric | Target |\r\n|--------|--------|\r\n| Direct `fs` calls in SDK | 0 outside MarkdownStorageProvider |\r\n| Directory scan locations | 1 (internal to MarkdownStorageProvider) |\r\n| SDK test execution time | \u003c2s for state tests (InMemory) |\r\n| Round-trip fidelity | 100% for all document types |\r\n| CLI write operations | 0 raw string surgery |\r\n\r\n### Non-Goals\r\n\r\n- Build non-filesystem providers (SQLite, GitHub API, etc.)\r\n- Replace git as the transport/sync mechanism\r\n- Abstract the communication layer (issues/PRs)\r\n- Break existing `.squad/` directory structure or formats\r\n\r\n---\r\n\r\n## 3. Key User Scenarios\r\n\r\n### Scenario 1: Read agent charter\r\n\r\n```typescript\r\n// BEFORE: bespoke fs + parsing per module\r\nconst raw = fs.readFileSync(path.join(squadRoot, '.squad', 'agents', name, 'charter.md'), 'utf-8');\r\nconst parsed = parseCharter(raw);\r\n\r\n// AFTER: typed handle — plain string in, typed API out\r\nconst mal = await state.agents.get('mal');   // AgentHandle — validates at runtime, throws NotFoundError\r\nconst charter = await mal.charter();          // Promise\u003cCharter> — fully typed, no casts\r\nconst learnings = await mal.history('learnings');  // Promise\u003cHistoryEntry[]>\r\nawait mal.appendHistory('learnings', entry);       // Promise\u003cvoid>\r\n```\r\n\r\n### Scenario 2: CLI appends a decision\r\n\r\n```typescript\r\n// BEFORE: raw string concatenation\r\nconst entry = `### ${timestamp}: ${title}\\n**By:** ${author}\\n\\n${body}\\n`;\r\nfs.writeFileSync(decisionsPath, existing + '\\n' + entry);\r\n\r\n// AFTER: typed API handles serialization\r\nawait state.decisions.addDecision({ title, by: 'Mal (Lead)', body, timestamp: new Date() });\r\n```\r\n\r\n### Scenario 3: Unit testing without filesystem\r\n\r\n```typescript\r\nconst store = new InMemoryStorageProvider();\r\nstore.seed({\r\n  agents: {\r\n    'test-agent': {\r\n      charter: { name: 'test-agent', role: 'Tester', status: 'active' },\r\n    },\r\n  },\r\n});\r\nconst state = new SquadState(store); // fast, deterministic, no cleanup\r\nconst agent = await state.agents.get('test-agent'); // AgentHandle — typed, no casts\r\n```\r\n\r\n---\r\n\r\n## 4. Scope\r\n\r\n### In Scope\r\n\r\n- `StorageProvider` interface definition (typed async CRUD at document + section level)\r\n- `MarkdownStorageProvider` — wraps current filesystem operations, owns markdown serialization\r\n- `InMemoryStorageProvider` — for tests\r\n- `SquadState` class — typed facade with collection-specific sub-interfaces\r\n- Shared `types.ts` — single source of truth for `AgentName`, `AgentStatus`, `HistorySection`, `ModelTier`, `RoutingTier`, `CollectionName`, domain types\r\n- Markdown serializers for all document types (charters, decisions, routing, team, history)\r\n- Conformance test suite — provider-agnostic, validates any `StorageProvider` implementation\r\n- Absorption of `history-shadow.ts` into `SquadState` as `agents.history` collection\r\n\r\n### Out of Scope\r\n\r\n- Non-filesystem provider implementations (SQLite, GitHub API, JSON — interface supports them, future PRD)\r\n- Communication layer abstraction (issues/PRs — separate concern)\r\n- Config schema unification (`SquadConfig` vs `SquadSDKConfig` — adjacent work)\r\n- Breaking changes to `.squad/` format\r\n\r\n---\r\n\r\n## 5. Approach\r\n\r\n### Architecture\r\n\r\n```\r\nSquadState (typed facade — typed collections, AgentHandle pattern, domain objects)\r\n  └── StorageProvider (interface — typed async CRUD, collection→entity mapping)\r\n       ├── MarkdownStorageProvider (default — reads/writes .squad/ files)\r\n       │    └── SquadFileSystem (file discovery, path resolution, caching)\r\n       └── InMemoryStorageProvider (for tests)\r\n```\r\n\r\n### Key Design Decisions\r\n\r\n**1. StorageProvider Interface — Type-Safe Collection-Entity Mapping**\r\n\r\nThe generic parameters on `read()` and `write()` are _linked_ to the collection name via `CollectionEntityMap`. The compiler prevents reading a `Charter` from the `'decisions'` collection — a class of bug that unconstrained generics silently permit.\r\n\r\n```typescript\r\n// Maps each collection to its entity type — the compiler enforces correct pairings\r\ninterface CollectionEntityMap {\r\n  agents: Charter;\r\n  decisions: Decision;\r\n  routing: RoutingConfig;\r\n  team: TeamConfig;\r\n  skills: SkillDefinition;\r\n  templates: Template;\r\n  log: LogEntry;\r\n  config: SquadConfig;\r\n}\r\n\r\ntype CollectionName = keyof CollectionEntityMap;\r\ntype CollectionEntity = CollectionEntityMap[CollectionName];\r\n\r\ninterface StorageProvider {\r\n  // Collection-level\r\n  list(collection: CollectionName): Promise\u003cstring[]>;\r\n\r\n  // Whole-document operations — collection name constrains entity type\r\n  read\u003cC extends CollectionName>(collection: C, id: string): Promise\u003cCollectionEntityMap[C]>;\r\n  write\u003cC extends CollectionName>(collection: C, id: string, entity: CollectionEntityMap[C]): Promise\u003cvoid>;\r\n  exists(collection: CollectionName, id: string): Promise\u003cboolean>;\r\n  delete(collection: CollectionName, id: string): Promise\u003cvoid>;\r\n\r\n  // Section-level operations (sections are string-typed at this layer;\r\n  // SquadState facade adds typed section names per collection)\r\n  readSection(collection: CollectionName, id: string, section: string): Promise\u003cunknown>;\r\n  appendToSection(collection: CollectionName, id: string, section: string, entry: SectionEntry): Promise\u003cvoid>;\r\n\r\n  // Lifecycle\r\n  initialize(): Promise\u003cvoid>;\r\n  dispose(): Promise\u003cvoid>;\r\n}\r\n```\r\n\r\n> **Design note (River):** The old `read\u003cT extends CollectionEntity>()` signature let callers request any entity type from any collection — `read\u003cCharter>('decisions', 'foo')` compiled but was always wrong. The `CollectionEntityMap` pattern (same one the SDK uses for `SquadEventPayloadMap`) makes invalid states unrepresentable.\r\n\r\n**2. SquadState — Agent Handle Pattern (No Branded Types, No Casts)**\r\n\r\nThe Agent Handle pattern eliminates branded types entirely. The old `AgentName = string & { __brand: 'AgentName' }` forced every call site into an `as AgentName` cast — a type system smell that means the design is wrong, not the caller. Instead, `state.agents.get()` accepts a plain `string`, validates at runtime, and returns a typed `AgentHandle`. Everything downstream is fully typed without casts.\r\n\r\n```typescript\r\ntype AgentStatus = 'active' | 'inactive' | 'retired';\r\ntype HistorySection = 'context' | 'learnings' | 'decisions' | 'patterns' | 'issues' | 'references';\r\ntype ModelTier = 'premium' | 'standard' | 'fast';\r\ntype RoutingTier = 'direct' | 'lightweight' | 'standard' | 'full';\r\n\r\n// The handle is the typed API surface for a single agent\r\ninterface AgentHandle {\r\n  readonly name: string;\r\n  charter(): Promise\u003cCharter>;\r\n  history(): Promise\u003cHistory>;\r\n  history(section: HistorySection): Promise\u003cHistoryEntry[]>;\r\n  appendHistory(section: HistorySection, entry: HistoryEntry): Promise\u003cvoid>;\r\n  status(): Promise\u003cAgentStatus>;\r\n}\r\n\r\n// The collection manages discovery and handle creation\r\ninterface AgentCollection {\r\n  list(): Promise\u003cstring[]>;\r\n  get(name: string): Promise\u003cAgentHandle>;    // validates name, throws NotFoundError\r\n  exists(name: string): Promise\u003cboolean>;\r\n}\r\n\r\ninterface DecisionCollection {\r\n  list(): Promise\u003cDecision[]>;\r\n  add(decision: Decision): Promise\u003cvoid>;\r\n}\r\n\r\nclass SquadState {\r\n  readonly agents: AgentCollection;\r\n  readonly team: TeamCollection;\r\n  readonly routing: RoutingCollection;\r\n  readonly decisions: DecisionCollection;\r\n  readonly skills: SkillCollection;\r\n\r\n  constructor(provider: StorageProvider) { /* wires typed collections to provider */ }\r\n}\r\n```\r\n\r\n> **Why no branded AgentName:** The SDK's existing `AgentRef` is `string`. The codebase uses plain strings for agent names everywhere. A branded type adds friction (casts at every boundary) without adding safety — the real validation is \"does this agent exist?\" which is a runtime concern handled by `AgentHandle`. The handle IS the proof of validity.\r\n\r\n**3. Serialization = Provider's Responsibility**\r\n\r\nThe interface deals in typed objects only. `MarkdownProvider` serializes to/from markdown. A future `SQLiteProvider` would map to/from SQL rows. The caller never sees raw strings or format-specific content.\r\n\r\n**4. Granularity = File + Section Level**\r\n\r\nOperations work at two levels: whole-document (get/put a Charter) and section (append to History.Learnings). This maps to how `.squad/` files use `##` headers as logical sections. Non-filesystem backends can map sections to table columns, API endpoints, or document subsections.\r\n\r\n**5. history-shadow.ts Absorbed Into SquadState**\r\n\r\nThe existing `history-shadow.ts` proved the pattern (typed CRUD, section-level operations, markdown as storage). It does NOT remain standalone — it becomes `state.agents.history`. One interface, no parallel APIs.\r\n\r\n**6. Inbox/Drop-Box = Provider-Specific**\r\n\r\nThe decisions inbox pattern (write to inbox files, Scribe merges) is a `MarkdownProvider` implementation detail, NOT part of the `StorageProvider` interface. The interface exposes `addDecision(decision: Decision): Promise\u003cvoid>`. How the provider handles concurrent writes is its own concern.\r\n\r\n**7. Async-Only**\r\n\r\nAll `StorageProvider` methods return Promises. No sync variant. JavaScript is async-first, and the interface must support remote backends.\r\n\r\n### Conformance Test Suite (Phase 0 Foundation)\r\n\r\nThe conformance suite is the specification made executable. Written as `function runConformanceSuite(provider: StorageProvider)`, invoked once per implementation.\r\n\r\n**Core behaviors tested:**\r\n- `write()` → `read()` returns identical typed object (round-trip)\r\n- `write()` → `exists()` returns `true`; before `write()` → returns `false`\r\n- `list()` returns all written documents, no extras\r\n- `appendToSection()` preserves existing content, adds new content\r\n- `delete()` → `exists()` returns `false`; `read()` throws\r\n- `write()` twice → `read()` returns second write (overwrite semantics)\r\n- Empty collection → `list()` returns `[]`, not error\r\n- `initialize()` → `dispose()` lifecycle is clean\r\n\r\n**Why this matters:** If both `InMemoryStorageProvider` and `MarkdownStorageProvider` pass the same suite, the contract is verified from two independent implementations. Neither can cheat in a way the other also cheats.\r\n\r\n### Competitive Analysis (Brief)\r\n\r\n| Pattern | LangGraph | CrewAI | AutoGen | Semantic Kernel | **Squad** |\r\n|---------|-----------|--------|---------|-----------------|-----------|\r\n| Pluggable storage interface | ✅ | ❌ | Partial | ✅ | **✅** |\r\n| Human-readable state | ❌ | ❌ | ❌ | ❌ | **✅** |\r\n| Git-diffable state | ❌ | ❌ | ❌ | ❌ | **✅** |\r\n| Document-level operations | ❌ | ❌ | ❌ | ❌ | **✅** |\r\n| Contract conformance tests | ❌ | ❌ | ❌ | ❌ | **✅** |\r\n| State is the product | ❌ | ❌ | ❌ | ❌ | **✅** |\r\n\r\n**Squad's unique position:** Every other framework stores opaque blobs or embeddings. Squad stores semantically rich, human-editable documents. The closest analog is an ORM, not a checkpoint system.\r\n\r\n### Implementation Phases\r\n\r\n**Phase 0: Conformance Suite + Tests (1 week)**\r\n- Round-trip fidelity tests for existing parsers\r\n- Conformance test suite (`runConformanceSuite(provider)`) alongside interface\r\n- Run against `InMemoryStorageProvider` as smoke test\r\n- **Deliverable:** Living spec + round-trip tests (red — serializers don't exist yet)\r\n\r\n**Phase 1: Interface + Two Providers (2 weeks)**\r\n- `StorageProvider` interface + shared `types.ts` (single source of truth)\r\n- `MarkdownStorageProvider` with `SquadFileSystem` internals\r\n- `InMemoryStorageProvider`\r\n- Both pass conformance suite\r\n- **Deliverable:** Interface, two providers, all tests green\r\n\r\n**Phase 2: SquadState Facade (2 weeks)**\r\n- Typed facade with collection-specific sub-interfaces\r\n- Wire into existing SDK modules (replace scattered `fs` calls)\r\n- **Deliverable:** `SquadState` class, SDK modules refactored\r\n\r\n**Phase 3: CLI Migration (1–2 weeks)**\r\n- Replace all CLI raw string surgery with `SquadState` APIs\r\n- **Deliverable:** CLI fully migrated, zero raw string surgery\r\n\r\n---\r\n\r\n## 6. Risks\r\n\r\n| Risk | Likelihood | Impact | Mitigation |\r\n|------|-----------|--------|------------|\r\n| Interface shape is wrong | Medium | High | Let MarkdownProvider drive the shape; two implementations validate. Refine before shipping. |\r\n| Round-trip fidelity is harder than expected | High | Medium | Phase 0 catches it early. Known hard cases: YAML frontmatter, inline HTML, comments. |\r\n| Migration breaks CLI behavior | Medium | High | Conformance suite + incremental migration (one module at a time). |\r\n| Scope creep into non-filesystem providers | Medium | Medium | Hard boundary: this PRD covers interface + MarkdownProvider only. Other providers = separate PRD. |\r\n\r\n### Dependencies\r\n\r\n- Node.js 18+ (already met), existing parsers in `markdown-migration.ts` and `doc-sync.ts`, TypeScript strict mode (enabled), no new npm packages\r\n\r\n### Edge Cases (Interface-Level)\r\n\r\nThese are contracts the interface defines; implementation details are provider-specific:\r\n\r\n| Edge Case | Interface Contract |\r\n|-----------|-------------------|\r\n| Concurrent appends | `appendToSection()` is the provider's responsibility. MarkdownProvider uses atomic file ops; others use transactions. |\r\n| Atomicity | `write()` is all-or-nothing. A failed write must not leave partial state. |\r\n| Error types | Discriminated error union — see Error Taxonomy below. |\r\n| Change detection | Not in v1 interface. A future `subscribe(collection, callback)` is a natural extension. |\r\n| Human editability | `supportsExternalModification` capability flag. Filesystem providers support it; closed providers can cache aggressively. |\r\n| Ordering | Append-only collections carry timestamps. `list()` returns chronological order. |\r\n\r\n### Error Taxonomy\r\n\r\nErrors use a `kind` discriminant for exhaustive `switch` matching, following the SDK's existing discriminated union patterns (see `CoordinatorRoutingPayload`, `AgentMilestonePayload`). Each error extends a base `StorageError` class:\r\n\r\n```typescript\r\ntype StorageErrorKind = 'not-found' | 'parse-error' | 'write-conflict' | 'provider-error';\r\n\r\nclass StorageError extends Error {\r\n  abstract readonly kind: StorageErrorKind;\r\n}\r\n\r\nclass NotFoundError extends StorageError {\r\n  readonly kind = 'not-found' as const;\r\n  constructor(\r\n    readonly collection: CollectionName,\r\n    readonly id: string,\r\n  ) { super(`${collection}/${id} not found`); }\r\n}\r\n\r\nclass ParseError extends StorageError {\r\n  readonly kind = 'parse-error' as const;\r\n  constructor(\r\n    readonly collection: CollectionName,\r\n    readonly id: string,\r\n    readonly cause: Error,\r\n  ) { super(`Failed to parse ${collection}/${id}`); }\r\n}\r\n\r\nclass WriteConflictError extends StorageError {\r\n  readonly kind = 'write-conflict' as const;\r\n  constructor(\r\n    readonly collection: CollectionName,\r\n    readonly id: string,\r\n  ) { super(`Write conflict on ${collection}/${id}`); }\r\n}\r\n\r\nclass ProviderError extends StorageError {\r\n  readonly kind = 'provider-error' as const;\r\n  constructor(\r\n    message: string,\r\n    readonly cause?: Error,\r\n  ) { super(message); }\r\n}\r\n\r\n// Exhaustive handling — compiler catches missing cases\r\nfunction handleError(err: StorageError): never {\r\n  switch (err.kind) {\r\n    case 'not-found':    throw new UserFacingError('Resource not found');\r\n    case 'parse-error':  throw new UserFacingError('Corrupt data');\r\n    case 'write-conflict': /* retry logic */\r\n    case 'provider-error': /* escalate */\r\n  }\r\n}\r\n```\r\n\r\n> **Design note (River):** Classes + discriminant is the right hybrid here. Classes give you `instanceof` checks and `.message`/`.stack` for logging. The `kind` discriminant gives you exhaustive `switch` matching. This aligns with the SDK's existing `ErrorFactory` pattern while adding the exhaustiveness guarantee that catch blocks currently lack.\r\n\r\n---\r\n\r\n## 7. Architecture Review — River (TypeScript Architect)\r\n\r\n### Interface Shape Assessment\r\n\r\n**CollectionEntityMap is the critical addition.** The original `read\u003cT extends CollectionEntity>()` had an unconstrained generic — the `T` bore no relationship to the `collection` parameter. This is the TypeScript equivalent of `void*`: it compiles, it's wrong, and you won't know until runtime. The mapped type `CollectionEntityMap` makes the compiler enforce valid collection-entity pairings.\r\n\r\n**AgentHandle eliminates the branded type cascade.** Branded types (`string & { __brand: 'AgentName' }`) are the right tool when you need to distinguish two string-shaped values at the type level (e.g., `UserId` vs `SessionId` in the same function signature). They're the _wrong_ tool when there's only one string type and the real validation is \"does this thing exist?\" — that's a runtime concern. The Agent Handle pattern moves validation to `get()` and makes the returned handle the proof of validity. Everything downstream is typed without casts.\r\n\r\n**The `readSection` return type is intentionally `unknown` at the StorageProvider layer.** Section typing is the SquadState facade's job — it knows that `agents` have `HistorySection` subsections. The provider just stores and retrieves opaque section data. This keeps the provider interface simple and pushes domain knowledge to the right layer.\r\n\r\n### Generic Patterns\r\n\r\n**Well-used:** `CollectionEntityMap[C]` — conditional type inference from mapped types. Same pattern as the SDK's `SquadEventPayloadMap`.\r\n\r\n**Recommendation — overloaded `history()` on AgentHandle:** The `history()` method has two signatures (full history vs. single section). TypeScript function overloads handle this cleanly:\r\n\r\n```typescript\r\ninterface AgentHandle {\r\n  history(): Promise\u003cHistory>;\r\n  history(section: HistorySection): Promise\u003cHistoryEntry[]>;\r\n}\r\n```\r\n\r\nThis is better than two separate methods (`getHistory` / `getHistorySection`) because the mental model is \"history, optionally scoped.\"\r\n\r\n### Where to Use Discriminated Unions\r\n\r\nThe PRD already uses literal union types (`AgentStatus`, `HistorySection`, `ModelTier`, `RoutingTier`). These are correct — they're simple enumerations, not variants with different shapes.\r\n\r\n**Where discriminated unions add value:**\r\n\r\n1. **Error taxonomy** — Done above with `StorageErrorKind`.\r\n2. **Provider capabilities** — If providers need to declare what they support:\r\n   ```typescript\r\n   type ProviderCapability =\r\n     | { readonly kind: 'external-modification'; supported: true }\r\n     | { readonly kind: 'transactions'; supported: boolean; maxBatchSize?: number }\r\n     | { readonly kind: 'watch'; supported: boolean };\r\n   ```\r\n3. **Future: operation results** — If `write()` needs to return more than `void` (e.g., created vs. updated), a discriminated result type is cleaner than boolean flags.\r\n\r\n### Conformance Testing — Type-Level Enforcement\r\n\r\nThe conformance suite can use TypeScript's type system to guarantee completeness:\r\n\r\n```typescript\r\n// Compile-time: verify a class implements StorageProvider\r\ntype AssertProvider\u003cT extends StorageProvider> = T;\r\ntype _checkMarkdown = AssertProvider\u003cMarkdownStorageProvider>;  // compile error if missing methods\r\ntype _checkInMemory = AssertProvider\u003cInMemoryStorageProvider>;\r\n\r\n// Runtime: the conformance suite is a function, not a class\r\nfunction runConformanceSuite(\r\n  name: string,\r\n  factory: () => Promise\u003cStorageProvider>,  // factory, not instance — fresh state per test\r\n): void {\r\n  describe(`StorageProvider conformance: ${name}`, () => {\r\n    // Round-trip tests for every collection in CollectionEntityMap\r\n    for (const collection of COLLECTION_NAMES) {\r\n      it(`round-trips ${collection}`, async () => {\r\n        const provider = await factory();\r\n        // ... write, read, assert deep equality\r\n      });\r\n    }\r\n  });\r\n}\r\n\r\n// Invocation:\r\nrunConformanceSuite('MarkdownStorageProvider', () => MarkdownStorageProvider.create(tempDir));\r\nrunConformanceSuite('InMemoryStorageProvider', () => Promise.resolve(new InMemoryStorageProvider()));\r\n```\r\n\r\n**Key insight:** Use a _factory function_, not an instance. Each test gets a fresh provider. This prevents test pollution and mirrors real initialization.\r\n\r\n### DX Critique\r\n\r\n**What I'd enjoy:**\r\n- `state.agents.get('mal')` → handle pattern is excellent DX. Autocomplete works. No ceremony.\r\n- `await mal.history('learnings')` — overloaded method, scoped reads. Clean.\r\n- `state.decisions.add(...)` — simple, obvious.\r\n\r\n**What I'd change:**\r\n- `appendToSection(collection, id, section, entry)` at the StorageProvider level takes 4 positional string args. Consider a params object for clarity when more than 3 args:\r\n  ```typescript\r\n  appendToSection(params: { collection: CollectionName; id: string; section: string; entry: SectionEntry }): Promise\u003cvoid>;\r\n  ```\r\n- The `initialize()` / `dispose()` lifecycle should be hidden from callers. SquadState's constructor should call `initialize()`. Expose `dispose()` only for cleanup. Consider `Symbol.asyncDispose` for `using` syntax:\r\n  ```typescript\r\n  await using state = await SquadState.create(provider);\r\n  // automatically disposed when scope exits\r\n  ```\r\n\r\n### Missing Type Patterns\r\n\r\n1. **Template literal types for paths:** If the provider ever needs to express file paths:\r\n   ```typescript\r\n   type AgentPath = `.squad/agents/${string}/charter.md`;\r\n   type HistoryPath = `.squad/agents/${string}/history.md`;\r\n   ```\r\n   Not critical for v1, but useful if paths leak into the public API.\r\n\r\n2. **`satisfies` over `as const` for seed data:** The test fixtures should use `satisfies` to validate structure while preserving literal types:\r\n   ```typescript\r\n   const seed = {\r\n     agents: { 'test-agent': { charter: { name: 'test-agent', role: 'Tester' } } },\r\n   } satisfies SeedData;\r\n   ```\r\n\r\n3. **`NoInfer\u003cT>` for provider methods:** If a provider method accepts both a value and a type hint, `NoInfer` prevents the value from widening the inferred type. Not needed in v1 but worth noting for future generic methods.\r\n\r\n---\r\n","author":{"url":"https://github.com/diberry","@type":"Person","name":"diberry"},"datePublished":"2026-03-20T23:12:53Z","url":"https://github.com/github/squad/issues/481"}

react-profiling0
react-import-mapreact,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322
route-pattern/_view_fragments/issues/show/:user_id/:repository/:id/issue_layout(.:format)
route-controllervoltron_issues_fragments
route-actionissue_layout
fetch-noncev2:8ff69ea0-068f-7d35-8af4-3c9969e98c7c
current-catalog-service-hash81bb79d38c15960b92d99bca9288a9108c7a47b18f2423d0f6438c5b7bcd2114
request-idD0A4:1CEA6F:1C9C517:25AA93B:6B0153C2
html-safe-noncee492c52274bf37bd1ddcc1d9cd2396584617b1d2f239d21a68c70e607672b406
visitor-payloadeyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJEMEE0OjFDRUE2RjoxQzlDNTE3OjI1QUE5M0I6NkIwMTUzQzIiLCJ2aXNpdG9yX2lkIjoiODg2MzAzODY3MDY1NjA2NjQ5OCIsInJlZ2lvbl9lZGdlIjoiaWFkIiwicmVnaW9uX3JlbmRlciI6ImlhZCJ9
visitor-hmac512bc929573fa79e565852f9cfe26c576c920d6a45afb4e41da0520df33dcab8
hovercard-subject-tagissue:4110534533
github-keyboard-shortcutsrepository,issues,copilot
google-site-verificationApib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I
octolytics-urlhttps://collector.github.com/github/collect
analytics-location///voltron/issues_fragments/issue_layout
fb:app_id1401488693436528
apple-itunes-appapp-id=1477376905, app-argument=https://github.com/_view_fragments/issues/show/github/squad/481/issue_layout
twitter:imagehttps://opengraph.githubassets.com/40e3ecd75ac8c310d66e235d859403258cec9ec8e726ca08e2648c751beaee6d/github/squad/issues/481
twitter:cardsummary_large_image
og:imagehttps://opengraph.githubassets.com/40e3ecd75ac8c310d66e235d859403258cec9ec8e726ca08e2648c751beaee6d/github/squad/issues/481
og:image:altSquad State: Typed Interface + MarkdownProvider Author: Dina Berry Date: 2026-03-22 Status: Draft — Awaiting Brady's Review Target Repository: bradygaster/squad (packages/squad-sdk/) Related: Full ...
og:image:width1200
og:image:height600
og:site_nameGitHub
og:typeobject
og:author:usernamediberry
hostnamegithub.com
expected-hostnamegithub.com
Nonecc5dfdd32f62ebd3223cab3af3aa2b268d3605218237326a48a99d1efd89495c
turbo-cache-controlno-preview
go-importgithub.com/github/squad git https://github.com/github/squad.git
octolytics-dimension-user_id9919
octolytics-dimension-user_logingithub
octolytics-dimension-repository_id1151205052
octolytics-dimension-repository_nwogithub/squad
octolytics-dimension-repository_publictrue
octolytics-dimension-repository_is_forkfalse
octolytics-dimension-repository_network_root_id1151205052
octolytics-dimension-repository_network_root_nwogithub/squad
turbo-body-classeslogged-out env-production page-responsive
disable-turbofalse
browser-stats-urlhttps://api.github.com/_private/browser/stats
browser-errors-urlhttps://api.github.com/_private/browser/errors
release8c77c9e8439031ad54c75a250694842892f693e1
ui-targetfull
theme-color#1e2327
color-schemelight dark
react-app-nameissues

Links:

Skip to contenthttps://github.com/github/squad/issues/481#start-of-content
https://github.com/
Sign inhttps://github.com/login?return_to=https%3A%2F%2Fgithub.com%2Fgithub%2Fsquad%2Fissues%2F481
GitHubRepository hosting, code review, and collaborationhttps://github.com/platform
CopilotAI coding agent for tasks, projects, and automated workhttps://github.com/features/copilot
ActionsCI/CD and automationhttps://github.com/features/actions
Code QualityQuality analysis, fixes, and enforcementhttps://github.com/features/code-quality
CodespacesCloud development environmentshttps://github.com/features/codespaces
Code SecurityVulnerability detection and remediationhttps://github.com/security/advanced-security/code-security
Secret ProtectionSecret scanning and leak preventionhttps://github.com/security/advanced-security/secret-protection
All Featureshttps://github.com/features
Documentationhttps://docs.github.com/en
Traininghttps://learn.github.com/skills
Certificationshttps://learn.github.com/credentials
Build with Copilothttps://github.com/features/ai
Customize Copilothttps://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-copilot-overview
Integrationshttps://github.com/marketplace
Trending reposhttps://github.com/trending
GitHub Sponsorshttps://github.com/open-source/sponsors
Developer articleshttps://github.com/resources/articles
ChangelogYour source for the latest features, improvements, and fixes across GitHub products, all in one place.https://github.blog/changelog/
Enterpriseshttps://github.com/enterprise
Teamhttps://github.com/team
Startupshttps://github.com/enterprise/startups
Nonprofitshttps://github.com/solutions/industry/nonprofits
Healthcarehttps://github.com/solutions/industry/healthcare
Financial serviceshttps://github.com/solutions/industry/financial-services
Manufacturinghttps://github.com/solutions/industry/manufacturing
Governmenthttps://github.com/solutions/industry/government
See all industrieshttps://github.com/solutions/industry
Why GitHubhttps://github.com/why-github
Customer Storieshttps://github.com/customer-stories
Business insightshttps://github.com/solutions/executive-insights
Trust Centerhttps://github.com/trust-center
GitHub Advanced SecurityEnterprise-grade code securityhttps://github.com/security/advanced-security
Copilot for businessEnterprise-grade AI featureshttps://github.com/features/copilot/copilot-business
Premium SupportEnterprise-grade 24/7 supporthttps://github.com/enterprise/premium-support
Documentationhttps://docs.github.com/en
Resource centerhttps://github.com/resources
Bloghttps://github.blog/
Events & webinarshttps://github.com/resources/events
Community Forumhttps://github.com/orgs/community/discussions
Customer Storieshttps://github.com/customer-stories
Integrationshttps://github.com/marketplace
Customer supporthttps://help.github.com/
Traininghttps://learn.github.com/skills
GitHub Statushttps://www.githubstatus.com/
Abouthttps://github.com/about
Partnershttps://github.com/partners
Changeloghttps://github.blog/changelog/
GitHub UniverseThe event for developers, by developers — talks, workshops, and what’s next for GitHub.https://githubuniverse.com/
Pricinghttps://github.com/pricing
Sign inhttps://github.com/login?return_to=https%3A%2F%2Fgithub.com%2Fgithub%2Fsquad%2Fissues%2F481
Sign uphttps://github.com/signup?ref_cta=Sign+up&ref_loc=header+logged+out&ref_page=%2F%3Cuser-name%3E%2F%3Crepo-name%3E%2Fvoltron%2Fissues_fragments%2Fissue_layout&source=header-repo&source_repo=github%2Fsquad
Reloadhttps://github.com/github/squad/issues/481
Reloadhttps://github.com/github/squad/issues/481
Reloadhttps://github.com/github/squad/issues/481
githubhttps://github.com/github
squadhttps://github.com/github/squad
Codehttps://github.com/github/squad
Issues108 (108)https://github.com/github/squad/issues
Pull requests26 (26)https://github.com/github/squad/pulls
Discussionshttps://github.com/github/squad/discussions
Actionshttps://github.com/github/squad/actions
Projectshttps://github.com/github/squad/projects
Security and qualityhttps://github.com/github/squad/security
Insightshttps://github.com/github/squad/insights
https://github.com/github/squad
New issuehttps://github.com/login?return_to=https://github.com/github/squad/issues/481
New issuehttps://github.com/login?return_to=https://github.com/github/squad/issues/481
PRD: Squad State — Typed StorageProvider Interface with Contract Conformancehttps://github.com/github/squad/issues/481#top
enhancementNew feature or improvementhttps://github.com/github/squad/issues?q=state%3Aopen%20label%3A%22enhancement%22
go:needs-researchNeeds investigationhttps://github.com/github/squad/issues?q=state%3Aopen%20label%3A%22go%3Aneeds-research%22
squadSquad triage inbox — Lead will assign to a memberhttps://github.com/github/squad/issues?q=state%3Aopen%20label%3A%22squad%22
https://github.com/diberry
diberryhttps://github.com/diberry
on Mar 20, 2026https://github.com/github/squad/issues/481#issue-4110534533
#1https://github.com/github/squad/pull/1
#2https://github.com/github/squad/pull/2
#2https://github.com/github/squad/pull/2
Nexthttps://github.com/github/squad/issues/481?timeline_page=1
https://github.com/bradygaster
bradygasterhttps://github.com/bradygaster
on Mar 22, 2026https://github.com/github/squad/issues/481#issuecomment-4105680355
#479https://github.com/github/squad/issues/479
bradygasterhttps://github.com/bradygaster
squadSquad triage inbox — Lead will assign to a memberhttps://github.com/github/squad/issues?q=state%3Aopen%20label%3A%22squad%22
squad:controlhttps://github.com/github/squad/issues?q=state%3Aopen%20label%3A%22squad%3Acontrol%22
squad:eecomhttps://github.com/github/squad/issues?q=state%3Aopen%20label%3A%22squad%3Aeecom%22
enhancementNew feature or improvementhttps://github.com/github/squad/issues?q=state%3Aopen%20label%3A%22enhancement%22
on Mar 22, 2026https://github.com/github/squad/issues/481#event-23788469637
https://github.com/apps/github-actions
github-actionshttps://github.com/apps/github-actions
on Mar 22, 2026https://github.com/github/squad/issues/481#issuecomment-4105680606
GitHub Actionshttps://help.github.com/en/actions
#481https://github.com/github/squad/issues/481
https://github.com/apps/github-actions
github-actionshttps://github.com/apps/github-actions
on Mar 22, 2026https://github.com/github/squad/issues/481#issuecomment-4105680607
GitHub Actionshttps://help.github.com/en/actions
#481https://github.com/github/squad/issues/481
github-actionshttps://github.com/apps/github-actions
squad:fidohttps://github.com/github/squad/issues?q=state%3Aopen%20label%3A%22squad%3Afido%22
go:needs-researchNeeds investigationhttps://github.com/github/squad/issues?q=state%3Aopen%20label%3A%22go%3Aneeds-research%22
on Mar 22, 2026https://github.com/github/squad/issues/481#event-23788470724
https://github.com/apps/github-actions
github-actionshttps://github.com/apps/github-actions
on Mar 22, 2026https://github.com/github/squad/issues/481#issuecomment-4105680624
GitHub Actionshttps://help.github.com/en/actions
#481https://github.com/github/squad/issues/481
bradygasterhttps://github.com/bradygaster
on Mar 23, 2026https://github.com/github/squad/issues/481#event-23805300234
docs(ai-team): Cross-agent triage updates + history initializationhttps://github.com/github/squad/commit/7c00ab7580eeaa47c459d22728121c7bae819c6a
7c00ab7https://github.com/github/squad/commit/7c00ab7580eeaa47c459d22728121c7bae819c6a
https://github.com/diberry
diberryhttps://github.com/diberry
on Mar 23, 2026https://github.com/github/squad/issues/481#issuecomment-4111095451
#479https://github.com/github/squad/issues/479
#479https://github.com/github/squad/issues/479
Bug: history-shadow.ts has read-modify-write race condition (data loss) #479https://github.com/github/squad/issues/479
https://github.com/diberry
diberryhttps://github.com/diberry
on Mar 23, 2026https://github.com/github/squad/issues/481#issuecomment-4111145679
https://github.com/diberry
diberryhttps://github.com/diberry
on Mar 23, 2026https://github.com/github/squad/issues/481#issuecomment-4111188081
@bradygasterhttps://github.com/bradygaster
diberryhttps://github.com/diberry
on Mar 23, 2026https://github.com/github/squad/issues/481#event-23818177276
feat(sdk): StorageProvider interface + FSStorageProvider (github#481)https://github.com/diberry/squad/commit/391777c4fcd9bbdbd282c95ed5218e2e35d8f597
github#481https://github.com/github/squad/issues/481
391777chttps://github.com/diberry/squad/commit/391777c4fcd9bbdbd282c95ed5218e2e35d8f597
diberryhttps://github.com/diberry
on Mar 26, 2026https://github.com/github/squad/issues/481#event-23930477379
feat: StorageProvider Phases 0-3 + Waves 3a/3b/3c/4 + example provide…https://github.com/diberry/squad/commit/9fe5c26903eb5c28f70bc9ba556747fada3f096a
9fe5c26https://github.com/diberry/squad/commit/9fe5c26903eb5c28f70bc9ba556747fada3f096a
feat: StorageProvider Phases 0-3 + Waves 3a/3b/3c/4 + example provide…https://github.com/diberry/squad/commit/cfc907bbf15745c45c5d94bd43a0f68a72ce42e0
cfc907bhttps://github.com/diberry/squad/commit/cfc907bbf15745c45c5d94bd43a0f68a72ce42e0
feat: StorageProvider Phases 0-3 + Waves 3a/3b/3c/4 + example provide…https://github.com/diberry/squad/commit/ce8876f5394f741fabbb71287de34db9fb3bcfa8
ce8876fhttps://github.com/diberry/squad/commit/ce8876f5394f741fabbb71287de34db9fb3bcfa8
feat: StorageProvider Phases 0-3 + Waves 3a/3b/3c/4 + example provide…https://github.com/diberry/squad/commit/0827911f61c2aa1f4feeaffae58c172ccc5d08b2
0827911https://github.com/diberry/squad/commit/0827911f61c2aa1f4feeaffae58c172ccc5d08b2
feat: StorageProvider Phases 0-3 + Waves 3a/3b/3c/4 + example provide…https://github.com/diberry/squad/commit/f0f801120841e2aefe804310c9b76b520dd89787
f0f8011https://github.com/diberry/squad/commit/f0f801120841e2aefe804310c9b76b520dd89787
feat(sdk): StorageProvider interface + FSStorageProvider (github#481)https://github.com/diberry/squad/commit/fd6b571ce8a6b1d5b9de5b431246fc475991cb33
github#481https://github.com/github/squad/issues/481
fd6b571https://github.com/diberry/squad/commit/fd6b571ce8a6b1d5b9de5b431246fc475991cb33
feat(sdk): StorageProvider interface + FSStorageProvider + InMemorySt…https://github.com/diberry/squad/commit/a41a03f540504cf3dacbf75357aebcf3854cc582
a41a03fhttps://github.com/diberry/squad/commit/a41a03f540504cf3dacbf75357aebcf3854cc582
feat(storage): add StorageProvider abstraction layerhttps://github.com/diberry/squad/commit/58cdfcb81d71bf35ab815d5f56a68ea0665dc6c2
58cdfcbhttps://github.com/diberry/squad/commit/58cdfcb81d71bf35ab815d5f56a68ea0665dc6c2
feat(storage): add StorageProvider abstraction layerhttps://github.com/diberry/squad/commit/fe0ab659ca9c6857f406a925899de1bcd239b8bc
fe0ab65https://github.com/diberry/squad/commit/fe0ab659ca9c6857f406a925899de1bcd239b8bc
feat(storage): add StorageProvider abstraction layerhttps://github.com/diberry/squad/commit/7d70900c53d37f018b9a3ca8847c9783c089c88a
7d70900https://github.com/diberry/squad/commit/7d70900c53d37f018b9a3ca8847c9783c089c88a
https://github.com/diberry
diberryhttps://github.com/diberry
on Mar 31, 2026https://github.com/github/squad/issues/481#issuecomment-4163822155
#678https://github.com/github/squad/issues/678
#680https://github.com/github/squad/pull/680
diberryhttps://github.com/diberry
completedhttps://github.com/github/squad/issues?q=is%3Aissue%20state%3Aclosed%20archived%3Afalse%20reason%3Acompleted
on Apr 1, 2026https://github.com/github/squad/issues/481#event-24129734154
bradygasterhttps://github.com/bradygaster
squad:eecomhttps://github.com/github/squad/issues?q=state%3Aopen%20label%3A%22squad%3Aeecom%22
squad:fidohttps://github.com/github/squad/issues?q=state%3Aopen%20label%3A%22squad%3Afido%22
squad:controlhttps://github.com/github/squad/issues?q=state%3Aopen%20label%3A%22squad%3Acontrol%22
on Sep 11, 2026https://github.com/github/squad/issues/481#event-31000777222
Sign up for freehttps://github.com/signup?return_to=https://github.com/github/squad/issues/481
Sign in to commenthttps://github.com/login?return_to=https://github.com/github/squad/issues/481
enhancementNew feature or improvementhttps://github.com/github/squad/issues?q=state%3Aopen%20label%3A%22enhancement%22
go:needs-researchNeeds investigationhttps://github.com/github/squad/issues?q=state%3Aopen%20label%3A%22go%3Aneeds-research%22
squadSquad triage inbox — Lead will assign to a memberhttps://github.com/github/squad/issues?q=state%3Aopen%20label%3A%22squad%22
https://github.com
Termshttps://docs.github.com/site-policy/github-terms/github-terms-of-service
Privacyhttps://docs.github.com/site-policy/privacy-policies/github-privacy-statement
Securityhttps://github.com/security
Statushttps://www.githubstatus.com/
Communityhttps://github.community/
Docshttps://docs.github.com/
Contacthttps://support.github.com?tags=dotcom-footer

Viewport: width=device-width


URLs of crawlers that visited me.