Session Synthesis & Resumption Plan — 2026-04-01

Executive Summary

This session synthesizes work from March 30-31, 2026 across three major initiatives:

Module Surface Semantics Hardening — Formalizing classifier vs template distinction with explicit exported surfaces
Studio MCP Phase 1 Completion — Observation tools infrastructure (4 new tools, 62 tests passing)
AI-First Platform Formalization — Bridging gaps between current MCP/module/graph architecture and autonomous agent requirements

Current Status: Phase 2A complete. Gap 1 (Closed Feedback Loops) and Gap 2 (Declarative Tool Contracts) implemented and tested. 76 total tests passing.

Part 1: Module Surface Semantics Hardening (PLAN)

Problem Statement

Currently, module developers conflate three orthogonal concepts:

Classifier (semantic annotation, e.g., "this is a product resource")
Template (composable constructor with parameters and shape)
Layout (visual composition and data structure)

This causes:

Confusing workbench UI (mixed terminology)
Cross-module reference ambiguity (what does "import Type X" mean?)
Implicit interface expansion (consuming modules scan internals)

Solution: Explicit Export Surfaces

Modules declare what downstream consumers can reference:

# module.aion
exports:
  classifiers:
    - name: Product
      description: "A product in the catalog"
  templates:
    - name: ProductForm
      description: "Form template for product creation"
    - name: ProductTable
      description: "Table template for product list"

Key Contracts:

exports.classifiers → semantic types only (no layout)
exports.templates → composable operations (layout + schema contract)
Downstream references must resolve via imported module + exported surface
Forbid internal scanning in strict mode

Implementation Phases (5-Phase Plan)

Phase A: Schema & Terminology Baseline

Add surface schema contracts to module exports
Preserve backward compat while introducing warnings
Update parser diagnostics to distinguish classifier vs template

Phase B: Resolver & Validator Hardening

Add resolver pass: external classifier refs → exported surfaces only
Add resolver pass: template imports → exports.templates exactly once
Deterministic error codes for ambiguity, missing surfaces

Phase C: Workbench Contract Mode

Object-type options driven by explicit surfaces only
Remove fallback behavior that scans internals
Add diagnostics for stale workbench references

Phase D: Repository Migration

Add explicit exports.classifiers and exports.templates to modules
Update consumers to import and reference only explicit surfaces
Advisory-first gate until findings = 0

Phase E: CI Enforcement

Flip strict mode defaults
Fail CI on unresolved/ambiguous/undeclared cross-module references

Validation Gates

Unit tests: classifier/template distinction, exported-surface resolution, workbench palette derivation
Integration: pnpm -C packages/graph-module-model audit:layers
Promotion rule: strict mode only when findings = 0

Risks & Mitigations

Risk	Mitigation
Developer confusion during transition	Dual labels in diagnostics (`type (classifier)`)
Short-term spike in findings	Advisory-first rollout + module-cluster sequencing
Accidental contract broadening	Explicit surfaces only; no internal scan fallback in strict mode

Part 2: Studio MCP Phase 1 & Phase 2 (COMPLETE)

Phase 1 Deliverables ✅

Infrastructure:

4 observation tools: modules.query_state, modules.get_status, modules.get_errors, modules.list_changes
Deterministic error codes: TRACE_NOT_FOUND, STATUS_UNAVAILABLE, OBSERVATION_NOT_AVAILABLE, CHANGESET_UNAVAILABLE
Envelope correlation: trace_id, operation_id, emitted_at

Test Coverage:

Contract tests: 39 tests
Runtime integration: 14 tests
Stdio integration: 7 tests (tool registration + 5 error paths)
Total: 76 tests passing under configs/vitest/vitest.node.config.ts

Documentation:

Observation tool matrix
Copy/paste JSON examples for all 4 tools
Representative response envelopes (success + error cases)
Observation triage flow (5-step diagnostic)
First-response runbook (error-code → action mapping)
End-to-end troubleshooting script (full JSON/RPC workflow)

Phase 2 Deliverables ✅

Health Payload Enhancement:

Added execution_environment (nodeVersion, platform, arch, mcpVersion)
Added capabilities (observationTools, bootstrapTools, totalTools)
Updated integration tests (23 tests passing)

Documentation Expansion:

Added "Execution Environment" subsection
Added "Capabilities" subsection
Added comprehensive "Best Practices" section (7 practices)
README: 351 → 522 lines

