feat: add schema and record entry types with JSON Schema validation

[cmeans-claude-dev]

Summary

Adds two new EntryType values — schema and record — with JSON Schema Draft 2020-12 validation on write. Schemas live per-owner with a shared _system fallback namespace for built-in shapes; records pin to an exact (schema_ref, schema_version) and get re-validated on content update. Schema deletion is blocked while live records still reference the version. A new CLI tool (mcp-awareness-register-schema) gives operators a path to seed _system-owned schemas at deploy time. The internal _error_response() helper now accepts **extras, so all new structured error envelopes flow through the same path.

Closes #208.

Spec: docs/superpowers/specs/2026-04-13-schema-record-entry-types-design.md
Plan: docs/superpowers/plans/2026-04-13-schema-record-entry-types-plan.md

What's new

• New MCP tools: register_schema, create_record
• New CLI: mcp-awareness-register-schema --system ... — operator-only, bypasses MCP
• New migration: idempotent _system user seed
• New runtime dep: jsonschema>=4.26.0,<5
• New helpers: validation.validate_schema_body, validation.validate_record_content, validation.resolve_schema, validation.assert_schema_deletable, validation.compose_schema_logical_key, SchemaInUseError
• New Store methods: find_schema(owner_id, logical_key) (with _system fallback), count_records_referencing(owner_id, schema_logical_key) (returns (count, up_to_10_ids))
• Extended: update_entry branches on type — schemas always reject (schema_immutable), records re-validate content on update; delete_entry blocks schema deletion when records reference it (schema_in_use); _error_response() now accepts **extras for structured error payloads

What's explicitly out of scope

• Secrets (x-secret encryption, one-time token web form, edge decrypt endpoint) — separate follow-up PR per the spec's implementation order (steps 3–6).
• Admin-via-MCP — no is_admin column on users; system writes are CLI-only for now.
• Cross-schema $ref resolution via referencing.Registry — deferred until a real use case demands it.
• Validator caching — per-write construction; cache later if throughput demands it.
• Bulk-delete paths (delete_entry by tags/source) — not protected against live records. Single-id deletion is protected. Bulk protection is a known concern worth its own follow-up.
• Generic create_entry — kept type-specific tools per existing convention; a future refactor across all write tools could collapse them, but that's not this PR.

Deployment

After merge + Docker image rebuild:

1. Pull + restart holodeck LXCs (production) and the QA instance.
2. Run mcp-awareness-migrate in each environment to apply the _system user seed.
3. Operator runs mcp-awareness-register-schema --system ... per built-in schema, gradually as schemas are authored.
4. No re-embed needed.

QA

Prerequisites

• pip install -e ".[dev]"
• Deploy to QA test instance on alternate port (AWARENESS_PORT=8421) via docker-compose.qa.yaml.
• Run mcp-awareness-migrate against the QA DB to apply the _system user seed migration.

Manual tests (via MCP tools unless otherwise noted)

1. • Register a schema (happy path)

   register_schema(source="qa-test", tags=["qa"], description="qa test schema",
                   family="schema:qa-thing", version="1.0.0",
                   schema={"type": "object", "properties": {"name": {"type": "string"}}, "required": ["name"]})
   

   Expected: {"status":"ok","id":"<uuid>","logical_key":"schema:qa-thing:1.0.0"}

2. • Reject invalid schema (meta-schema check)

   register_schema(source="qa-test", tags=[], description="bad",
                   family="schema:bad", version="1.0.0",
                   schema={"type": "strng"})
   

   Expected: structured error with code: "invalid_schema" in the payload.

3. • Reject duplicate family+version
     Re-run step 1 exactly. Expected: code: "schema_already_exists" with logical_key in the extras.
4. • Reject empty family or version

   register_schema(source="qa-test", tags=[], description="bad", family="", version="1.0.0", schema={"type":"object"})
   

   Expected: code: "invalid_parameter" with param: "family".

