@inneranimalmedia/agentsam-sdk 2.6.2 → 2.6.4

package/docs/architecture/SAM_KERNEL.md

@@ -0,0 +1,181 @@
+# SAM Kernel — Systematic Autonomous Machinery
+
+**Status:** LOCKED vocabulary + seed contracts (2026-09-25)  
+**Product:** AgentSam (`@inneranimalmedia/agentsam-sdk`)  
+**Machinery:** SAM = **Systematic Autonomous Machinery**
+
+This document is the canonical architecture for how AgentSam exposes work. It does **not** replace `AGENTSAM.md` runtime agent law; it defines the developer-facing execution spine.
+
+---
+
+## Naming (non-negotiable)
+
+| Term | Meaning |
+|------|---------|
+| **AgentSam** | Product / SDK / CLI / platform |
+| **SAM** | **Systematic Autonomous Machinery** — the execution architecture underneath AgentSam |
+| **`sam`** | Conventional client variable for that machinery — **not** a human identity or owner name |
+| **`sam.invoke()`** | Universal normalized execution doorway |
+
+Docs and comments prefer:
+
+- “SAM resolves the registered operation…”
+- “AgentSam executes the operation through SAM…”
+
+Never:
+
+- “Sam will decide…”
+- anthropomorphic `sam.ask()` / `sam.think()` as public verbs
+
+---
+
+## Hierarchy
+
+```text
+@inneranimalmedia/agentsam-sdk
+│
+├── AgentSamClient   (sam)
+│     ├── session: login / logout / whoami
+│     ├── runtime: status / configuration
+│     └── SAM: invoke / describe / discover + domain modules
+│
+├── SAM Kernel
+│     auth · schemas · policy · execution lanes · events · errors · receipts
+│
+├── Modules (brand, repository, knowledge, security, cad, cms, …)
+│     register operations into the kernel — they do not own a second runtime
+│
+├── Operations · Capabilities · Tools · Skills · Pipelines · Providers · Contracts
+└── Projections: TypeScript · CLI · MCP · HTTP · Python · Workbench · docs
+```
+
+**CLI is a projection, not the source of truth.** Canonical identity is the **operation ID**.
+
+---
+
+## Four seed primitives
+
+| Primitive | Role |
+|-----------|------|
+| `defineSamOperation()` | Register one operation (schemas, lanes, model policy, handler) |
+| `sam.invoke(id, input, options?)` | Execute any registered operation |
+| `sam.describe(id)` | Metadata / schemas / requirements without execution |
+| `sam.discover({ query })` | Compact operation cards before schema hydration |
+
+Domain ergonomics are projections of `invoke`:
+
+```js
+await sam.brand.scan({ root: '.' });
+// ≡
+await sam.invoke('brand.scan', { root: '.' });
+```
+
+---
+
+## Vocabulary
+
+| Kind | Meaning |
+|------|---------|
+| **module** | Domain namespace (`brand`, `repository`, `cad`) |
+| **operation** | User-callable capability (`brand.scan`) |
+| **tool** | Bounded executable primitive (often agent-facing) |
+| **skill** | Procedural knowledge / instructions |
+| **pipeline** | Ordered composition of operations/tools |
+| **capability** | Declaration of what the runtime can perform |
+| **provider** | Adapter to an external/local implementation |
+| **contract** | Portable schemas / types / vocabulary |
+
+Do not flatten everything into “tools.”
+
+---
+
+## Operation contract (normative)
+
+Every externally callable AgentSam capability:
+
+1. Has **one** canonical operation ID (`module.action` or `module.subsystem.action`)
+2. Declares typed **input** / **output** schemas
+3. Declares **execution** metadata: lanes, `model: never|optional|required`, network, side effects, risk
+4. Is invokable through **SAM** (`invoke`) and projected to CLI / MCP / HTTP without renaming authority
+5. Returns a **SamResult** envelope (`data` + `receipt` + optional evidence/artifacts/usage)
+
+Alias ≠ authority. Human CLI aliases (`agentsam inspect`, `agentsam sca`) remain; internal ID stays `repository.inspect` / `security.scan`.
+
+### Session vs operations
+
+`login`, `logout`, `whoami`, shell preferences, and help are **client/session/runtime** controls. Do not force them through `sam.invoke('auth.login')`.
+
+---
+
+## Result envelope
+
+```ts
+interface SamResult<T> {
+  schema: 'agentsam.result.v1';
+  operation: string;
+  ok: boolean;
+  data: T;
+  receipt: SamReceipt;
+  evidence?: unknown[];
+  artifacts?: unknown[];
+  usage?: { provider_calls: number; cost_usd?: number; /* … */ };
+  warnings?: unknown[];
+}
+```
+
+`data` is what the caller asked for. `receipt` is how SAM proves what happened.
+
+---
+
+## Execution policy (AI is a lane, not the API)
+
+`choice()` / `predicate()` / `score()` (future `sam.machine.evaluate`) mean **bounded classification**, not “send to GPT.” Runtime may satisfy via rules, cache, heuristics, local models, or remote models under policy.
+
+Operations declare `model: never | optional | required` so `$0` machinery is machine metadata, not README prose.
+
+---
+
+## Seed operations (first migration set)
+
+| Operation ID | CLI projection | model |
+|--------------|----------------|-------|
+| `repository.inspect` | `agentsam inspect` | never |
+| `brand.scan` | `agentsam brand scan` | never |
+| `security.scan` | `agentsam security scan` | never |
+| `terminal.exec` | (runtime / tools) | never |
+| `cad.blender.inspect` | `agentsam cad blender inspect` | never |
+| `codebaseindex.ingest` | `agentsam codebaseindex` / `ingest` | optional |
+
+Pipeline alias for host escalation: `sam.codebaseindex.index.run`.
+
+Handlers reuse existing implementations. New work asks: **What module owns this operation?**
+
+---
+
+## Go / agentsamd (next lane — Slice H)
+
+Local durable machine service (`agentsamd`) owns PTY, jobs, local invoke — **not** a Tauri rewrite. `AGENTSAM_API_KEY` authenticates **remote/platform** operations; local capabilities stay key-optional. Tauri may later consume the same daemon.
+
+See: Go Worker product lane already live; expand carefully.
+
+---
+
+## Related files
+
+| Path | Role |
+|------|------|
+| `protocol/sam/operation.schema.json` | Operation metadata schema |
+| `protocol/sam/result.schema.json` | SamResult envelope |
+| `protocol/sam/registry.seed.json` | Seed operation registry |
+| `src/sam/` | Kernel registry + `AgentSamClient` / `invoke` / `describe` / `discover` |
+| `protocol/capabilities/manifest.json` | Existing capability cards (migrate into ops over time) |
+
+---
+
+## Anti-patterns
+
+- Building a miniature runtime inside each package
+- Making `systemOne()` / chat APIs the flagship surface
+- Letting CLI command strings define internal operation IDs
+- Requiring `AGENTSAM_API_KEY` for local inspect/merkle/security
+- Documenting APIs by hand that should be projections of the registry