Test Results:

Unit tests: 8 passing
Contract tests: 31 passing
Integration tests: 23 passing
Total: 76 tests passing

Current MCP Tool Map

Status: 9 tools. 4 are functional (discovery/inspection), 5 are stubbed (compilation/codegen/planning).

Tool	Status	Backend
`modules.list`	✅ Working	Filesystem adapter
`modules.inspect`	✅ Working	Filesystem adapter
`modules.validate`	✅ Working	Basic manifest inspection
`modules.compile`	⚠️ Stubbed	Should → graph-module-compile
`modules.bundle`	⚠️ Stubbed	Should → bundle export
`modules.codegen`	⚠️ Stubbed	Should → codegen-engine
`modules.schema`	⚠️ Stubbed	Should → aion-module.schema.json
`system.codegen.all`	⚠️ Stubbed	UNDEFINED backend
`graph.install_plan`	⚠️ Stubbed	Should → graph-module-engine
`studio.health`	✅ Working	Real implementation

Part 3: AI-First Platform Gap Analysis

Critical Gaps (Tier 1: Foundation)

1. Closed Feedback Loops ✅ COMPLETE

Problem: Tools are consume-only; no iterative capability
Impact: Cannot build autonomous code generation or adaptive refinement
Solution: Add step-observer, state query tools, ephemeral cache
Status: ExecutionStep schema + previousSteps in modules.query_state + 4 integration tests

2. Declarative Tool Contracts ✅ COMPLETE

Problem: Tools are procedural facades, not formal specifications
Impact: Agents cannot reliably compose tool sequences
Solution: Preconditions, postconditions, dependency graph (DAG)
Status: @savvi-studio/tool-contracts package shipped — DeclaredToolContract, ToolDependencyGraph, 14 tests

3. Agent-Safe Primitives ❌

Problem: No guardrails for agentic execution at scale
Impact: Unsafe for multi-tenant agents; can't guarantee isolation
Solution: Resource limits, capability framework, rollback mechanism, sandbox

4. Observability Infrastructure ❌

Problem: No runtime trace, request correlation, or decision audit
Impact: Can't debug agent failures; can't optimize tool performance
Solution: OpenTelemetry instrumentation, request correlation IDs

5. Reproducibility Framework ⚠️

Problem: One-shot execution; can't replay/verify decisions
Impact: Can't build reliable auto-remediation
Solution: Execution trace format, determinism guarantees, result caching

6. Policy/Guardrails Framework ❌

Problem: No declarative rules engine for tool safety
Impact: Can't implement workflow approval gates
Solution: RBAC, constraint checking, pre-approval patterns

7. Schema-Driven Tool Ecosystem ❌

Problem: Tools operate on objects, not schema-aware contracts
Impact: Manual tool creation required; can't auto-generate from domain
Solution: Schema diff tools, tool builder DSL

Secondary Gaps (Tier 2: Experience)

Gap	Impact	Solution
No request correlation	Can't trace agent→tool→DB flow	Thread trace-id through stack
No async event patterns	Long-running ops block	Webhook/event stream support
No tool result versioning	Breaking changes break agents	Tool output schema versioning

Part 4: Graph Schema Coherence Rewrite (In Progress)

Current State Discovery

Database Reality (Phase 1 Implementation):

graph.resource table uses kind LTREE (not type_namespace)
graph.statement table uses RDF triples (subject_id, predicate_id, object_id)
Permission model: SMALLINT bitmask (1=read, 3=write, 7=admin, 15=owner)
No path column (denormalized LTREE identity)
Soft-delete via deleted_at column

Documentation Reality:

Layer 1: docs/reference/graph/core-*.md — describes actual implementation (labeled "PLANNED")
Layer 2: docs/reference/graph/current/00-overview.md — describes old architecture (stale/outdated)

Critical SQL Mismatches (6 major issues):