5. • Create a valid record

   create_record(source="qa-test", tags=[], description="a qa thing",
                 logical_key="qa-rec-1", schema_ref="schema:qa-thing", schema_version="1.0.0",
                 content={"name": "widget"})
   

   Expected: {"status":"ok","id":"<uuid>","action":"created"}

6. • Reject record with invalid content (all errors surfaced)

   create_record(source="qa-test", tags=[], description="bad record",
                 logical_key="qa-rec-bad", schema_ref="schema:qa-thing", schema_version="1.0.0",
                 content={"unexpected": 42})
   

   Expected: code: "validation_failed" with validation_errors list containing at least the required violation for the missing name field, and schema_ref/schema_version echoed.

7. • Unknown schema yields schema_not_found with searched_owners

   create_record(source="qa-test", tags=[], description="orphan",
                 logical_key="orphan-1", schema_ref="schema:does-not-exist", schema_version="1.0.0",
                 content={})
   

   Expected: code: "schema_not_found", searched_owners: [<your-owner>, "_system"].

8. • Record upsert via same logical_key
     Re-run step 5 with different content {"name": "widget-v2"}. Expected: action: "updated", same id as step 5.
9. • Record re-validation on content update (valid)

   update_entry(entry_id=<id from step 5>, content={"name": "still-valid"})
   

   Expected: success (no error). Content updated.

10. • Record re-validation on content update (invalid → rejected)

    update_entry(entry_id=<id>, content={"name": 123})
    

    Expected: code: "validation_failed"; record content unchanged when queried via get_knowledge.

11. • Schema immutability

    update_entry(entry_id=<schema id from step 1>, description="new desc")
    

    Expected: code: "schema_immutable"; schema unchanged.

12. • Schema deletion blocked by live records

    delete_entry(entry_id=<schema id from step 1>)
    

    Expected: code: "schema_in_use", referencing_records: [...], total_count.

13. • Schema deletion allowed after records deleted
      delete_entry(entry_id=<record id from step 5>), then retry step 12.
      Expected: schema soft-deletes successfully.
14. • _system fallback via CLI + MCP
      On the QA instance shell:

    echo '{"type": "object"}' > /tmp/qa-sys.json && \
    AWARENESS_DATABASE_URL=<qa-dsn> mcp-awareness-register-schema \
      --system --family schema:qa-system --version 1.0.0 \
      --schema-file /tmp/qa-sys.json --source qa-built-in --tags qa --description "qa system schema"
    

    Then via MCP:

    create_record(source="qa-test", tags=[], description="uses system schema",
                  logical_key="qa-sys-rec", schema_ref="schema:qa-system", schema_version="1.0.0",
                  content={"any": "thing"})
    

    Expected: record creates successfully against the _system-owned schema.

15. • Cross-owner isolation
      As a second authenticated user on the QA instance, attempt to resolve step 1's schema (schema:qa-thing:1.0.0). Expected: code: "schema_not_found".

Edge cases

16. • Primitive content schemas

    register_schema(source="qa-test", tags=[], description="int schema",
                    family="schema:counter", version="1.0.0", schema={"type": "integer"})
    create_record(source="qa-test", tags=[], description="a count",
                  logical_key="count-1", schema_ref="schema:counter", schema_version="1.0.0",
                  content=42)
    

    Expected: success — data.content can be any JSON value, not just objects.

17. • Array content schemas
      Register {"type": "array", "items": {"type": "string"}} and write ["a","b"] as content. Expected: success.

Known limitations (verify no attempt exploits these)

• Bulk-delete paths (delete_entry by tags/source) do not currently protect schemas referenced by records. Only single-id deletion is protected. If QA has a compelling case for bulk-delete protection, file as follow-up; not blocking for this PR.

[codecov]

Codecov Report

❌ Patch coverage is 99.49749% with 1 line in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
src/mcp_awareness/cli_register_schema.py	97.95%	1 Missing ⚠️

📢 Thoughts on this report? Let us know!