package/docs/architecture/SAM_MACHINE_NORMALIZATION_PRECOMMIT_REPORT.md

@@ -0,0 +1,208 @@
+# PRE-COMMIT REPORT — SAM Machine Normalization Sprint
+
+**Date:** 2026-09-25  
+**Repo:** `@inneranimalmedia/agentsam-sdk`  
+**Status:** **NOT COMMITTED** — awaiting your review per sprint contract §32  
+**Working tree:** dirty with the changes summarized below
+
+---
+
+## 1. Current command-catalog authority
+
+- **Authority file:** `src/cli/command-catalog.js` (`CLI_COMMAND_CATALOG`)
+- **Help:** `src/ui/cli/help.js` already consumes the catalog (topics/common/skill tips)
+- **Tips:** `printAssistTip()` — human stderr only; **skipped for `--json`**
+- **New:** `src/cli/dispatch.js` — lazy handler bootstrap (partial)
+
+## 2. Remaining command truth still hardcoded in `cli.js`
+
+- The giant `if/else` dispatch chain from `create` → `scaffold` is **still live**
+- Legacy `printLegacyHelp()` prose block remains in `cli.js`
+- Init interactive still hardcodes lane options (Full Stack / CMS / …)
+- Catalog dispatch only wires: `codebaseindex|ingest`, `skills|skill`
+- **Deferred:** full cutover of ~45 verbs to lazy catalog handlers
+
+## 3. Final SamOperation contract (this sprint)
+
+Rich fields now supported by `defineSamOperation()` / `src/sam/types.js`:
+
+| Field | Role |
+|-------|------|
+| `id`, `version`, `module`, `action` | Identity |
+| `summary` | Card/search |
+| `purpose`, `outcome` | Product capability semantics |
+| `accepts[]` | Material / input kinds |
+| `phases[]` | Execution phases |
+| `artifacts[]` | Produced artifact kinds |
+| `skill` | `{ id, help }` or `null` |
+| `preview` | `{ available, operation }` |
+| `execution` | lanes, model, network, sideEffects, **embedding**, **provider_spend** |
+| `risk`, `capabilities`, `cli`, `docs`, `status` | Policy + projections |
+| `handler` | Existing machinery |
+
+Thin `{ id, module, action, summary }` alone is **not** treated as a complete capability definition.
+
+## 4. Commands / operations graduated in this working set
+
+| Operation | Notes |
+|-----------|-------|
+| `repository.inspect` | Purpose/outcome/phases/accepts enriched; richer return refs |
+| `brand.scan` | BrandPack-oriented contract; points to `brand.preview` |
+| `codebaseindex.ingest` | Inventory-first phases; job graph artifact |
+| `terminal.exec`, `security.scan`, `cad.blender.inspect` | Still on prior seed contracts (not re-authored this pass) |
+
+Desktop:
+
+| Item | Change |
+|------|--------|
+| Local Studio manifest | `launch_path: "/agentsam"` + `routes` + `auth` notes |
+
+## 5. Skill mapping
+
+| Command / op | Skill |
+|--------------|-------|
+| codebaseindex / ingest | `agentsam-codebaseindex` |
+| repository.inspect | `agentsam-app-fundamentals` (until `agentsam-repository` skill exists) |
+| brand.scan | `agentsam-app-fundamentals` (until `agentsam-brand` skill exists) |
+| security | `agentsam-progression-guard` |
+| cloudflare / mcp / go | `agentsam-cloudflare-workers` |
+
+**Deferred:** dedicated `agentsam-brand`, `agentsam-repository`, `agentsam-security`, `agentsam-cad`, `agentsam-mcp`, `agentsam-identity` skill packs.
+
+## 6. Generic material-ingest contract
+
+- **Current:** `src/lib/ingest/materials.js` (stage under `.agentsam/ingest/<id>/`)
+- **Shared:** used by codebaseindex; ops declare `accepts[]`
+- **Deferred:** promote to first-class SAM material resolver for brand/cad/security; zip slip limits / symlink escape hardening tests; `--stdin` convention end-to-end
+
+## 7. Inventory output schema
+
+- `agentsam.inventory.v1` via `src/lib/ingest/inventory.js`
+- Fields: counts, languages, top_level, suggested include/exclude, sample_paths, materials
+- Human projection: `formatInventoryTree()` (ASCII is **not** authority)
+
+## 8. Codebaseindex guided flow (now)
+
+```text
+① Connection discovery (credentials + ollama list)
+② Materials (paste/drop)
+③ INVENTORY / file map  ← confirm before scope
+④ Include / exclude (inventory suggestions · manual · optional Ollama assist)
+⑤ Embedding profile (discovered only; always includes none)
+⑥ Vector lane: local | supabase+node-api | vectorize
+⑦ Dry-run/plan (default) or execute
+→ job graph printed
+```
+
+## 9. Local SQLite schema / migrations
+
+- **Deferred:** portable spine migrations mirroring D1 logical core
+- Today: existing `.agentsam/knowledge/index.sqlite` knowledge store only
+
+## 10. D1 mapping (logical — not copied blindly)
+
+`code_repositories`, merkle/evidence, `agentsam_code_index_job(+_file)`, `codebase_ast_nodes`, `codebase_dep_edges`, health, `agentsam_pgvector_lane_registry`
+
+## 11. Supabase / Postgres mapping
+
+Host SSOT tables (Gemini@1536):
+
+- `agentsam.agentsam_codebase_chunks_gemini_embedding_2_1536`
+- `agentsam.agentsam_codebase_files_gemini_embedding_2_1536`
+- `agentsam.agentsam_codebase_ast_symbols_gemini_embedding_2_1536`
+- `agentsam.agentsam_gemini_semantic_embeddings_1536`
+- `agentsam.agentsam_documents_gemini_embedding_2_1536`
+
+Customer template: BYO node-api edge + Hyperdrive (documented in `CODEBASEINDEX_GUIDED_PATH.md`).
+
+## 12. Vectorize mapping
+
+- Lane selectable in wizard as `vectorize`
+- **Deferred:** full CF Vectorize adapter write path (receipt notes only today)
+- IAM host code-index SSOT remains Supabase pgvector, not Vectorize
+
+## 13. Embedding discovery source per provider
+
+| Source | Mechanism |
+|--------|-----------|
+| OpenAI | Live `/v1/models` when credential configured |
+| Gemini | Credential → knowledge adapter model list |
+| Ollama | Live `/api/tags`; embed-like tags → embed picker; chat tags → scope assist |
+| None | Always offered |
+
+## 14. Profile identity / fingerprint
+
+- Knowledge engine already fingerprints embedding profile (`embeddingProfileId`)
+- Encoding: `provider|model|dimensions` (colon-safe for `mxbai-embed-large:latest`)
+- Semantic retrieve fails closed on profile mismatch
+- **Deferred:** replace `defaultDimensions()` regex with adapter metadata + Ollama probe length as sole authority
+
+## 15. App discovery mechanism
+
+- **Deferred:** `agentsam app options` from manifests (`apps/*/agentsam.app.json`, themes)
+- Current `app` command path still mostly launcher-shaped
+
+## 16. Init / app-options UX
+
+- **Deferred:** replace hardcoded Full Stack/CMS/… init menu with discoverable apps/themes/materials start
+
+## 17. BrandPack schema
+
+- Added: `protocol/brand/brandpack.v1.schema.json` (`agentsam.brandpack.v1`)
+- **Deferred:** `brand.preview` handler, localhost brand grid, pack export/import round-trip
+
+## 18. Brand preview path
+
+- Contract points to `brand.preview` with `sideEffects: local_write` intended
+- **Not implemented** this pass (scan stays read-only)
+
+## 19. Tests run
+
+```text
+node --test test/sam-kernel.test.mjs test/codebaseindex-ingest.test.mjs test/ingest-discover-models.test.mjs
+→ 23 pass / 0 fail
+```
+
+## 20. Intentionally deferred
+
+1. Full `cli.js` catalog cutover (kill legacy help + if/else)
+2. `agentsam app options` + init discovery
+3. `brand.preview` + BrandPack export/import UX
+4. Shared material resolver with archive sandbox hard limits + tests
+5. Ollama dimension probe as SSOT (retire name heuristics)
+6. Metadata vs vectors storage split as first-class config object (wizard records lanes; knowledge.json still primarily sqlite|postgres)
+7. Local SQLite portable D1-spine migrations
+8. Customer node-api / Supabase template pack
+9. Wire Local Studio session gate: `/agentsam` → session check → `/auth/login?next=/agentsam`
+10. agentsamd behind Tauri (Slice H)
+11. Rebuild/reinstall DMG after manifest change (needs `build-brand` + Tauri release)
+
+---
+
+## Desktop auth note (your screenshots)
+
+Three surfaces:
+
+| URL | Role |
+|-----|------|
+| `/` | PUBLIC marketing — **not** desktop home |
+| `/auth/login` | IDENTITY |
+| `/agentsam` | PRODUCT (Local Studio) |
+
+Manifest fix: `launch_path: "/agentsam"`. Login entry: `/auth/login?next=/agentsam`. Re-run desktop brand build + reinstall to pick up in `/Applications`.
+
+---
+
+## Files touched (pending commit)
+
+- `packages/agentsam-desktop-shell/manifests/local-studio.json`
+- `packages/agentsam-desktop-shell/manifests/schema.json`
+- `src/sam/types.js`, `define.js`, `client.js`
+- `src/sam/operations/{repository-inspect,brand-scan,codebaseindex-ingest}.js`
+- `src/commands/codebaseindex.js` (inventory-first wizard)
+- `src/lib/ingest/{inventory,job-graph}.js`
+- `src/cli/{command-catalog,dispatch}.js`
+- `protocol/brand/brandpack.v1.schema.json`
+- this report: `docs/architecture/SAM_MACHINE_NORMALIZATION_PRECOMMIT_REPORT.md`
+
+**No commit / no push** until you approve.

