@inneranimalmedia/agentsam-sdk 2.6.5 → 2.6.8

package/docs/REPO_FILE_MAP.txt

@@ -0,0 +1,132 @@
+AGENTSAM SDK - REPOSITORY FILE MAP
+=================================
+ASCII orientation map; logical map, not exhaustive per-file inventory.
+Scope: tracked layout. Generated, ignored, and machine-local content is omitted.
+Baseline evidence: repository audit on feat/public-package-graduation.
+Use git status / agentsam context for the current revision rather than treating
+this orientation map as revision authority.
+
+1. SYSTEM WIREFRAME
+-------------------
+
+  Consumer / developer
+       |
+       +--> README.md, DEVELOPMENT.md, docs/ -------- architecture, contracts, guidance
+       +--> bin/agentsam ------------------------------ CLI launcher
+       |      +--> src/cli + src/commands ----------- CLI composition
+       |      +--> src/index.* ----------------------- SDK public facade
+       |      +--> src/sam --------------------------- typed execution spine
+       |      `--> src/* ----------------------------- SDK domains and adapters
+       +--> package.json / package-lock.json --------- root npm product and lockfile
+              +--> packages/* ------------------------ reusable packages
+              +--> apps/* ---------------------------- product applications
+              `--> services/* ------------------------ service implementations
+
+  Shared vocabulary: protocol/* + contracts/* + packages/agentsam-contracts
+  Data schemas:      migrations/{runtime,sqlite,d1}
+  Provider seams:    src/providers, src/cloudflare, packages/connectors/*
+  Verification:      test/*, package-local tests, scripts/verify-* and npm gates
+
+2. TOP-LEVEL FILE MAP
+---------------------
+
+  /
+  |-- README.md, DEVELOPMENT.md, AGENTSAM.md, .agentsamrules
+  |      Product overview, contributor workflow, runtime/repo instructions.
+  |-- package.json, package-lock.json, tsconfig.base.json
+  |      Root package/workspaces, dependency lock, shared TypeScript settings.
+  |-- agentsam.yaml, .agentsam/config.json
+  |      Portable project config and host/install config (not run history).
+  |-- bin/                 CLI launchers
+  |-- src/                 ROOT SDK AND CLI IMPLEMENTATION
+  |   |-- index, cli, commands       Public facade and command composition
+  |   |-- sam, schemas, rpc, errors  Execution kernel and typed boundaries
+  |   |-- agent, models, providers   Agent/model/provider seams
+  |   |-- repository, context, indexing, knowledge
+  |   |-- security, local, local-fs, capabilities, tools
+  |   |-- cloudflare, plugins, features, skills, telemetry, eval
+  |   `-- lib/                      Legacy extraction zone (see SOURCE_ARCHITECTURE.md)
+  |-- packages/             REUSABLE PACKAGE BOUNDARIES
+  |   |-- contracts, errors, runtime-protocol
+  |   |-- identity, key-manager, vault, settings
+  |   |-- repository, knowledge, work-graph, work, workbench, queue-control, goap
+  |   |-- connectors/*, providers/*
+  |   |-- brand, content*, assets-core, cloudflare-images, scoring
+  |   |-- nav, shell-kit, desktop-shell, ide, database-editor
+  |   `-- theme-* / heuristic-theme / docs-theme
+  |       Examples/families, not an exhaustive package list.
+  |-- apps/                 PRODUCT APPLICATIONS
+  |   |-- local-studio, project-control, frontend, theme-gallery-preview
+  |   |-- cad-creator, client-cms-editor, ecommerce-cms-agentsam
+  |   |-- agentsam-go-worker, agentsamd
+  |   |-- church-site, companions-site, floors-site, fuelnfree-site,
+  |   |   handyman-site, insurance-site, shinshu-site
+  |   `-- _incoming/         Intake area
+  |       App-specific frontend/backend/shared code and deployment configs stay
+  |       with the app; see docs/architecture/AGENTSAM_APPLICATION_CONTRACT.md.
+  |-- services/              Standalone service areas (cad, knowledge)
+  |-- protocol/              Cross-system protocol definitions (SAM, runtime,
+  |   |                      repository, database, apps, skills, etc.)
+  |   `-- README.md           Ownership and host-adapter boundaries
+  |-- contracts/             Root-level contract artifacts
+  |-- migrations/            d1, runtime, sqlite migration families
+  |-- test/                  Root unit, CLI, integration, terminal, live, Go tests
+  |-- scripts/               Generation, verification, release, site, tooling
+  |-- python/                Python SDK/tooling, tests, docs
+  |-- native/                Native machine/runtime component(s)
+  |-- docs/                  Architecture, product, tools, ops, plans
+  |   |-- architecture/      System boundaries and architecture contracts
+  |   |-- product/           Lifecycle and UX standards
+  |   |-- tools/             Capability/tool references
+  |   `-- plans/             Dated plans/handoffs; not implementation SSOT
+  |-- skills/                Portable skill definitions
+  |-- templates/             Scaffolding templates
+  |-- registry/              Tool and domain registries
+  |-- examples/, assets/     Examples and shared assets
+  |-- sites/                 Public-site source/content
+  |-- focus-timer/           Separate tracked top-level mini-app/site
+  |-- .github/, .changeset/  CI workflows and release metadata
+  `-- tags/                  Repository tag metadata
+
+3. AUDIT / NAVIGATION NOTES
+---------------------------
+
+  * docs/SOURCE_ARCHITECTURE.md defines root src as the SDK/package composition
+    layer and calls src/lib a legacy extraction zone. Put new reusable modules in
+    a coherent owned package instead of adding unrelated code to src/lib.
+  * package.json explicitly enumerates root npm workspaces. Not every directory
+    under packages/ is necessarily a configured workspace: check before using
+    workspace commands or assuming it is published.
+  * protocol/, packages/agentsam-contracts, and root contracts/ are distinct
+    locations. Follow their local ownership docs instead of conflating them.
+  * Select the correct migration family and owning app/service before changing data
+    schemas. App-specific seeds and bindings belong with the consuming app.
+  * APP identity/validation: docs/architecture/AGENTSAM_APPLICATION_CONTRACT.md;
+    root gates are npm run app:validate / npm run guard:apps.
+  * Local filesystem discovery also surfaced folders such as generated/, .wrangler/,
+    level-1/, test2/, and agentsam-originalsetup-inspect/. They are omitted here:
+    this map describes tracked repository roots, not every local/ignored directory.
+  * Public package distribution is audited by agentsam package audit/status/verify/
+    publish-plan. A publishConfig alone is intent, not proof that a package is
+    consumer-ready.
+  * native/agentsam-machine is the Rust machine-perception workspace. Its CLI resolves
+    from PATH, a built repo binary, or a Cargo fallback; treat native distribution as
+    its own release lane rather than assuming the npm package publishes a native binary.
+  * This file is an orientation map, not implementation or release authority.
+
+4. QUICK TEST / RELEASE ENTRY POINTS
+------------------------------------
+
+  npm run test:standard       focused root test bundle
+  npm run test:workspaces     selected package tests/typechecks
+  npm run verify              broad SDK/package/app/boundary/package checks
+  npm run verify:release      verify + knowledge package + Python + release security
+  npm run app:validate        validate all product app manifests
+  agentsam package audit --public
+                            compare public intent with registry/quality state
+  agentsam package verify <name>
+                            run declared package gates + npm pack dry-run
+  agentsam package publish-plan
+                            dependency-ordered, read-only publication plan
+
+Use DEVELOPMENT.md and each package/app README for current, more detailed commands.

package/docs/THEME_REFINERY.md

@@ -2,7 +2,7 @@
 
 **Law:** discover ≠ promote · install ≠ activate · automation ≠ authority  
 **SSOT for registry:** live `inneranimalmedia-business` D1 (`agentsam_products` + `asset_relationships` + evidence/artifacts)  
-**SSOT for packages:** `agentsam-sdk` workspaces (`@inneranimalmedia/heuristic-theme`, `@inneranimalmedia/theme-*`)
+**SSOT for packages:** `agentsam-sdk` workspaces (`@inneranimalmedia/theme-heuristic`, `@inneranimalmedia/theme-*`)
 
 Python owns deterministic harvest/normalize/preview/QA. AgentSam owns interpretation. **Every meaningful product unit must reconcile into D1** — filesystem-only runs are incomplete.
 
@@ -113,7 +113,7 @@ discovered / matched / registered / updated / unchanged products · repositories
 
 | Package | Role |
 |---------|------|
-| `@inneranimalmedia/heuristic-theme` | Stock CMS `theme.storefront.shell` |
+| `@inneranimalmedia/theme-heuristic` | Stock CMS `theme.storefront.shell` |
 | `@inneranimalmedia/theme-<slug>` | Installable gallery theme contracts |
 | `apps/theme-gallery-preview` | Proving surface / historical mounts — not the package SSOT |
 

package/docs/architecture/AGENTSAM_RUNTIME_PROTOCOL.md

@@ -1,10 +1,10 @@
 # AgentSam Runtime Protocol
 
-> Branch: `feat/runtime-protocol-agentsamd`. Law: **agentsamd is the machine daemon; providers are adapters.**
+> Standing law: **`agentsam.runtime.v1` is the portable execution contract. `agentsamd` and ExecOS are supported runtime implementations/adapters; neither is a transport.**
 
 ## Architectural law
 
-**agentsamd is the AgentSam machine/runtime daemon. Providers are adapters beneath it.**
+**`agentsam.runtime.v1` is the execution authority. `agentsamd` is the stock portable machine daemon for independent installs; ExecOS is a proven managed/platform runtime and dispatcher used by InnerAnimalMedia. Runtime implementations sit behind the same connection/protocol model, and transports stay separate from them.**
 
 Physical D1 tables stay `terminal_*` for this generation. Domain nouns in code are `RuntimeInstance`, `RuntimeConnection`, `RuntimeAdapter`, `RuntimeCapabilities`.
 
@@ -12,7 +12,7 @@ Physical D1 tables stay `terminal_*` for this generation. Domain nouns in code a
 |---|---|
 | **agentsamd** | Lives with execution: exec, PTY, fs, processes, git, tools, capabilities, attach |
 | **Native helper** (this sprint) | Privileged companion under unprivileged Go: keychain, mounts, devices |
-| **EXECOS Worker** (`env.EXECOS` / `EXECOS_IAM`) | Interim cloud→machine hop + session/job writes. Becomes `runtime_adapter=execos_legacy`, then retires |
+| **ExecOS / EXECOS Worker** (`env.EXECOS` / `EXECOS_IAM`) | Supported managed/platform runtime + cloud→machine dispatch used by InnerAnimalMedia. Historical rows may use `runtime_adapter=execos_legacy`; that compatibility id does **not** imply a retirement decision. |
 | **PTY_SERVICE** | VPC/PTY health lane — not the daemon |
 | **agentsam-go-worker** | Optional hosted Go service (same Go core). **Not** the Studio control plane |
 | **Local Studio Worker** | Stock app host: auth, D1 SSOT, bindings, runtime APIs |
@@ -35,12 +35,30 @@ Examples:
 | lifecycle | persistent | persistent | ephemeral |
 | provider_product | (host) | compute_engine | sandbox |
 | protocol | agentsam.runtime.v1 | same | same |
-| runtime_adapter | agentsamd | agentsamd | cloudflare_sandbox |
+| runtime_adapter | agentsamd or ExecOS | agentsamd or ExecOS | cloudflare_sandbox |
 | transport | cloudflare_tunnel / direct_https | cloudflare_tunnel / vpc_service | service_binding |
 | auth_mode | connection_token | connection_token / platform_bridge | service_binding |
 
 **Forbidden:** `transport IN ('execos','container')` — those were adapter/substrate smuggled into transport.
 
+### ExecOS support status
+
+ExecOS is **supported working machinery**, not presumed deprecated. Current InnerAnimalMedia production/runtime paths still use it for governed dispatch, enrolled-device execution, bridge authentication, terminal/session routing, and `user_hosted_tunnel` flows.
+
+`execos_legacy` exists because earlier rows encoded `execos` as a transport and needed a compatibility mapping into the newer four-axis model. The word `legacy` in that identifier is migration vocabulary; it is **not** authorization to delete, disable, or silently replace ExecOS.
+
+The portability goal is additive:
+
+```text
+agentsam.runtime.v1
+        ├── agentsamd              stock portable/local runtime
+        ├── ExecOS                 supported managed/platform runtime
+        ├── cloudflare_sandbox     sandbox adapter
+        └── future adapters
+```
+
+Where implementations overlap, converge on protocol semantics and acceptance tests. A future deprecation is a separate, evidence-backed product decision.
+
 ---
 
 ## Runtime Registry (D1 spine — preserve)
@@ -57,7 +75,7 @@ ACCOUNT
        ▼
     terminal_connections         HOW AGENTSAM TALKS TO IT
        ├── protocol = agentsam.runtime.v1
-       ├── runtime_adapter = agentsamd | execos_legacy | …
+       ├── runtime_adapter = agentsamd | execos_legacy (ExecOS compatibility id) | …
        ├── transport = direct_https | cloudflare_tunnel | vpc_service | …
        ├── auth_mode
        ├── terminal_connection_credentials
@@ -118,16 +136,16 @@ system.inspect
 
 ## Migration priority
 
-1. Freeze vocabulary (this doc + `packages/runtime-protocol`)
-2. Rebuild `terminal_instances` (local_device→host)
-3. Rebuild `terminal_connections` (execos→`runtime_adapter=execos_legacy`)
-4. New enrollments default `runtime_adapter=agentsamd`, `protocol=agentsam.runtime.v1`
-5. `execos_run_id` → `runtime_run_id`
-6. Widen `cloud_provider_connections`
-7. Heartbeat fills `capabilities_json`, `provider_product`, lifecycle facts
-8. `agentsam setup runtime` writes these records from GOAP plans
-9. After agentsamd proven: migrate live ExecOS rows `execos_legacy` → `agentsamd`
-10. Keep ExecOS as adapter during cutover — never as the architecture
+1. Freeze vocabulary (this doc + `packages/runtime-protocol`).
+2. Rebuild `terminal_instances` (local_device→host).
+3. Normalize historical `transport=execos` records into **adapter + real transport** fields. Existing `runtime_adapter=execos_legacy` is a compatibility identifier for ExecOS-backed connections, not a support/deprecation state.
+4. Stock independent/local installs may default to `runtime_adapter=agentsamd`; managed/platform installs may continue to use ExecOS. Both remain valid registered runtimes.
+5. `execos_run_id` → protocol-neutral `runtime_run_id` where that column still encodes implementation detail.
+6. Widen `cloud_provider_connections`.
+7. Heartbeats fill `capabilities_json`, `provider_product`, and lifecycle facts from the selected runtime.
+8. `agentsam setup runtime` writes records from GOAP plans without assuming one runtime implementation.
+9. Prove overlapping ExecOS / agentsamd operations against the same `agentsam.runtime.v1` semantics instead of removing one merely because the other exists.
+10. Any future narrowing or retirement of ExecOS requires an explicit product decision, inventory of production callers, proven replacement parity, migration plan, acceptance tests, and approval.
 
 ---
 
@@ -144,8 +162,10 @@ system.inspect
 
 ## Success criteria
 
-- User123: Studio → `setup runtime` → enrolled agentsamd (+ native helper on host) → attach
-- Same protocol on Mac / GCP VM / Docker / CF Container; Sandbox via adapter
-- Transport changes without renaming the instance
-- D1 spine stays `terminal_*`; vocabulary is four-axis + adapter + transport
-- ExecOS is `execos_legacy` until retired; agentsamd is the computer
+- User123 can install Studio → `setup runtime` → enroll the stock `agentsamd` runtime (+ native helper where needed) → attach without InnerAnimalMedia infrastructure.
+- Existing InnerAnimalMedia ExecOS connections remain supported and functional while sharing protocol-neutral registry/session concepts.
+- Same protocol semantics can be implemented across Mac / GCP VM / Docker / CF Container; Sandbox remains an adapter.
+- Transport can change without renaming the instance or changing runtime/session semantics.
+- D1 spine stays `terminal_*`; vocabulary remains instance + adapter + transport + auth.
+- The historical string `execos_legacy` is treated as compatibility vocabulary only. **Do not infer support lifecycle from the identifier.**
+- Duplication between ExecOS and agentsamd is resolved by shared contracts/tests and explicit routing, not by deleting proven machinery without parity.

package/docs/content-studio/REVISION_GATE_2026-09-27.md

@@ -24,7 +24,7 @@ or a hardcoded provider — it is not finished.
    `protocol/assets/`) owns canonical asset identity (`ast_*`), machine facts,
    provenance and provider **representations**.
 
-3. **BrandPack** (`brand.pack.json` / `@inneranimalmedia/agentsam-sdk-brand`)
+3. **BrandPack** (`brand.pack.json` / `@inneranimalmedia/agentsam-brand`)
    owns the canonical brand system **AND brand-scoped assets**: logos, icons,
    fonts, imagery, video, models, themes, styles, tokens, motion, semantic
    roles and brand delivery rules. BrandPack does **not** own physical storage

package/docs/plans/LOCAL_STUDIO_DESKTOP_RELEASE_2026-09-29.md

@@ -0,0 +1,150 @@
+# Local Studio desktop release graduation — 2.6.6
+
+**Owner lane:** installed/downloadable Local Studio only
+**Branch:** `feat/local-studio-desktop-release-20260929`
+**Canonical UI:** `apps/local-studio`
+**Native shell:** `packages/agentsam-desktop-shell`
+**Do not absorb:** Agent 1's hosted Worker/CMS finishing work
+
+## Current verified baseline
+
+- The installed `/Applications/AgentSam Local Studio.app` is stale `2.6.5`.
+- `apps/local-studio` is already `2.6.6` and builds a real bundled desktop SPA.
+- `npm --prefix apps/local-studio run verify:desktop` passes.
+- `cargo check --manifest-path packages/agentsam-desktop-shell/src-tauri/Cargo.toml` passes.
+- The packaged `2.6.6` Tauri app launches and exposes the real Local Studio UI: navigation, Chat/Work, composer, model picker, and Send.
+- The current `2.6.6` DMG exists, but the app is ad-hoc signed; Gatekeeper rejects it.
+- This machine currently has no valid Apple code-signing identity and no Tauri updater private-key environment configured.
+- `agentsam-desktop-updates` is deployed, but updater checks fail because production D1 lacks `desktop_shell_releases`.
+- `updates.agentsam.dev` does not currently resolve.
+- `apps/local-studio/agentsam.app.json` still advertises an npm install for a private package. That install contract is stale.
+
+## Product law
+
+Local Studio desktop is not a website wrapper and not an npm package masquerading as an app.
+
+```text
+AgentSam Local Studio.app
+  -> bundled apps/local-studio SPA
+  -> Tauri native commands
+  -> agentsamd / SQLite / filesystem / keychain / identity adapters
+```
+
+The npm release and desktop release may share a version, but they are separate artifacts:
+
+```text
+@inneranimalmedia/agentsam-sdk  -> npm registry
+AgentSam Local Studio          -> signed/notarized native artifact + updater/download service
+```
+
+## Release gate 1 — source and native parity
+
+Required green checks:
+
+1. `npm --prefix apps/local-studio run verify:desktop`
+2. Local Studio typecheck/tests relevant to desktop and auth
+3. `npm --prefix packages/identity test`
+4. `cargo check` and `cargo test` for `agentsam-desktop-shell`
+5. Build the shell from the current Local Studio SPA, never from a recovery/bootstrap page
+6. Launch the packaged `.app` and confirm the Local Studio accessibility tree contains the real workspace
+7. Exercise native startup without blocking the work surface
+8. Exercise SQLite, local content/files, PTY/agentsamd, keychain/session restoration, and deep-link callback paths
+
+No release may proceed if the UI only works in Chrome while the packaged WebView is blank.
+
+## Release gate 2 — one version authority
+
+Before release, these must agree:
+
+- root SDK package version
+- `apps/local-studio/package.json`
+- `packages/agentsam-desktop-shell/manifests/local-studio.json`
+- generated Tauri config / bundle Info.plist
+- DMG filename
+- updater registry row
+
+For this graduation target, the intended version is `2.6.6`.
+
+## Release gate 3 — updater/download backend
+
+1. Apply `migrations/d1/0017_desktop_shell_releases.sql` to `inneranimalmedia-business`.
+2. Re-test `agentsam-desktop-updates` updater lookup; missing table must be gone.
+3. Keep one backend: D1 release metadata + R2 artifact bytes.
+4. Decide the canonical public updater hostname and make it resolve. Do not leave Tauri configured to a dead hostname.
+5. Publish immutable release artifacts under:
+   `native/release/local-studio/<target>/<arch>/<version>/<filename>`.
+6. Registry rows must point at the exact downloadable artifact and include a valid Tauri updater signature.
+
+## Release gate 4 — signing and notarization
+
+A public macOS build is not complete while `codesign` reports `Signature=adhoc` or `spctl` rejects it.
+
+Required for release channel:
+
+- Developer ID Application signing identity
+- hardened-runtime-compatible signing through Tauri
+- Apple notarization
+- stapled notarization ticket where applicable
+- `codesign --verify --deep --strict` passes
+- `spctl -a -vv` accepts the final app copied from the DMG
+- Tauri updater private key available at build time and `.sig` generated
+
+Unsigned/ad-hoc artifacts may only be used in a clearly named test lane.
+
+## Release gate 5 — installer and CLI contract
+
+`agentsam app install local-studio` must stop advertising `npm install @inneranimalmedia/agentsam-local-studio`.
+
+Target behavior:
+
+1. resolve OS + architecture;
+2. resolve the current release artifact from the desktop release service;
+3. present/download the native installer for that platform;
+4. keep source/npm installation separate from native application installation;
+5. fail visibly when no signed release exists.
+
+The hosted `/install/studio` route must not claim to install Local Studio while it only installs the SDK CLI.
+
+## Release gate 6 — clean-machine acceptance
+
+For macOS 2.6.6:
+
+1. download the release DMG through the public release URL;
+2. mount the DMG;
+3. copy `AgentSam Local Studio.app` to `/Applications`;
+4. launch the copied app, not the build-tree app;
+5. confirm real Local Studio shell renders;
+6. confirm signed-out local usage remains available;
+7. test AgentSam account login/session restore through the shared IAM authority;
+8. test local filesystem/content, SQLite/database UI, terminal/PTY, and agentsamd;
+9. restart the app and verify state/session restoration;
+10. confirm updater check works from an older known build.
+
+## Release gate 7 — npm SDK release
+
+Only after desktop acceptance is green:
+
+1. reconcile root SDK version to `2.6.6`;
+2. run the full npm release verification gates;
+3. `npm pack` and inspect the consumer artifact;
+4. publish `@inneranimalmedia/agentsam-sdk@2.6.6`;
+5. verify npm `latest` points to the intended version;
+6. verify CLI `agentsam app install local-studio` resolves the native app release rather than a private npm package.
+
+## Hosted/web Agent 1 handoff boundary
+
+Agent 1 owns the hosted `agentsam.inneranimalmedia.com` completion lane: marketing/download surface, hosted `/agentsam`, CMS, and web routing. Desktop work may consume the final public download/updater hostname but must not revert to a hosted WebView as its application runtime.
+
+## Hard stop conditions
+
+Do not call the desktop release complete if any of these are true:
+
+- installed app opens blank;
+- packaged app is only a website redirect;
+- version sources disagree;
+- updater endpoint returns 5xx;
+- download URL is dead;
+- updater signature is absent;
+- Gatekeeper rejects the release artifact;
+- CLI advertises a private/unpublished npm package as the desktop installer;
+- native local features require a hosted login page just to render the app.

package/migrations/d1/0017_identity_native_oauth.sql

@@ -0,0 +1,21 @@
+-- Native (desktop) OAuth handoff for the portable identity package.
+-- Additive only: browser OAuth keeps working before and after this applies.
+-- auth_sessions.type already exists in live D1 (DEFAULT 'browser').
+
+ALTER TABLE identity_oauth_states ADD COLUMN client_type TEXT;
+ALTER TABLE identity_oauth_states ADD COLUMN native_challenge TEXT;
+ALTER TABLE identity_oauth_states ADD COLUMN native_redirect TEXT;
+
+-- Single-use, PKCE-bound pickup of a desktop session. Only the sha256 of the
+-- handoff code is stored; the session id never appears in a URL.
+CREATE TABLE IF NOT EXISTS identity_native_handoffs (
+  handoff_hash TEXT PRIMARY KEY,
+  session_id   TEXT NOT NULL,
+  challenge    TEXT NOT NULL,
+  expires_at   INTEGER NOT NULL,
+  created_at   INTEGER NOT NULL,
+  consumed_at  INTEGER
+);
+
+CREATE INDEX IF NOT EXISTS idx_identity_native_handoffs_expires
+  ON identity_native_handoffs(expires_at);

package/migrations/d1/0018_goap_control_plane_remaster.sql

@@ -0,0 +1,40 @@
+-- 0018_goap_control_plane_remaster.sql
+-- Additive ticket/event contract remaster only: no new GOAP table family.
+--
+-- This migration intentionally targets tables owned by the portable D1/SQLite
+-- control-plane baseline (0010) and equivalent legacy host tables.
+-- Blackboard/workspace state is a runtime concern and is evolved separately by
+-- migrations/runtime/0002_goap_blackboard_v1.sql.
+--
+-- NOTE: account_id/repository_id are intentionally NOT added to ticket_events here.
+-- Portable 0010 already has them, while the legacy platform table does not.
+-- The GOAP adapter supports eventOwnership=ticket_join for that host shape until a
+-- dedicated platform-only ownership repair is intentionally applied.
+
+ALTER TABLE agentsam_tickets
+  ADD COLUMN goal_schema TEXT;
+
+ALTER TABLE agentsam_tickets
+  ADD COLUMN goal_spec_json TEXT
+    CHECK (goal_spec_json IS NULL OR json_valid(goal_spec_json));
+
+ALTER TABLE agentsam_ticket_events
+  ADD COLUMN payload_json TEXT NOT NULL DEFAULT '{}'
+    CHECK (json_valid(payload_json));
+
+ALTER TABLE agentsam_ticket_events
+  ADD COLUMN workflow_run_id TEXT;
+
+ALTER TABLE agentsam_ticket_events
+  ADD COLUMN execution_step_id TEXT;
+
+ALTER TABLE agentsam_ticket_events
+  ADD COLUMN schema_version TEXT NOT NULL DEFAULT 'agentsam.event.v1';
+
+CREATE INDEX IF NOT EXISTS idx_agentsam_ticket_events_workflow_run
+  ON agentsam_ticket_events(workflow_run_id, created_at)
+  WHERE workflow_run_id IS NOT NULL;
+
+CREATE INDEX IF NOT EXISTS idx_agentsam_ticket_events_execution_step
+  ON agentsam_ticket_events(execution_step_id, created_at)
+  WHERE execution_step_id IS NOT NULL;

package/migrations/d1/0019_agentsam_agent_run_plan_todo.sql

@@ -0,0 +1,14 @@
+-- 0019_agentsam_agent_run_plan_todo.sql
+-- Attribute remote AgentSam run attempts to the durable plan/TODO that caused them.
+-- This mirrors migrations/runtime/0004_agent_run_plan_linkage.sql for local SQLite.
+ALTER TABLE agentsam_agent_run
+  ADD COLUMN plan_id TEXT REFERENCES agentsam_plans(id) ON DELETE SET NULL;
+
+ALTER TABLE agentsam_agent_run
+  ADD COLUMN todo_id TEXT REFERENCES agentsam_todo(id) ON DELETE SET NULL;
+
+CREATE INDEX IF NOT EXISTS idx_agentsam_agent_run_plan
+  ON agentsam_agent_run(account_id, plan_id, created_at_unix DESC);
+
+CREATE INDEX IF NOT EXISTS idx_agentsam_agent_run_todo
+  ON agentsam_agent_run(account_id, todo_id, created_at_unix DESC);

package/migrations/d1/README_PORTABLE_CONTROL_PLANE.md

@@ -1,16 +1,27 @@
-# Portable control-plane schemas (tickets · memory · skills · tools)
+# Portable control-plane schemas (tickets · memory · skills · tools · GOAP)
 
-Apply from the repo that owns the SQL (agentsam-sdk `migrations/d1/`).
+Apply schema families from the repo that owns them. Portable D1/ticket state and
+runtime blackboard state have different baselines and must not pretend to share
+one migration history.
 
 | File | Purpose |
 |------|---------|
-| `0010_portable_tickets_memory.sql` | Account-owned `agentsam_tickets` + events + `agentsam_memory` + outbox. `account_id` + `repository_id` **NOT NULL**. |
-| `0011_agentsam_skill_v2.sql` | Skill identity · metrics · retrieval (3-table redesign). Legacy hosts: rename old → `agentsam_skill_legacy`, backfill, verify. |
-| `0012_agentsam_tools_required_seed.sql` | Idempotent seed of required `tool_key` rows for GOAP / multitask. Manifest: `registry/tools/required-seed.json`. |
+| 0010_portable_tickets_memory.sql | Account-owned agentsam_tickets + events + agentsam_memory + outbox. account_id + repository_id NOT NULL for portable installs. |
+| 0011_agentsam_skill_v2.sql | Skill identity · metrics · retrieval (3-table redesign). Legacy hosts: rename old -> agentsam_skill_legacy, backfill, verify. |
+| 0012_agentsam_tools_required_seed.sql | Idempotent seed of required tool_key rows for GOAP / multitask. Manifest: registry/tools/required-seed.json. |
+| 0018_goap_control_plane_remaster.sql | Additive ticket/event contract remaster: structured goal spec, structured event payloads, workflow/action linkage. No new GOAP table family and no dependency on runtime workspace tables. |
+| migrations/runtime/0002_goap_blackboard_v1.sql | Evolves agentsam_workspace_state after runtime/0001 with blackboard schema identity + CAS revision. |
 
 ## Law
 
-- **NULL `repository_id` on memory/ticket writes = broken implementation.** Resolve repo identity from `agentsam inspect` / snapshot before insert.
-- Customer tickets use **their** D1/SQLite — never IAM host ticket rows.
-- `agentsam_autorag` stays registered for A* planning even while multi-level retrieval is incomplete.
-- Skill publish uniqueness: partial unique on `slash_trigger WHERE is_published = 1` is included.
+- NULL repository_id on portable memory/ticket/event writes = broken implementation. Resolve repo identity from agentsam inspect / snapshot before insert.
+- Customer tickets and GOAP state use their D1/SQLite (or another adapter-owned store) — never IAM host ticket rows as an SDK requirement.
+- Logical GOAP contracts live in @inneranimalmedia/agentsam-goap; storage tables are adapter details.
+- GOAP errors use @inneranimalmedia/agentsam-errors and the shared error catalog. GOAP does not own a parallel error taxonomy.
+- Cross-store GOAP mutations use an atomic MutationPort. Do not sequence ticket/blackboard/event writes independently.
+- Existing workflow/execution/approval tables remain the plan/run/action/approval authorities. Do not create parallel GOAP graph tables.
+- Goal focus is not execution. Creating, selecting, or activating a goal must not fabricate an agentsam_agent_run. Link a run only after the execution subsystem actually creates one.
+- Portable ticket_events already has account_id + repository_id. Legacy platform event ownership is resolved through ticket_join until a host-only repair is intentionally applied.
+- Portable/account-owned runtime stores may scope blackboards by repository. Shared platform stores must verify repository ownership through their repository authority (for IAM D1: code_repositories.account_id).
+- agentsam_autorag stays registered for A* planning even while multi-level retrieval is incomplete.
+- Skill publish uniqueness: partial unique on slash_trigger WHERE is_published = 1 is included.

package/migrations/runtime/0002_goap_blackboard_v1.sql

@@ -0,0 +1,15 @@
+-- 0002_goap_blackboard_v1.sql
+-- Runtime blackboard contract evolution for D1/SQLite-compatible stores.
+-- agentsam_workspace_state is created by 0001_cli_runtime.sql.
+--
+-- The revision is the portable optimistic-concurrency/CAS fence.
+-- state_schema freezes the logical payload contract independently from storage.
+
+ALTER TABLE agentsam_workspace_state
+  ADD COLUMN state_schema TEXT NOT NULL DEFAULT 'agentsam.blackboard.v1';
+
+ALTER TABLE agentsam_workspace_state
+  ADD COLUMN revision INTEGER NOT NULL DEFAULT 1 CHECK (revision > 0);
+
+CREATE INDEX IF NOT EXISTS idx_agentsam_workspace_state_repo_revision
+  ON agentsam_workspace_state(repository_id, revision);

package/migrations/runtime/0004_agent_run_plan_linkage.sql

@@ -0,0 +1,8 @@
+-- Attribute every runtime attempt to the durable plan/TODO that caused it.
+ALTER TABLE agentsam_agent_run ADD COLUMN plan_id TEXT REFERENCES agentsam_plans(id) ON DELETE SET NULL;
+ALTER TABLE agentsam_agent_run ADD COLUMN todo_id TEXT REFERENCES agentsam_todo(id) ON DELETE SET NULL;
+
+CREATE INDEX IF NOT EXISTS idx_agentsam_agent_run_plan
+  ON agentsam_agent_run(plan_id, created_at_unix DESC);
+CREATE INDEX IF NOT EXISTS idx_agentsam_agent_run_todo
+  ON agentsam_agent_run(todo_id, created_at_unix DESC);