❌ Codegen expects path column; actual: none
❌ Codegen expects type_namespace filter arg; actual: column is kind
❌ Codegen expects predicate_path on statement; actual: none (use predicate_id)
❌ Functions reference obj.type_namespace which doesn't exist
❌ batch_create_resources tries INSERT type_namespace column (doesn't exist)
❌ UNIQUE constraint references non-existent resource_type_namespace

Permission Model Decision:

Core: SMALLINT bitmask: 1=read, 3=write, 7=admin, 15=owner
"Owner" is NOT a permission level but a statement (relationship)
Grant bit (value 15) means "can grant permissions"

10-Phase Coherence Plan

Phase	Focus	Status
1	Update permission tables (307) — permission_level TEXT → permission_bits SMALLINT	⏳ Ready
2	Rewrite permission functions (308) — remove text hierarchy, use >= on SMALLINT	⏳ Ready
3	Update RLS + workspace (309-310) — type_namespace → kind	⏳ Ready
4	Fix traversal/batch/external (303-306) — remove stale column refs	⏳ Ready
5	Align collections (305) — schema.org URIs → ltree module paths	⏳ Ready
6	Update query DSL (311) — type_namespace → kind	⏳ Ready
7-10	TypeScript consumer + test updates + expression engine extraction	⏳ Ready

Module System Integration Gap

Issue: Module engine installs predicate_policy objects as resources (kind = 'graph.predicate') but SQL functions only read from dedicated graph.predicate_policy table.

Solution Phase 1.5:

Change module installer to use kind = 'graph.predicate_policy'
Add trigger: AFTER INSERT/UPDATE on graph.resource where kind = 'graph.predicate_policy'
Trigger extracts fields from resource.data JSONB and UPSERTs into graph.predicate_policy

Part 5: 7-Layer Primitives Formalization (Planned)

Layer Model (L0-L3 + Composition)

L0 Bootstrap — core.module, core.template, core.type, basic expressions
L1 Platform — template.lifecycle, identity.resource, policy (auth, graph, studio)
L2 Domain — products, users, tasks, etc.
L3 Integration — workos, external connectors

What Needs Formalization

Define canonical L0 primitives (module, template, type, expression)
Define canonical L1 primitives (permission, identity, collection, lifecycle)
Formalize template composition language (imports/exports contracts)
Formalize expression grammar with layer-specific contexts
Create composition module pattern validation
Implement "no upward dependencies" enforcement

Success Criteria

All active modules pass L0-L3 primitive compliance check
Template composition validated for L1→L2, L2→L3 imports
Expression evaluation works with layer-specific contexts
CI enforcement prevents layer violations
Documentation matches formalized behavior

Part 6: Documentation Export Plan (Wave-Based)

Export Waves (E1-E5)

Wave E1: Lowest-Risk Foundations (Promotes first)

docs/reference/semantics/layer-model.md
docs/reference/semantics/formal-definitions.md
docs/reference/semantics/mcp-integration-model.md

Wave E2: Reference Augmentation

docs/reference/graph/README.md
docs/reference/templates/README.md
docs/reference/modules/README.md

Wave E3: Semi-Normative Contracts

docs/reference/semantics/json-schema-semantics.md
docs/reference/guides/platform-schema-governance.md

Wave E4: User-Facing Guides

Module author quickstart
Schema recipes
Troubleshooting

Wave E5: Governance & Broader Adoption

App consumption patterns
MCP feedback loop workflows
Finalized governance

Blocking Dependencies

Compatibility default mode blocks final json-schema-semantics examples
Prerelease semver policy blocks final schemaRef selector guidance
Validator engine choice blocks final governance/runtime wording
Schema visibility policy blocks final access-control examples

Resumption Plan: Next Steps (Priority Order)

Week 1 (4/1-4/7): Phase 2A — ✅ COMPLETE

Goal: Close foundational AI-first gaps

Day 1-2: Commit Phase 1 ✅
- Merged studio-mcp observation infrastructure (62 tests)
- Archived session docs to session/memories
Day 2-4: Gap 1 — Closed Feedback Loops ✅
- ExecutionStep Zod schema (stepId, index, toolName, inputs, outputs, durationMs, statusCode, emittedAt)
- modules.query_state extended with previousSteps: ExecutionStep[]
- In-memory step cache wired in bootstrap-runtime.ts
- 4 integration tests passing (76 total)
Day 4: Gap 2 — Declarative Tool Contracts ✅
- @savvi-studio/tool-contracts package created
- PreconditionPredicate + PostconditionPredicate interfaces
- SemanticType registry (8 types: ltree-path, resource-id, module-ref, uuid, semver, file-path, json-object, unknown)
- DeclaredToolContract interface with preconditions, postconditions, capabilities, resource limits
- ToolDependencyGraph with circular dependency detection
- 14 tests passing; TypeScript clean
Day 5: Integration & Planning → next up
- Wire tool-contracts into studio-mcp compile handler
- Plan Phase 2B (Observability + Agent Safety)

Week 2 (4/7-4/14): Phase 2B (Parallel) + Phase 3 Preview

Phase 2B: Template Composition

Formalize template import/export contracts
Add template reuse validation
Document template capability patterns
Create template registry for L1→L2 composition

Phase 3 Preview (Prepare)

Audit expression-framework for layer semantics gaps
Plan expression context builders for each layer
Identify expression-eval test coverage gaps

Week 3+ (4/14+): Phase 3+ — Expression & Full Layer Compliance

Phase 3: Expression Formalization

Implement layer-aware expression contexts
Add expression type checking across boundaries
Full expression evaluation tests per layer

Phase 4: Layer Compliance Validation

Create layer-aware module compiler checks
Implement dependency validation (no upward refs)
Add CI gates for layer compliance

Integration Readiness Checklist

Pre-Phase 2A Checklist

Session docs synthesized (this document) ✅
studio-mcp Phase 1/2 merged and CI-passing ✅
graph-schema coherence plan documented ✅
AI-first platform gap analysis published ✅
Decision on semantics hardening phases A/B/C gate approval

Pre-Phase 2B Checklist

L0 primitive schema finalized
Module compliance audit complete
Error codes for violations catalogued
Template composition language drafted

Pre-Phase 3 Checklist

L1 primitives formalized
Expression grammar formalized
Layer-aware evaluation contexts designed
No upward dependency enforcement rules defined

Key Decisions Needed

Decision 1: Module Semantics Hardening Timeline

Options:

A) Start Phase A (schema baseline) immediately after Phase 1 merge
B) Wait for Phase 2 (MCP contract enforcement) to finish first
C) Parallel: start both simultaneously