package/docs/architecture/SLASH_SKILLS_PORTABLE.md

@@ -0,0 +1,116 @@
+# Portable slash skills — architecture & migration report
+
+**Status:** implemented in `agentsam-sdk` (local-first). **Not committed** pending review.  
+**Do not** copy IAM `skill-slash-invoke.js` / R2 hydration / platform account fallback into the SDK.
+
+---
+
+## Target architecture
+
+```
+/skill args
+   ↓
+parseSlashInvocation()          ← CLI / shell only; prose = no lookup
+   ↓
+SkillRegistry                   ← user · installed · app · builtins
+   ↓
+SkillManifest (agentsam.skill.v1)
+   ↓
+SkillContentResolver            ← inline | local_file | package_file | database | object_store
+   ↓
+SkillRuntime.invoke()           ← turn-only
+   ↓
+SkillInvocationResult
+   ├── modelInstructions        ← what the model sees
+   ├── tools / operations       ← declared requirements
+   ├── interaction              ← AgentSamInteraction (Clack / Studio / Tauri)
+   └── receipt                  ← source · version · checksum
+```
+
+### Explicit non-goals (monolith leaks rejected)
+
+| Leak | Replacement |
+|------|-------------|
+| `account_id IN ('platform','system')` | Layered registry sources — no pseudo accounts |
+| `ORDER BY account_id = ?` precedence | Install-time trigger map; collisions → alias |
+| Global unique published slash | Package may *suggest*; local registry owns binding |
+| `metadata.pipeline` → subagent profiles | Declared `tools` / `operations` / `capabilities` |
+| `hydrateSkillRowFromR2` | `object_store` adapter (R2 is one driver) |
+| D1-required lookup | Local `~/.agentsam/skills/registry.json` works offline |
+| Empty `promptBlock` | `modelInstructions` ≠ `interaction` |
+| Hyperdrive as “provider” | `accelerator_ref` on retrieval rows |
+| `embedding_model` + `dimensions` on retrieval | `embedding_profile_id` only |
+
+### Canonical slash
+
+- Parse: `/[a-zA-Z0-9][a-zA-Z0-9-]{0,63}` → store/lookup as **lowercase** `/kebab-case`
+- Normalize on write (`canonicalizeSlashTrigger`); exact match on read
+- Underscores rewritten to dashes at canonicalize time
+
+### Registry layers
+
+1. **User / installed** (`~/.agentsam/skills/`) — authoritative triggers  
+2. **App-provided** (optional inject)  
+3. **SDK builtins** (`skills/catalog.json`) — suggested trigger only if free  
+
+### Interaction contract (`agentsam.interaction.v1`)
+
+`ready | needs_input | needs_approval | blocked | complete`  
+Prompt kinds: `info | text | select | multiselect | confirm | error`
+
+---
+
+## Migration report (IAM → portable)
+
+IAM cutover `0011_*` remains host storage. Portable runtime does **not** depend on it.
+
+| IAM today | Portable SDK | Host migration later |
+|-----------|--------------|----------------------|
+| Lookup with `platform`/`system` | Delete clause | Hosted SkillStore adapter filters by real `account_id` only |
+| `LOWER(TRIM(slash_trigger))` | Canonical write | Backfill triggers to lowercase kebab; drop expression lookups |
+| Partial unique published slash | Drop global uniqueness | Allow duplicate *suggestions*; enforce uniqueness per install |
+| `metadata.pipeline` + subagents | Remove from slash path | Map declared ops to SAM operations |
+| R2 hydrate in invoke | Content resolver | Register `cloudflare-r2` object_store adapter |
+| Retrieval `provider IN (… hyperdrive …)` | See `migrations/sqlite/agentsam_skill_retrieval.portable.sql` | Split strategy/provider/driver/accelerator |
+| Metrics triggers on `content_markdown` | Compute on resolve/install | Keep trigger only as inline optimization |
+| `promptBlock: ''` | Split fields | Chat adapters render `interaction` |
+
+**Hosted ownership:** stay in the **SkillStore adapter**, not in the portable manifest (no `workspace_id` / `tenant_id` on `agentsam.skill.v1`).
+
+---
+
+## CLI surface
+
+```
+agentsam skill list|create|inspect|edit|install|alias|remove|publish|invoke
+agentsam skills …          # legacy catalog reader (SDK built-in markdown skills)
+```
+
+Interactive shell:
+
+- `/skills` — vocabulary (no model)
+- `/<trigger> args` — skill invoke when not a hard-coded shell command
+- Unknown `/deply` → suggestions (no model)
+
+---
+
+## Files added
+
+- `protocol/skills/agentsam.skill.v1.schema.json`
+- `protocol/skills/agentsam.interaction.v1.schema.json`
+- `src/skills/{slash,manifest,interaction,metrics,content-resolver,local-store,registry,runtime,index}.js`
+- `src/skills/catalog.js` (renamed from index)
+- `src/commands/skill.js`
+- `migrations/sqlite/agentsam_skill_retrieval.portable.sql`
+- `test/skill-runtime.test.mjs`
+
+---
+
+## Hosted SkillStore
+
+Portable runtime uses `createNullHostedSkillStore()` offline.
+
+Hosts inject a real adapter that lists/puts skills **by real `account_id` only**.
+IAM must not keep `account_id IN ('platform','system')` visibility.
+
+See `src/skills/hosted-store.js`.

