{
  "$schema": "https://github.com/ta-amps/ta-amps-hackathon/blob/main/hackathon/agents/schemas/architecture.schema.json",
  "schema_version": 1,
  "name": "tessera",
  "summary": "Tessera: a single-node atomic work queue and atomic store for AI agent swarms where everything is either a verb (a small unit of work: every task a tile, claimed once, finished once, receipted) or a noun (versioned records with compare-and-set and content-addressed blobs), giving swarms clear organization, reusability, and a safe way to pick up shared work. Many agents share one backlog safely: leases with heartbeats and a hard cap, fencing tokens, idempotent submits with receipts, retries then dead letters, split and merge, one counts record, and an append-only event log. Agents connect over HTTP, MCP, web forms or a CLI. It knows nothing about any domain and never calls a model itself.",
  "status": {
    "as_of": "2026-10-28",
    "stage": "prototype",
    "notes": "Tracked anonymous demo sessions and account-bound keys share scoped HTTP/MCP routes, durable audit records, read-only public observer and generated access schemas. The spec remains a draft."
  },
  "docs": {
    "summary": "docs/summary.md",
    "architecture": "docs/architecture.md",
    "setup": "docs/setup.md",
    "comparison": "docs/comparison.md",
    "generalizing": "docs/generalizing.md",
    "decisions": "docs/decisions.md",
    "glossary": "docs/glossary.md",
    "review": "docs/review.md",
    "spec": "conformance-draft/SPEC.md",
    "operations": "docs/operations.md",
    "expansion": "docs/expansion.md",
    "opencode_ollama": "docs/opencode-and-ollama.md",
    "making_of": "docs/making-of.md",
    "handoff": "docs/handoff.md",
    "access_modes": "docs/access-modes.md",
    "frontier_publication": "docs/frontier-publication.md",
    "work_design_and_evidence": "docs/work-design-and-evidence.md",
    "work_routing": "docs/work-routing.md"
  },
  "read_order": [
    "README.md",
    "docs/summary.md",
    "docs/architecture.md",
    "conformance-draft/SPEC.md",
    "docs/setup.md",
    "docs/access-modes.md",
    "docs/expansion.md",
    "docs/opencode-and-ollama.md",
    "docs/comparison.md",
    "docs/generalizing.md",
    "docs/decisions.md",
    "docs/glossary.md",
    "docs/review.md",
    "docs/operations.md",
    "docs/making-of.md",
    "docs/handoff.md",
    "AGENTS.md"
  ],
  "commands": {
    "setup": "make setup",
    "check": "make check",
    "test": "make test",
    "suite": "make suite BACKEND=store",
    "suite_stub": "make suite-stub",
    "suite_http": "make suite-http-local",
    "run": "make dev",
    "run_public": "make dev TUNNEL=1",
    "seed": "make seed",
    "expand_demo": "make expand-demo",
    "bilateral_demo": "make bilateral-demo",
    "architecture": "make architecture",
    "index": "make index",
    "access_schema": "python3 scripts/build_access_openapi.py --check",
    "ontology_catalog": "python3 scripts/build_ontology_catalog.py --check"
  },
  "components": [
    {
      "id": "models",
      "title": "Models",
      "path": "src/tessera/models.py",
      "kind": "library",
      "domain": "neutral",
      "role": "Pydantic records that cross the boundary: what callers send and what every backend returns"
    },
    {
      "id": "errors",
      "title": "Errors",
      "path": "src/tessera/errors.py",
      "kind": "library",
      "domain": "neutral",
      "role": "One exception per problem code, each mapped to one HTTP status"
    },
    {
      "id": "receipts",
      "title": "Receipts",
      "path": "src/tessera/receipts.py",
      "kind": "library",
      "domain": "neutral",
      "role": "Canonical JSON and the receipt hash",
      "tests": [
        "tests/test_phase4_atomicity_and_vectors.py::test_l26_receipt_vectors_python_and_cloudflare_edge_node_parity"
      ]
    },
    {
      "id": "clock",
      "title": "Clock",
      "path": "src/tessera/clock.py",
      "kind": "library",
      "domain": "neutral",
      "role": "Time source; tests inject a fake clock"
    },
    {
      "id": "grants",
      "title": "Key grants",
      "path": "src/tessera/grants.py",
      "kind": "library",
      "domain": "neutral",
      "role": "What a key may do (queues, kinds, effect classes, scopes) and the rules that narrow a request to it; pure policy shared by the store and every door",
      "depends_on": [
        "models"
      ]
    },
    {
      "id": "store",
      "title": "Store",
      "kind": "library",
      "domain": "neutral",
      "path": [
        "src/tessera/store.py",
        "src/tessera/_base.py",
        "src/tessera/_tasks.py",
        "src/tessera/_graph.py",
        "src/tessera/_jobs.py",
        "src/tessera/_keys.py",
        "src/tessera/_observe.py",
        "src/tessera/_storage.py",
        "src/tessera/_buckets.py",
        "src/tessera/_intelligence.py",
        "src/tessera/schema.sql",
        "src/tessera/_principals.py",
        "src/tessera/_publication_guard.py",
        "src/tessera/_frontier_guard.py"
      ],
      "role": "The reference backend and the only place state changes: queues, the five verbs, park and resume, dependencies, retries, automatic dead-end tombstones, split, model jobs, keys, counts, events, health, queryable CAS records, content-addressed blobs, versioned named file buckets, 0-call progressive L0 scent search, monotonic delta feeds and dual-resolution reflex recall, each operation one IMMEDIATE transaction",
      "depends_on": [
        "clock",
        "errors",
        "grants",
        "models",
        "receipts"
      ],
      "interfaces": [
        "library"
      ],
      "tests": [
        "conformance-draft/test_queue_semantics.py",
        "conformance-draft/test_storage.py",
        "conformance-draft/test_model_jobs.py",
        "conformance-draft/test_task_graph.py",
        "tests/test_buckets.py",
        "tests/test_intelligence.py",
        "tests/test_governance_and_isolation.py",
        "tests/test_phase4_atomicity_and_vectors.py",
        "tests/test_frontier_publication.py",
        "tests/test_blob_first_uploader.py"
      ]
    },
    {
      "id": "backend",
      "title": "Backend protocol",
      "path": "src/tessera/backend.py",
      "kind": "library",
      "domain": "neutral",
      "role": "The contract every backend meets: Store, Client and any adapter",
      "depends_on": [
        "models"
      ]
    },
    {
      "id": "client",
      "title": "HTTP client",
      "path": "src/tessera/client.py",
      "kind": "library",
      "domain": "neutral",
      "role": "A Backend over HTTP, so callers switch between store and service with one setting",
      "depends_on": [
        "models",
        "errors"
      ],
      "interfaces": [
        "library"
      ]
    },
    {
      "id": "bridge",
      "title": "Surface bridge wrapper",
      "path": "src/tessera/bridge.py",
      "kind": "library",
      "domain": "neutral",
      "role": "Reusable Surface Handshake v1.0 wrapper for stateless product frontends: negotiates clamped limits, isolates <surface_id>.* CAS writes, polls/publishes live delta feeds, and optionally shims outbound LLM requests via middleware while keeping transactional DBs exempt",
      "depends_on": [
        "backend",
        "errors",
        "models"
      ],
      "interfaces": [
        "library"
      ],
      "tests": [
        "tests/test_handshake_and_bridge.py"
      ]
    },
    {
      "id": "ontology",
      "title": "Categorized Ontology, Ranking, Fragility & Reconciliation",
      "path": [
        "src/tessera/ontology/__init__.py",
        "src/tessera/ontology/categories.py",
        "src/tessera/ontology/rankings.py",
        "src/tessera/ontology/fragility.py",
        "src/tessera/ontology/reconcile.py",
        "src/tessera/ontology/profiles.py"
      ],
      "kind": "library",
      "domain": "neutral",
      "role": "20 canonical Noun categories, 18 canonical Verb categories, Empirical-Bayes/Dirichlet/Wilson/Pareto rankings, exponential fragility decay and recheck planning, 0-call 3-way CAS merge, explicit nonpersistent ballot simulations, and 8 CallerProfile adaptive lenses",
      "tests": [
        "tests/test_ontology_and_reconcile.py"
      ]
    },
    {
      "id": "observations",
      "title": "Execution observations and problem fingerprints",
      "path": [
        "src/tessera/observations.py",
        "src/tessera/fingerprints.py",
        "deploy/cloudflare/execution_observations.js"
      ],
      "kind": "library",
      "domain": "neutral",
      "role": "Core infrastructure for learning without learning policy: the optional report.learning block check, the bounded execution-observation-v1 view behind GET /v1/executions, and pure exact/MinHash fingerprint functions with shared Python/Worker vectors",
      "tests": [
        "tests/test_execution_learning_vectors.py",
        "tests/test_execution_learning.py",
        "tests/workerd_execution_learning.mjs"
      ]
    },
    {
      "id": "learners",
      "title": "Swappable learners",
      "path": [
        "src/tessera/learners/__init__.py",
        "src/tessera/learners/contract.py",
        "src/tessera/learners/catalog.py",
        "src/tessera/learners/runtime.py",
        "src/tessera/learners/stats.py",
        "src/tessera/learners/memory.py",
        "src/tessera/learners/path_statistics.py",
        "src/tessera/learners/routing.py",
        "src/tessera/learners/worker.py",
        "src/tessera/learners/pack.py",
        "tools/learner.py"
      ],
      "kind": "library",
      "domain": "neutral",
      "role": "Learner-spec and config nouns, deterministic learner run verbs over the public client contract, the memory (MinHash index and recall), path-statistics and routing-weights learners, and an inert seed-pack export; core never imports it",
      "tests": [
        "tests/test_execution_learning.py"
      ]
    },
    {
      "id": "service",
      "title": "HTTP service",
      "path": [
        "src/tessera/service.py",
        "src/tessera/_service_buckets.py",
        "src/tessera/_service_intelligence.py",
        "src/tessera/access.py",
        "src/tessera/_access_boundary.py",
        "src/tessera/_access_models.py",
        "src/tessera/_access_routes.py",
        "src/tessera/_access_schema.py"
      ],
      "kind": "service",
      "domain": "neutral",
      "role": "FastAPI app: routes, problem+json and the reaper loop; access.py holds what every door shares: settings, the claim limiter, the bearer key and the Gate",
      "depends_on": [
        "errors",
        "grants",
        "mcp-door",
        "models",
        "ontology",
        "pages",
        "store"
      ],
      "interfaces": [
        "http"
      ],
      "tests": [
        "tests/test_service.py",
        "tests/test_governance_and_isolation.py",
        "tests/test_phase4_atomicity_and_vectors.py",
        "tests/test_ontology_and_reconcile.py",
        "conformance-draft/test_service_surface.py"
      ]
    },
    {
      "id": "mcp-door",
      "title": "MCP door",
      "path": [
        "src/tessera/mcp_door.py",
        "src/tessera/_mcp_storage.py",
        "src/tessera/_mcp_access.py"
      ],
      "kind": "service",
      "domain": "neutral",
      "role": "MCP server over Streamable HTTP at /mcp: verb tools (queues, enqueue, claim, heartbeat, submit, split, park, resume), 0-call progressive L0 discovery & reflex tools (search_nouns, match_reflex, list_feeds, poll_feed, publish_feed), queryable CAS noun tools (list_stores, list_records, put_record, put_records, get_record, record_history) and persistent named bucket tools (define_bucket, buckets, put_object, get_object, list_objects, object_history), behind the same keys and Gate",
      "depends_on": [
        "errors",
        "grants",
        "models",
        "store"
      ],
      "interfaces": [
        "mcp"
      ],
      "tests": [
        "tests/test_service.py::test_the_mcp_door",
        "tests/test_service.py::test_mcp_door_enqueues_verbs_and_writes_cas_nouns",
        "tests/test_buckets.py::test_http_client_mcp_and_admin_keys_for_buckets",
        "conformance-draft/test_service_surface.py::test_T11_an_mcp_client_can_claim_and_submit"
      ]
    },
    {
      "id": "pages",
      "title": "Agent pages",
      "path": [
        "src/tessera/pages.py",
        "src/tessera/_access_contract.py"
      ],
      "kind": "web",
      "domain": "neutral",
      "role": "/connect, /llms.txt, /llms-full.txt, /favicon.svg, agent card, robots, the read-only Console Board v2 and keyed /work forms",
      "depends_on": [
        "errors",
        "grants",
        "models",
        "store"
      ],
      "interfaces": [
        "web"
      ],
      "tests": [
        "tests/test_service.py::test_the_agent_door",
        "tests/test_service.py::test_web_forms_never_echo_the_key",
        "tests/test_board.py",
        "tests/test_agent_tool_listings.py::test_python_pages_list_exactly_the_served_tools"
      ]
    },
    {
      "id": "cli",
      "title": "CLI",
      "path": "src/tessera/cli.py",
      "kind": "cli",
      "domain": "neutral",
      "role": "The tessera command: every verb on a shared SQLite file, plus serve and keys",
      "depends_on": [
        "store",
        "service",
        "models",
        "errors"
      ],
      "interfaces": [
        "cli"
      ]
    },
    {
      "id": "suite",
      "title": "Conformance suite",
      "path": [
        "conformance-draft",
        "src/tessera/testing.py"
      ],
      "kind": "tests",
      "domain": "neutral",
      "role": "SPEC.md, receipt_vectors.json and tests T01 to T22, ST01 to ST04, run against any backend by factory name",
      "depends_on": [
        "backend",
        "store",
        "client"
      ]
    },
    {
      "id": "edge",
      "title": "Cloud Worker & Edge",
      "path": [
        "deploy/cloudflare/worker.js",
        "deploy/cloudflare/cloud_store.js",
        "deploy/cloudflare/cloud_buckets.js",
        "deploy/cloudflare/cloud_intelligence.js",
        "deploy/cloudflare/cloud_mcp.js",
        "deploy/cloudflare/cloud_pages.js",
        "deploy/cloudflare/ontology_engine.js",
        "deploy/cloudflare/d1-fabric.sql",
        "deploy/cloudflare/d1-buckets.sql",
        "deploy/cloudflare/wrangler.jsonc",
        "deploy/cloudflare/cloud_access.js",
        "deploy/cloudflare/cloud_access_routes.js",
        "deploy/cloudflare/cloud_publication.js",
        "deploy/cloudflare/access_openapi.json",
        "deploy/cloudflare/ontology_catalog.js",
        "deploy/cloudflare/cloud_frontier_publication.js",
        "deploy/cloudflare/cloud_library.js",
        "deploy/cloudflare/library_checks.js",
        "deploy/cloudflare/library_contract.js",
        "deploy/cloudflare/cloud_a2a.js"
      ],
      "kind": "edge",
      "domain": "neutral",
      "role": "24/7 native cloud execution on Cloudflare SQLite Durable Objects (TesseraCoordinator) + Cloudflare D1 (ta-amps-fabric and ta-amps-buckets) + Streamable HTTP /mcp, with optional STORAGE_MODE=origin reverse-proxy fallback",
      "depends_on": [
        "service"
      ],
      "tests": [
        "tests/workerd_blob_first_uploader.mjs",
        "tests/test_board.py::test_cloudflare_pages_parity",
        "tests/test_phase4_atomicity_and_vectors.py::test_l26_receipt_vectors_python_and_cloudflare_edge_node_parity",
        "tests/workerd_agent_tool_listings.mjs"
      ]
    },
    {
      "id": "tools",
      "title": "Worker tools",
      "path": [
        "tools/seed.py",
        "tools/load_briefs.py",
        "tools/muse_worker.py",
        "tools/swarm_expander.py",
        "tools/meta_open_bridge.py",
        "tools/opencode_bilateral.py"
      ],
      "kind": "worker",
      "domain": "specific",
      "role": "Seed queues, seed nouns and keys; queue briefs whose dependencies are done; run one Muse Code worker on one brief; expand seed nouns into reviewed canonical nouns via Meta's Model API",
      "depends_on": [
        "client",
        "store"
      ],
      "tests": [
        "tests/test_tools.py"
      ]
    }
  ],
  "interfaces": [
    {
      "id": "http",
      "kind": "http",
      "served_by": "service",
      "spec": "conformance-draft/SPEC.md",
      "auth": "Bearer key; Idempotency-Key header on enqueue and submit; optional X-Namespace and X-Surface-Id headers",
      "entry_points": [
        "POST /v1/queues/define",
        "GET /v1/queues",
        "POST /v1/tasks",
        "GET /v1/tasks/{id}",
        "GET /v1/tasks/{id}/results",
        "POST /v1/tasks/claim",
        "POST /v1/tasks/heartbeat",
        "POST /v1/tasks/submit",
        "POST /v1/tasks/split",
        "POST /v1/tasks/park",
        "POST /v1/tasks/resume",
        "POST /v1/tasks/cancel",
        "POST /v1/admin/reap",
        "GET /v1/counts",
        "GET /v1/health",
        "GET /api/health",
        "GET /v1/events",
        "POST /v1/jobs",
        "POST /v1/jobs/{id}",
        "GET /v1/jobs",
        "GET /v1/stores",
        "GET /v1/stores/{store}/records",
        "POST /v1/stores/{store}/records/{key}",
        "POST /v1/stores/batch",
        "GET /v1/stores/{store}/records/{key}",
        "GET /v1/stores/{store}/records/{key}/history",
        "POST /v1/buckets/define",
        "GET /v1/buckets",
        "GET /v1/buckets/{bucket}/objects",
        "POST /v1/buckets/{bucket}/objects/{key}",
        "GET /v1/buckets/{bucket}/objects/{key}",
        "GET /v1/search",
        "GET /v1/feeds",
        "GET /v1/feeds/{feed}",
        "POST /v1/feeds/{feed}",
        "GET /v1/reflexes/match",
        "POST /v1/handshake",
        "POST /v1/blobs",
        "GET /v1/blobs/{sha256}",
        "/ns/{namespace}/v1/*"
      ]
    },
    {
      "id": "mcp",
      "kind": "mcp",
      "served_by": "mcp-door",
      "spec": "conformance-draft/SPEC.md",
      "auth": "Bearer key",
      "entry_points": [
        "POST /mcp (Streamable HTTP): tools queues, enqueue, claim, heartbeat, submit, split, park, resume, search_nouns, match_reflex, handshake, list_feeds, poll_feed, publish_feed, list_stores, list_records, put_record, put_records, get_record, record_history, define_bucket, buckets, put_object, get_object, list_objects, object_history"
      ]
    },
    {
      "id": "web",
      "kind": "web",
      "served_by": "pages",
      "auth": "None for pages; the key typed into each /work form",
      "entry_points": [
        "/connect",
        "/llms.txt",
        "/llms-full.txt",
        "/favicon.svg",
        "/.well-known/agent-card.json",
        "/robots.txt",
        "/board",
        "/work",
        "/work/resume"
      ]
    },
    {
      "id": "cli",
      "kind": "cli",
      "served_by": "cli",
      "auth": "Access to the SQLite file",
      "entry_points": [
        "tessera init|define|enqueue|claim|heartbeat|submit|split|park|resume|cancel|reap|counts|health|queues|events|task|results|serve|keys|version"
      ]
    },
    {
      "id": "library",
      "kind": "library",
      "served_by": "store",
      "auth": "In process",
      "entry_points": [
        "tessera.Store",
        "tessera.client.Client",
        "tessera.bridge.SurfaceBridge",
        "tessera.backend.Backend"
      ]
    }
  ],
  "data_stores": [
    {
      "id": "sqlite",
      "kind": "sqlite (WAL, busy_timeout 30 s)",
      "owned_by": "store",
      "path": "src/tessera/schema.sql",
      "location": "TESSERA_DB, default .tessera/tessera.db; /data on the Fly volume",
      "holds": [
        "queues",
        "tasks",
        "task_deps",
        "task_inputs",
        "leases",
        "results",
        "keys (hashed)",
        "jobs",
        "events",
        "counts",
        "records",
        "record_heads",
        "blobs",
        "blob_namespaces",
        "blob_uploaders",
        "buckets",
        "bucket_objects",
        "bucket_object_versions",
        "feed_entries",
        "noun_tags",
        "meta"
      ]
    }
  ],
  "boundaries": [
    {
      "id": "internet-edge",
      "between": [
        "internet",
        "edge"
      ],
      "rule": "TLS; cookies and hop-by-hop headers stripped; writes never cached",
      "enforced_by": "deploy/cloudflare/worker.js"
    },
    {
      "id": "edge-origin",
      "between": [
        "edge",
        "service"
      ],
      "rule": "With TESSERA_EDGE_SECRET set, every request except the health checks needs a matching x-edge-auth (constant-time compare), else 403",
      "enforced_by": "src/tessera/service.py",
      "checked_by": [
        "tests/test_service.py::test_the_edge_lock"
      ]
    },
    {
      "id": "caller-service",
      "between": [
        "agent",
        "service"
      ],
      "rule": "Bearer key scoped to queues, kinds, effect classes, surfaces and admin or store; per-key claim rate limit; writes are POST-only; write-repo and public require admin; resuming requires the task's effect class; a key may depend only on tasks in queues it can use",
      "enforced_by": [
        "src/tessera/service.py",
        "src/tessera/_keys.py"
      ],
      "checked_by": [
        "conformance-draft/test_service_surface.py::test_T01_keys_are_required",
        "conformance-draft/test_service_surface.py::test_T02_writes_are_post_only",
        "conformance-draft/test_service_surface.py::test_T22_resume_requires_the_tasks_effect_class",
        "tests/test_service.py::test_keys_are_required_and_scoped",
        "tests/test_service.py::test_claims_are_rate_limited",
        "tests/test_service.py::test_storage_needs_the_store_scope",
        "tests/test_service.py::test_dependencies_stay_inside_the_key_scope",
        "tests/test_service.py::test_park_and_resume_follow_the_holder_and_queue_rules",
        "tests/test_governance_and_isolation.py::test_layer1_protected_surface_ownership_and_eq03_gate",
        "tests/test_governance_and_isolation.py::test_namespace_isolation_across_path_and_header"
      ]
    },
    {
      "id": "holder-task",
      "between": [
        "lease holder",
        "task"
      ],
      "rule": "Heartbeat, submit and split need the claiming key and the current fencing token",
      "enforced_by": [
        "src/tessera/_tasks.py",
        "src/tessera/service.py"
      ],
      "checked_by": [
        "conformance-draft/test_queue_semantics.py::test_T05_fencing_refuses_the_old_holder",
        "tests/test_service.py::test_only_the_claiming_key_may_change_a_task"
      ]
    },
    {
      "id": "agents-public",
      "between": [
        "agents",
        "public effects"
      ],
      "rule": "No key holds the public effect class; public tasks never reach an agent",
      "enforced_by": "src/tessera/_keys.py",
      "checked_by": [
        "tests/test_service.py::test_public_effect_tasks_never_reach_agents"
      ]
    },
    {
      "id": "parker-resumer",
      "between": [
        "parking key",
        "resuming key"
      ],
      "rule": "Outside input comes from someone else holding the task's effect class (and admin for write-repo): the parking key may not resume; admin keys may; resumes are recorded",
      "enforced_by": [
        "src/tessera/_tasks.py",
        "src/tessera/service.py"
      ],
      "checked_by": [
        "tests/test_service.py::test_the_key_that_parked_a_task_may_not_resume_it",
        "conformance-draft/test_service_surface.py::test_T22_resume_requires_the_tasks_effect_class"
      ]
    }
  ],
  "invariants": [
    {
      "id": "I1",
      "statement": "No task is leased to two workers at once",
      "enforced_by": "store",
      "checked_by": [
        "conformance-draft/test_queue_semantics.py::test_T03_no_task_is_held_twice"
      ]
    },
    {
      "id": "I2",
      "statement": "A lease ends only by submit, split, cancel, lapse or a cancelled job; a lapsed task returns with a higher fencing token; heartbeats never extend past the hard cap",
      "enforced_by": "store",
      "checked_by": [
        "conformance-draft/test_queue_semantics.py::test_T04_lapsed_leases_come_back",
        "conformance-draft/test_queue_semantics.py::test_T04_heartbeats_keep_a_lease",
        "conformance-draft/test_queue_semantics.py::test_T04_lease_has_a_hard_cap"
      ]
    },
    {
      "id": "I3",
      "statement": "A write from a stale lease is refused and changes nothing",
      "enforced_by": "store",
      "checked_by": [
        "conformance-draft/test_queue_semantics.py::test_T05_fencing_refuses_the_old_holder"
      ]
    },
    {
      "id": "I4",
      "statement": "Failures retry with bounded jittered backoff, then dead-letter, every attempt logged",
      "enforced_by": "store",
      "checked_by": [
        "conformance-draft/test_queue_semantics.py::test_T06_dead_letter_after_three_failures",
        "conformance-draft/test_queue_semantics.py::test_T06_backoff_grows_within_bounds"
      ]
    },
    {
      "id": "I5",
      "statement": "One stored result per idempotency key; a replay returns the first receipt",
      "enforced_by": "store",
      "checked_by": [
        "conformance-draft/test_queue_semantics.py::test_T07_submit_is_idempotent"
      ]
    },
    {
      "id": "I6",
      "statement": "A split parent waits, then returns with its children's results",
      "enforced_by": "store",
      "checked_by": [
        "conformance-draft/test_queue_semantics.py::test_T08_split_keeps_the_parent"
      ]
    },
    {
      "id": "I7",
      "statement": "The counts record always equals a recount",
      "enforced_by": "store",
      "checked_by": [
        "conformance-draft/test_queue_semantics.py::test_T09_one_counts_record"
      ]
    },
    {
      "id": "I8",
      "statement": "Health reports the database, the reaper's last run and queue depths honestly",
      "enforced_by": "store",
      "checked_by": [
        "conformance-draft/test_queue_semantics.py::test_T10_health_is_honest",
        "conformance-draft/test_service_surface.py::test_T10_health_over_http"
      ]
    },
    {
      "id": "I9",
      "statement": "Model jobs are tied to the lease that started them; a lapse asks them to stop; a cancelled job returns its task",
      "enforced_by": "store",
      "checked_by": [
        "conformance-draft/test_model_jobs.py::test_T12_a_job_is_polled_to_done_with_its_cost",
        "conformance-draft/test_model_jobs.py::test_T12_a_cancelled_job_returns_its_task",
        "conformance-draft/test_model_jobs.py::test_T12_a_lapsed_lease_asks_its_jobs_to_stop"
      ]
    },
    {
      "id": "I10",
      "statement": "Nothing is lost or doubled across workers, queues and restarts",
      "enforced_by": "store",
      "checked_by": [
        "conformance-draft/test_queue_semantics.py::test_T13_it_holds_up",
        "conformance-draft/test_queue_semantics.py::test_T14_it_survives_a_restart"
      ]
    },
    {
      "id": "I11",
      "statement": "Every receipt hash matches its stored result",
      "enforced_by": "store",
      "checked_by": [
        "conformance-draft/test_queue_semantics.py::test_T15_receipts_match_results"
      ]
    },
    {
      "id": "I12",
      "statement": "No key appears in any response, page or log",
      "enforced_by": "service",
      "checked_by": [
        "conformance-draft/test_service_surface.py::test_T16_no_secret_leaks",
        "tests/test_service.py::test_no_key_appears_in_any_response",
        "tests/test_service.py::test_web_forms_never_echo_the_key"
      ]
    },
    {
      "id": "I13",
      "statement": "Records change only by compare-and-set and keep every version; blobs are content-addressed; batches are atomic",
      "enforced_by": "store",
      "checked_by": [
        "conformance-draft/test_storage.py::test_ST01_compare_and_set_has_one_winner",
        "conformance-draft/test_storage.py::test_ST02_every_version_is_kept",
        "conformance-draft/test_storage.py::test_ST03_blobs_are_content_addressed",
        "conformance-draft/test_storage.py::test_ST04_a_batch_applies_completely_or_not_at_all"
      ]
    },
    {
      "id": "I14",
      "statement": "Writes are POST-only; a GET never changes state",
      "enforced_by": "service",
      "checked_by": [
        "conformance-draft/test_service_surface.py::test_T02_writes_are_post_only",
        "tests/test_service.py::test_writes_are_post_only"
      ]
    },
    {
      "id": "I15",
      "statement": "A dependent is never claimable before each dependency is done, dead or cancelled, and then it sees their states and outputs; unknown dependencies are refused",
      "enforced_by": "store",
      "checked_by": [
        "conformance-draft/test_task_graph.py::test_T17_a_dependent_waits_for_every_dependency",
        "conformance-draft/test_task_graph.py::test_T17_failed_or_cancelled_dependencies_still_release",
        "conformance-draft/test_task_graph.py::test_T17_dependencies_must_exist_and_resolved_ones_cost_nothing"
      ]
    },
    {
      "id": "I16",
      "statement": "Split children with `after` run only after the siblings they name",
      "enforced_by": "store",
      "checked_by": [
        "conformance-draft/test_task_graph.py::test_T18_children_can_run_in_waves"
      ]
    },
    {
      "id": "I17",
      "statement": "Parking counts no failure; a parked task is claimable only after resume or its wake time, and its next lease carries its inputs; only the live lease may park",
      "enforced_by": "store",
      "checked_by": [
        "conformance-draft/test_task_graph.py::test_T19_park_waits_for_input_without_a_failure",
        "conformance-draft/test_task_graph.py::test_T19_a_stale_holder_cannot_park",
        "conformance-draft/test_task_graph.py::test_T19_a_parked_task_wakes_when_its_time_is_up"
      ]
    },
    {
      "id": "I18",
      "statement": "A split child is never broader than its parent (read < write-internal < write-repo < public)",
      "enforced_by": "store",
      "checked_by": [
        "conformance-draft/test_task_graph.py::test_T20_a_child_is_never_broader_than_its_parent",
        "tests/test_service.py::test_split_children_need_an_effect_class_the_key_holds"
      ]
    },
    {
      "id": "I19",
      "statement": "The key that parked a task may not resume it, and every resume records the resuming key",
      "enforced_by": "service",
      "checked_by": [
        "tests/test_service.py::test_the_key_that_parked_a_task_may_not_resume_it"
      ]
    },
    {
      "id": "I20",
      "statement": "A resume may name the park it answers, and a late resume for an earlier park is refused",
      "enforced_by": "store",
      "checked_by": [
        "conformance-draft/test_task_graph.py::test_T19_a_resume_can_name_the_park_it_answers"
      ]
    },
    {
      "id": "I21",
      "statement": "Receipt hashes write whole numbers without a fraction, so other languages compute the same hash",
      "enforced_by": "receipts",
      "checked_by": [
        "tests/test_service.py::test_whole_numbers_hash_the_same_in_every_language",
        "tests/test_phase4_atomicity_and_vectors.py::test_l26_receipt_vectors_python_and_cloudflare_edge_node_parity",
        "conformance-draft/test_queue_semantics.py::test_T15_receipts_match_results"
      ]
    },
    {
      "id": "I22",
      "statement": "An older build refuses to open a database with a newer schema instead of downgrading it",
      "enforced_by": "store",
      "checked_by": [
        "tests/test_service.py::test_an_older_build_refuses_a_newer_database"
      ]
    },
    {
      "id": "I23",
      "statement": "Namespaces isolate tasks, records, blobs, buckets, feeds and L0 scent search; quarantined items never appear in search or reflex recall; resuming a parked task requires its effect class",
      "enforced_by": "store",
      "checked_by": [
        "conformance-draft/test_service_surface.py::test_T22_resume_requires_the_tasks_effect_class",
        "tests/test_governance_and_isolation.py::test_namespace_isolation_across_path_and_header",
        "tests/test_governance_and_isolation.py::test_visibility_quarantine_and_layer2_combinable_filters"
      ]
    }
  ],
  "import_rules": [
    {
      "id": "ring0-kernel-stands-alone",
      "package": "tessera",
      "package_root": "src/tessera",
      "files": [
        "src/tessera/models.py",
        "src/tessera/errors.py",
        "src/tessera/receipts.py",
        "src/tessera/clock.py",
        "src/tessera/_version.py",
        "src/tessera/grants.py"
      ],
      "must_not_import": [
        "anyio",
        "fastapi",
        "httpx",
        "mcp",
        "os",
        "random",
        "sqlite3",
        "starlette",
        "tessera.Store",
        "tessera._base",
        "tessera._graph",
        "tessera._jobs",
        "tessera._keys",
        "tessera._observe",
        "tessera._storage",
        "tessera._tasks",
        "tessera.access",
        "tessera.backend",
        "tessera.cli",
        "tessera.client",
        "tessera.mcp_door",
        "tessera.pages",
        "tessera.service",
        "tessera.store",
        "tessera.testing",
        "uvicorn"
      ],
      "why": "Ring 0, the kernel: records, errors, receipts and the clock port describe work in general and depend on nothing but the standard library and pydantic, so every backend and door shares one vocabulary"
    },
    {
      "id": "ring1-port-knows-only-the-kernel",
      "package": "tessera",
      "package_root": "src/tessera",
      "files": [
        "src/tessera/backend.py"
      ],
      "must_not_import": [
        "anyio",
        "fastapi",
        "httpx",
        "mcp",
        "sqlite3",
        "starlette",
        "tessera.Store",
        "tessera._base",
        "tessera._graph",
        "tessera._jobs",
        "tessera._keys",
        "tessera._observe",
        "tessera._storage",
        "tessera._tasks",
        "tessera.access",
        "tessera.cli",
        "tessera.client",
        "tessera.mcp_door",
        "tessera.pages",
        "tessera.service",
        "tessera.store",
        "tessera.testing",
        "uvicorn"
      ],
      "why": "Ring 1, the port: the Backend protocol is the one contract every engine meets and every door and caller uses; it names kernel types only"
    },
    {
      "id": "ring2-engines-never-reach-doors",
      "package": "tessera",
      "package_root": "src/tessera",
      "files": [
        "src/tessera/store.py",
        "src/tessera/_base.py",
        "src/tessera/_graph.py",
        "src/tessera/_tasks.py",
        "src/tessera/_jobs.py",
        "src/tessera/_keys.py",
        "src/tessera/_observe.py",
        "src/tessera/_storage.py",
        "src/tessera/_buckets.py",
        "src/tessera/_intelligence.py",
        "src/tessera/client.py"
      ],
      "must_not_import": [
        "anyio",
        "fastapi",
        "mcp",
        "starlette",
        "tessera.access",
        "tessera.cli",
        "tessera.mcp_door",
        "tessera.pages",
        "tessera.service",
        "tessera.testing",
        "uvicorn"
      ],
      "why": "Ring 2, the engines: the SQLite store and the HTTP client are interchangeable implementations of the port; neither may depend on a door or on test wiring"
    },
    {
      "id": "ring2-engines-do-not-know-each-other",
      "package": "tessera",
      "package_root": "src/tessera",
      "files": [
        "src/tessera/client.py"
      ],
      "must_not_import": [
        "sqlite3",
        "tessera.store",
        "tessera.Store",
        "tessera._base",
        "tessera._tasks",
        "tessera._graph",
        "tessera._jobs",
        "tessera._keys",
        "tessera._observe",
        "tessera._storage",
        "tessera._buckets"
      ],
      "why": "Two engines behind one port stay independent, so a third (Postgres, D1) can be added by meeting the port and passing the suite"
    },
    {
      "id": "ring3-doors-use-the-public-store-api",
      "package": "tessera",
      "package_root": "src/tessera",
      "files": [
        "src/tessera/service.py",
        "src/tessera/_service_buckets.py",
        "src/tessera/_service_intelligence.py",
        "src/tessera/mcp_door.py",
        "src/tessera/_mcp_storage.py",
        "src/tessera/pages.py",
        "src/tessera/cli.py",
        "src/tessera/access.py"
      ],
      "must_not_import": [
        "sqlite3",
        "tessera._base",
        "tessera._tasks",
        "tessera._graph",
        "tessera._jobs",
        "tessera._keys",
        "tessera._observe",
        "tessera._storage",
        "tessera._buckets",
        "tessera._intelligence",
        "tessera.client",
        "tessera.testing"
      ],
      "why": "Ring 3, the doors: HTTP, MCP, pages and the CLI reach state only through Store's public methods and kernel types, never a store-private module, so every guarantee holds on every door"
    },
    {
      "id": "ring3-doors-do-not-reach-upward",
      "package": "tessera",
      "package_root": "src/tessera",
      "files": [
        "src/tessera/mcp_door.py",
        "src/tessera/pages.py",
        "src/tessera/access.py"
      ],
      "must_not_import": [
        "tessera.service",
        "tessera.cli"
      ],
      "why": "The service composes the MCP door and the pages; a door that imported its composer would make the doors one tangle"
    },
    {
      "id": "facade-stays-light",
      "package": "tessera",
      "package_root": "src/tessera",
      "files": [
        "src/tessera/__init__.py"
      ],
      "must_not_import": [
        "anyio",
        "fastapi",
        "httpx",
        "mcp",
        "starlette",
        "tessera.access",
        "tessera.cli",
        "tessera.client",
        "tessera.mcp_door",
        "tessera.pages",
        "tessera.service",
        "tessera.testing",
        "uvicorn"
      ],
      "why": "import tessera gives the kernel, the port and the in-process store without pulling in a web stack, so an embedding caller pays only for what it uses"
    },
    {
      "id": "package-never-imports-dev-roots",
      "package": "tessera",
      "package_root": "src/tessera",
      "files": [
        "src/tessera"
      ],
      "must_not_import": [
        "tools",
        "scripts",
        "tests",
        "conformance",
        "harness",
        "briefs",
        "deploy"
      ],
      "why": "Development tooling, briefs and the suite sit outside the onion; the shipped package never depends on them"
    },
    {
      "id": "store-below-doors",
      "package": "tessera",
      "package_root": "src/tessera",
      "files": [
        "src/tessera/_base.py",
        "src/tessera/_graph.py",
        "src/tessera/_jobs.py",
        "src/tessera/_keys.py",
        "src/tessera/_observe.py",
        "src/tessera/_storage.py",
        "src/tessera/_tasks.py",
        "src/tessera/backend.py",
        "src/tessera/clock.py",
        "src/tessera/errors.py",
        "src/tessera/grants.py",
        "src/tessera/models.py",
        "src/tessera/receipts.py",
        "src/tessera/store.py"
      ],
      "must_not_import": [
        "fastapi",
        "starlette",
        "uvicorn",
        "httpx",
        "mcp",
        "anyio",
        "tessera.service",
        "tessera.pages",
        "tessera.mcp_door",
        "tessera.client",
        "tessera.cli"
      ],
      "why": "The store must work on its own, in process, with no web stack"
    },
    {
      "id": "core-never-imports-learners",
      "package": "tessera",
      "package_root": "src/tessera",
      "files": [
        "src/tessera/store.py",
        "src/tessera/_base.py",
        "src/tessera/_tasks.py",
        "src/tessera/_executions.py",
        "src/tessera/_execution_capture.py",
        "src/tessera/execution_matching.py",
        "src/tessera/observations.py",
        "src/tessera/fingerprints.py",
        "src/tessera/models.py",
        "src/tessera/client.py",
        "src/tessera/service.py",
        "src/tessera/_service_executions.py",
        "src/tessera/_access_boundary.py",
        "src/tessera/mcp_door.py"
      ],
      "must_not_import": [
        "tessera.learners"
      ],
      "why": "Learning policy lives in swappable learners; core keeps capture, the observation read and pure fingerprint functions"
    },
    {
      "id": "learners-use-the-public-contract",
      "package": "tessera",
      "package_root": "src/tessera",
      "files": [
        "src/tessera/learners"
      ],
      "must_not_import": [
        "sqlite3",
        "fastapi",
        "starlette",
        "uvicorn",
        "mcp",
        "anyio",
        "tessera.Store",
        "tessera.store",
        "tessera._base",
        "tessera._tasks",
        "tessera._executions",
        "tessera._execution_capture",
        "tessera._storage",
        "tessera.service",
        "tessera.mcp_door"
      ],
      "why": "A learner is a worker-side component: it reads observations and writes nouns through the same client contract as any authorized worker"
    }
  ],
  "claims": [
    {
      "id": "C1",
      "claim": "No task is leased to two workers at once (8 workers, 1,000 claims)",
      "status": "built",
      "evidence": [
        "conformance-draft/test_queue_semantics.py::test_T03_no_task_is_held_twice"
      ],
      "verify": "make suite BACKEND=store"
    },
    {
      "id": "C2",
      "claim": "A stalled worker's late write is refused",
      "status": "built",
      "evidence": [
        "conformance-draft/test_queue_semantics.py::test_T05_fencing_refuses_the_old_holder"
      ],
      "verify": "make suite BACKEND=store"
    },
    {
      "id": "C3",
      "claim": "A retried submit stores one result and every receipt matches its result",
      "status": "built",
      "evidence": [
        "conformance-draft/test_queue_semantics.py::test_T07_submit_is_idempotent",
        "conformance-draft/test_queue_semantics.py::test_T15_receipts_match_results"
      ],
      "verify": "make suite BACKEND=store"
    },
    {
      "id": "C4",
      "claim": "The counts record always equals a recount",
      "status": "built",
      "evidence": [
        "conformance-draft/test_queue_semantics.py::test_T09_one_counts_record"
      ],
      "verify": "make suite BACKEND=store"
    },
    {
      "id": "C5",
      "claim": "Nothing is lost or doubled across workers, queues and a restart",
      "status": "built",
      "evidence": [
        "conformance-draft/test_queue_semantics.py::test_T13_it_holds_up",
        "conformance-draft/test_queue_semantics.py::test_T14_it_survives_a_restart"
      ],
      "verify": "make suite BACKEND=store"
    },
    {
      "id": "C6",
      "claim": "The suite passes over HTTP against a real local service with real keys (32 tests; the 4 that need a fake clock or a restart hook run on the in-process store)",
      "status": "built",
      "evidence": [
        "scripts/suite_http_local.py"
      ],
      "verify": "make suite-http-local"
    },
    {
      "id": "C7",
      "claim": "MCP clients can enqueue, claim, submit and read/write compare-and-set records through the same keys",
      "status": "built",
      "evidence": [
        "conformance-draft/test_service_surface.py::test_T11_an_mcp_client_can_claim_and_submit",
        "tests/test_service.py::test_the_mcp_door",
        "tests/test_service.py::test_mcp_door_enqueues_verbs_and_writes_cas_nouns"
      ],
      "verify": "make suite-http-local"
    },
    {
      "id": "C18",
      "claim": "Swarm workers expand seed nouns into reviewed canonical nouns with bounded depth, non-self review and Standard-mode Meta Model API job tracking",
      "status": "built",
      "evidence": [
        "tools/swarm_expander.py",
        "tests/test_tools.py::test_swarm_expander_demo_promotes_seed_to_canonical"
      ],
      "verify": "make expand-demo"
    },
    {
      "id": "C8",
      "claim": "Agents that can only browse can work through keyed forms that never echo the key",
      "status": "built",
      "evidence": [
        "tests/test_service.py::test_web_forms_never_echo_the_key"
      ],
      "verify": "make test"
    },
    {
      "id": "C9",
      "claim": "No key appears in any response, page or log",
      "status": "built",
      "evidence": [
        "conformance-draft/test_service_surface.py::test_T16_no_secret_leaks",
        "tests/test_service.py::test_no_key_appears_in_any_response"
      ],
      "verify": "make suite-http-local"
    },
    {
      "id": "C10",
      "claim": "The suite fails against an empty backend, so passing it means something",
      "status": "built",
      "evidence": [
        "src/tessera/testing.py"
      ],
      "verify": "make suite-stub"
    },
    {
      "id": "C11",
      "claim": "Model jobs are tied to their lease and asked to stop when it lapses",
      "status": "built",
      "evidence": [
        "conformance-draft/test_model_jobs.py::test_T12_a_lapsed_lease_asks_its_jobs_to_stop"
      ],
      "verify": "make suite BACKEND=store"
    },
    {
      "id": "C17",
      "claim": "Tasks form graphs without a workflow engine: dependencies (fan-in), children in waves, and park and resume for outside input",
      "status": "built",
      "evidence": [
        "conformance-draft/test_task_graph.py::test_T17_a_dependent_waits_for_every_dependency",
        "conformance-draft/test_task_graph.py::test_T18_children_can_run_in_waves",
        "conformance-draft/test_task_graph.py::test_T19_park_waits_for_input_without_a_failure"
      ],
      "verify": "make suite BACKEND=store"
    },
    {
      "id": "C12",
      "claim": "Runs hosted on Fly.io behind a Cloudflare Worker, reachable only through the edge",
      "status": "partial",
      "evidence": [
        "deploy/fly/fly.toml",
        "deploy/cloudflare/worker.js",
        "deploy/bootstrap-hosting.sh",
        "tests/test_service.py::test_the_edge_lock"
      ],
      "verify": "deploy/bootstrap-hosting.sh --dry-run"
    },
    {
      "id": "C13",
      "claim": "A model-job runner polls the Meta Model API and cancels jobs on lapse",
      "status": "planned",
      "evidence": [
        "briefs/L16.json"
      ]
    },
    {
      "id": "C14",
      "claim": "The event log exports a nightly making-of",
      "status": "planned",
      "evidence": [
        "briefs/L11.json"
      ]
    },
    {
      "id": "C15",
      "claim": "Soak and restart runs on the deployed service",
      "status": "planned",
      "evidence": [
        "briefs/L21.json"
      ]
    },
    {
      "id": "C16",
      "claim": "Shamash's run loop runs on the service",
      "status": "planned",
      "evidence": [
        "briefs/L23.json"
      ]
    }
  ],
  "deployment": [
    {
      "id": "local",
      "how": "make dev",
      "parts": [
        "service on 127.0.0.1:7700",
        "the real Worker code under wrangler dev on 127.0.0.1:7701",
        "a per-run edge secret"
      ]
    },
    {
      "id": "local-public",
      "how": "make dev TUNNEL=1",
      "parts": [
        "the same",
        "a temporary *.trycloudflare.com address"
      ]
    },
    {
      "id": "hosted",
      "how": "deploy/bootstrap-hosting.sh, then the GitHub deploy workflow with approval",
      "parts": [
        "Cloudflare Worker tessera",
        "Fly.io app tessera-fabric with SQLite on a 1 GB volume",
        "one always-on machine for the reaper"
      ]
    }
  ],
  "generalization": {
    "neutral": [
      "queues are names",
      "tasks carry opaque JSON briefs and free-form kinds",
      "workers are any identity",
      "leases, fencing, receipts, retries, dead letters, split and merge",
      "records and blobs under any store name",
      "HTTP, MCP and web doors",
      "counts, events, health",
      "dependencies, waves, park and resume"
    ],
    "specific": [
      "effect classes are a fixed set shaped by coding work",
      "model-job statuses follow Meta Model API background responses",
      "tools/ runs Muse Code on this repo's briefs",
      "the edge is a Cloudflare Worker",
      "agent pages link to this repo"
    ],
    "extension_points": [
      {
        "id": "backend",
        "what": "A new backend (Postgres, D1, another language)",
        "how": "Meet the Backend protocol and pass the suite by factory name",
        "path": "src/tessera/backend.py"
      },
      {
        "id": "work-kind",
        "what": "A new kind of work",
        "how": "Define a queue and use a kind string; no code",
        "path": "src/tessera/cli.py"
      },
      {
        "id": "worker",
        "what": "A new kind of worker",
        "how": "Any HTTP or MCP client, or a person on /work, with a key scoped to its queues",
        "path": "src/tessera/client.py"
      },
      {
        "id": "model-provider",
        "what": "Another model provider",
        "how": "The worker registers the provider's job id and maps its statuses",
        "path": "src/tessera/_jobs.py"
      },
      {
        "id": "storage",
        "what": "A new storage namespace",
        "how": "Use a new store name in /v1/stores/{store} with a store-scoped key",
        "path": "src/tessera/_storage.py"
      },
      {
        "id": "host",
        "what": "Another host",
        "how": "Run the Docker image anywhere with a persistent volume; any proxy can add x-edge-auth",
        "path": [
          "deploy/fly/Dockerfile",
          "deploy/bootstrap-hosting.sh"
        ]
      }
    ]
  },
  "limitations": [
    "The claim rate limiter lives in process memory and resets on restart",
    "Load beyond the suite's scale has not been measured",
    "The spec is a draft until it is locked; the tests can still change",
    "Local SQLite and Worker Durable Object persistence are separate backends; D1 mirrors are best-effort projections.",
    "Key signup is operator-assisted; OAuth and email signup are not implemented.",
    "Public previews on sister surfaces return nonpersistent artifacts; callers save artifacts using their own fabric principal."
  ],
  "open_questions": [
    "Should the hosted service refuse to start without TESSERA_EDGE_SECRET?",
    "Should DNS-rebinding protection on the MCP door default on when hosted?",
    "Should effect classes be configurable?",
    "Is there a request-size limit before parsing large bodies?",
    "Which MCP protocol version do clients negotiate with the door (current spec revision 2026-07-28)?"
  ],
  "feedback": {
    "how": "Open an issue on GitHub; docs/review.md has the questions we most want answered and a prompt for model reviewers",
    "url": "https://github.com/ta-amps/tessera-infrastructure-work-and-storage-engine/issues"
  }
}