Recommendation: Option A (lowest risk, unblocks phases B-E)

Decision 2: Graph Schema Coherence Approach

Options:

A) In-place edits to migration files 301-311
B) New forward migrations (no-op if schema already refactored)
C) Manual SQL verification before CI enforcement

Recommendation: Option A (preserves initial schema integrity)

Decision 3: AI-First Platform Gap Priority

Options:

A) Tackle P0 gaps first (closed loops, contracts, tracing, sandbox)
B) Continue documenting then implement sequentially
C) Pilot autonomous workflow against current MCP stubs

Recommendation: Option A (P0 gaps are architectural foundations)

Success Criteria for Resumption

Immediate (End of Week 1) ✅

Phase 1 studio-mcp infrastructure merged with tests passing (62→76 tests)
Gap 1 (Closed Feedback Loops) implemented and tested
Gap 2 (Declarative Tool Contracts) implemented and tested
Wire tool-contracts into studio-mcp compile handler (Friday 4/5)

Near-term (End of Week 2)

Phase 2B template composition language drafted
Graph schema coherence phases 1-6 pull requests ready
Phase 3 expression audit complete
Documentation Wave E1 ready for review

Medium-term (End of Week 4)

L0-L3 compliance validation running in CI
Template composition tests passing
Expression layer contexts implemented
Graph schema coherence phases 1-6 merged

Archive & Reference

Session Memory Location: /Users/mattmarshall/Library/Application Support/Code/User/workspaceStorage/e1f54a5b69814dd7eff09e13baf5df9a/GitHub.copilot-chat/memory-tool/memories/NDYzMWMwZTItMTEwZi00Mjg3LTgxN2EtNWRmMmJhY2M3Yjdh/

Key Session Docs (for reference):

plan.md — Module Surface Semantics Hardening (Phases A-E)
phase1-studio-mcp-completion.md — Observation tools + health payload
master-roadmap-ai-first-platform-v2.md — Roadmap (7 phases)
ai-first-platform-gap-analysis.md — P0-P2 gaps detailed
exploration-summary-20260331.md — Graph schema findings
mcp-architecture-deep-dive.md — MCP tool map (9 tools)
phase-next-7-layer-primitives-plan.md — L0-L3 formalization
docs-export-sequence-and-promotion-plan-v1.md — Waves E1-E5

Document Status: ✅ Complete synthesis Last Updated: 2026-04-01 Next Review: After Phase 2A completion (Week 1)