package/docs/architecture/STORAGE.md

@@ -0,0 +1,87 @@
+# AgentSam storage architecture
+
+## Authorities
+
+AgentSam's own local execution state defaults to one database per project:
+`<projectRoot>/.agentsam/data/agentsam.sqlite`. A model or provider switch
+keeps the same ProjectSession and storage authority. A `cwd` change inside the
+project also keeps it. Switching repositories selects a new project authority.
+
+The user's application keeps its actual storage. In this repository,
+`apps/local-studio/backend/wrangler.jsonc` declares a deployed Worker with D1,
+Hyperdrive, R2, Workers AI, and service bindings. AgentSam must honor those
+bindings for Worker features. Its local SQLite session state does not replace
+the Worker's data, provision new cloud state, or start an implicit sync. Inspect
+the project's real deployment and data bindings before choosing storage for
+application features. Use local SQLite for application data only when the user
+selects it or the task benefits from a clearly scoped local cache or scratch
+store.
+
+Cloudflare, Postgres/Supabase, object stores, and vector systems are connected
+infrastructure. Their use is explicit and governed by the user's project and
+credentials. Ordinary `agentsam` boot requires none of them. Durable Objects
+are reserved for a future optional actor adapter with a demonstrated need for
+globally addressed, serialized distributed actors. No default runtime path may
+require one.
+
+## Runtime state and lifecycle
+
+`src/local/runtime-store.js`, `src/local/sqlite.js`, and
+`src/local/migrations.js` own the local relational runtime and its versioned
+SQL. `src/lib/local-sessions.js` writes resumable session records to the same
+database. The older `~/.agentsam/sessions/*.json` files are a read-only
+compatibility source: a session is imported only when its saved project root
+matches the selected project. New sessions do not write there.
+`agentsam resume` lists sessions for the current project; use
+`agentsam resume --cwd <project-path>` when invoking it elsewhere. Opaque
+provider response IDs can continue across process restarts. Provider message
+arrays remain in memory for the active shell and are not stored in generic
+session state. An explicit native compaction saves only its latest returned
+window in the separate `agentsam_provider_continuations` session record, bounded
+to 10 MiB. It is replaced on compaction and deleted after successful continuation.
+Generic session JSON retains only a presence marker and a usage/cost receipt.
+The returned window may contain plaintext provider items as well as encrypted
+items; local SQLite file permissions protect access, not application-level
+encryption. It is never a knowledge source. Outside that explicit checkpoint,
+providers without an opaque continuation ID start a fresh model conversation
+after process restart.
+
+| Lifecycle | Keep | Expire or discard |
+| --- | --- | --- |
+| persistent | project configuration, selected model metadata, valuable cache | stale derived copies |
+| session | safe continuation IDs, status, usage, bounded receipts | raw prompts and provider message arrays |
+| work_cycle | accepted objective/plan, final checkpoint and evidence | search frontier and rejected candidates |
+| ttl | useful temporary context digest until expiry | expired digest/scratch |
+| scratch | recoverable intermediate state only while needed | all obsolete scratch |
+
+Existing runtime tables carry their own status and expiry fields where
+applicable. New persisted concepts require a migration, an owner, and a
+cleanup rule. Credentials stay in the existing credential-specific machine
+stores. Session state retains no access/refresh tokens, provider keys, cookies,
+or raw prompts. Blob and vector data do not belong behind a pretend universal
+relational interface. `SQLITE_RUNTIME_CAPABILITIES` reports transactions,
+relational queries, application-managed expiry, and local-only storage; it
+does not claim shared remote state, blob/vector storage, or actor semantics.
+
+## Connected infrastructure and sync
+
+Use the cheapest appropriate authority already available. Local session and
+run state belongs in SQLite. Remote relational application data may belong in
+the user's D1 or Postgres. Blobs may belong in the user's object store; vectors
+in the selected vector system. An explicit remote integration must state its
+source authority, owner, direction, retry, conflict, freshness, and deletion
+policy before copying state between stores. Connected D1 does not move a local
+ProjectSession into D1.
+
+## Enforcement
+
+The existing source boundary verifier rejects a new Durable Object dependency
+in the default shell, runtime store, agent, and provider paths. It also checks
+that resumable sessions use the canonical project SQLite database and that
+runtime schema definitions stay in versioned migrations. Focused storage tests
+cover project-root selection, project isolation, model-independent session
+storage, migration behavior, and secret-free session rows.
+
+See [Provider tools and compaction](PROVIDER-TOOLS-AND-COMPACTION.md) for the
+continuation contract and [knowledge lifecycle proposal](../../protocol/knowledge/LIFECYCLE.md)
+for blackboard, knowledge, evidence, and store-selection boundaries.

package/docs/architecture/fs-e2e-receipt.latest.json

@@ -0,0 +1,42 @@
+{
+  "schema": "agentsam.fs-e2e-receipt.v1",
+  "complete": true,
+  "root": "/var/folders/4s/05_wctw12k33szskjcfrr1bc0000gn/T/agentsam-fs-e2e-SUSpQa",
+  "workspace_id": "ws_ce3df666a4cef739031b",
+  "runtimeBaseUrl": "http://127.0.0.1:65149",
+  "pty_session_id": "pty_mugpalql_x93808",
+  "monaco_path": "README.md",
+  "monaco_marker": "MONACO_MARK_1790325024020",
+  "git_diff_snippet": "\r\nThe default interactive shell is now zsh.\r\nTo update your account to use zsh, please run `chsh -s /bin/zsh`.\r\nFor more details, please visit https://support.apple.com/kb/HT208050.\r\n\u001b[?1034hbash-3.2$ git diff -- README.md; echo MONACO_MARK_DONE\r\n\u001b[?1h\u001b=\r\u001b[1mdiff --git a/README.md b/README.md\u001b[m\u001b[m\r\n\u001b[1mindex aa5699e..342a7bb 100644\u001b[m\u001b[m\r\n\u001b[1m--- a/README.md\u001b[m\u001b[m\r\n\u001b[1m+++ b/README.md\u001b[m\u001b[m\r\n\u001b[36m@@ -1 +1,3 @@\u001b[m\u001b[m\r\n # disposable\u001b[m\u001b[m\r\n\u001b[32m+\u001b[m\u001b[m\r\n\u001b[32m+\u001b[m\u001b[32m## MONACO_MARK_1790325024020\u001b[m\u001b[m\r\n\r\u001b[K\u001b[?1l\u001b>MONACO_MARK_DONE\r\nbash-3.2$ ",
+  "identity": {
+    "type": "workspace_identity",
+    "workspace_id": "ws_ce3df666a4cef739031b",
+    "root": "/var/folders/4s/05_wctw12k33szskjcfrr1bc0000gn/T/agentsam-fs-e2e-SUSpQa",
+    "session_cwd": "/var/folders/4s/05_wctw12k33szskjcfrr1bc0000gn/T/agentsam-fs-e2e-SUSpQa",
+    "session_id": "pty_mugpalql_x93808",
+    "runtimeBaseUrl": "http://127.0.0.1:65149"
+  },
+  "pty_path": "NOTES.md",
+  "pty_marker": "PTY_MARK_1790325024020",
+  "stale_conflict": {
+    "ok": false,
+    "error": "version_conflict",
+    "code": "version_conflict",
+    "expected": "sha256:2b92ea252be0fbc26f70317cdaa7b6411ea634b50d55338cd8c495e4dbf25d1d",
+    "actual": "sha256:95e5f36ba91fce6c51078ba4948aa068fa9e33e213504318dfeea0ea80ece986",
+    "path": "NOTES.md"
+  },
+  "external_version_before": "sha256:2b92ea252be0fbc26f70317cdaa7b6411ea634b50d55338cd8c495e4dbf25d1d",
+  "external_version_after": "sha256:95e5f36ba91fce6c51078ba4948aa068fa9e33e213504318dfeea0ea80ece986",
+  "authorization": {
+    "binding": "127.0.0.1",
+    "capability_required": true,
+    "cors": "studio-origin-allowlist",
+    "arbitrary_root_claim": "rejected"
+  },
+  "scratch_vs_filesystem": {
+    "filesystem": "real FS + real PTY",
+    "scratch": "virtual files + virtual shell",
+    "silent_fallback": false
+  }
+}