Skip to content

Latest commit

 

History

History
215 lines (170 loc) · 7.45 KB

V1_COMPLETION_PLAN.md

File metadata and controls

215 lines (170 loc) · 7.45 KB

Canon V1 Completion Plan

Overview

Canon V1 is an AI-native programming language with a working foundation. This plan addresses the gaps between the current implementation and the full V1 specification.

Current Status

Working:

  • CLI commands: validate, policy, gen, test, build
  • Core IR types and JSON loading
  • Schema validation, reference checking, basic type checking
  • TypeScript codegen for most node types
  • Golden test runner with effect mocking
  • OPA/Rego policy engine integration

Gaps to Address:

  1. Missing codegen for match nodes
  2. Incomplete type validation (struct fields, list ops, custom calls)
  3. Missing capability scope enforcement
  4. Missing DAG cycle detection
  5. Incomplete policy deny message extraction
  6. No unit tests for Go packages
  7. Runtime effects are stubs (deny-all only)

Implementation Tasks

Phase 1: Complete Validation (Critical)

1.1 Add match node codegen

File: pkg/codegen/typescript.go

  • Add case in generateNode() switch for "match"
  • Generate JS switch statement or chained ternaries
  • Handle enum/variant pattern matching

1.2 Implement struct field validation

File: pkg/validate/typecheck.go

  • For struct.make: verify field count/names match struct type definition
  • For struct.get: verify field exists in struct type
  • Look up struct definitions from prog.Types

1.3 Implement list operation type checking

File: pkg/validate/typecheck.go

  • list.map: input is List[T], mapper returns List[U]
  • list.filter: input is List[T], predicate returns Bool
  • list.fold: input is List[T], initial is A, reducer is (A,T)->A

1.4 Add custom function call validation

File: pkg/validate/typecheck.go

  • For non-intrinsic calls, look up function definition
  • Verify argument count matches params
  • Verify argument types match param types

1.5 Add DAG cycle detection

File: pkg/validate/references.go

  • Build adjacency list from node inputs
  • Run DFS to detect back edges
  • Report error with cycle path if found

Phase 2: Capability System (Security-Critical)

2.1 Implement capability scope validation

File: pkg/validate/effects.go

  • Parse scope field from CapabilityDef
  • For effect.invoke with cap_id:
    • Extract attrs (e.g., host for HTTP, path for FS)
    • Check attrs fall within capability scope constraints
  • Example: HTTP capability with scope.hosts: ["api.example.com"] should reject calls to other hosts

2.2 Add scope constraint types

File: pkg/ir/types.go

  • Define CapabilityScope struct with typed fields:
    • Hosts []string for Net capabilities
    • Paths []string for FS capabilities
    • Tables []string for DB capabilities
    • Actions []string for allowed operations

Phase 3: Policy Engine Improvements

3.1 Fix getDenyMessages

File: pkg/policy/opa.go

  • Store policy module content after compilation
  • Extract deny messages from evaluation result properly
  • Return specific violation reasons, not generic "denied"

3.2 Expand default policies

Files: policies/default.rego, policies/safety.rego

  • Add secret access requires capability rule
  • Add AI confidence threshold for production (0.8)
  • Add shell execution forbidden rule
  • Verify existing rules work correctly

Phase 4: Testing Infrastructure

4.1 Add Go unit tests

New files:

  • pkg/ir/types_test.go - IR struct tests
  • pkg/ir/load_test.go - JSON loading tests
  • pkg/validate/schema_test.go - Schema validation tests
  • pkg/validate/typecheck_test.go - Type checking tests
  • pkg/validate/references_test.go - Reference integrity tests
  • pkg/codegen/typescript_test.go - Codegen tests
  • pkg/policy/opa_test.go - Policy engine tests

4.2 Add integration tests

New file: cmd/canon/integration_test.go

  • Test full pipeline on example files
  • Test policy violations are caught
  • Test type errors are caught

Phase 5: Runtime Implementation

5.1 Implement real HTTP effect handler

File: runtime-ts/effects.ts

  • Add makeHttpHost() that performs real HTTP requests
  • Respect timeout attrs
  • Return response body/status

5.2 Implement logging effect handler

File: runtime-ts/effects.ts

  • Add makeLoggingHost() that actually logs
  • Support log levels from attrs

5.3 Add effect handler composition

File: runtime-ts/effects.ts

  • Allow combining handlers (e.g., HTTP + logging)
  • Add composeHosts(...hosts) function

Phase 6: Additional Examples

6.1 Create policy violation example

New file: examples/policy-demo/violation.canon.json

  • Program that violates default policies
  • Document expected error output

6.2 Create complex dataflow example

New file: examples/data-pipeline/pipeline.canon.json

  • Uses list.map, list.filter, list.fold
  • Demonstrates struct operations
  • Shows conditional logic with if

6.3 Create match/pattern matching example

New file: examples/enum-demo/enum.canon.json

  • Defines enum type with variants
  • Uses match to handle cases
  • Shows type-safe exhaustive matching

File Summary

Files to Modify

File Changes
pkg/codegen/typescript.go Add match node codegen
pkg/validate/typecheck.go Struct/list/call validation
pkg/validate/references.go DAG cycle detection
pkg/validate/effects.go Capability scope checking
pkg/ir/types.go CapabilityScope struct
pkg/policy/opa.go Fix deny message extraction
runtime-ts/effects.ts Real effect handlers
policies/default.rego Additional safety rules
policies/safety.rego Additional safety rules

Files to Create

File Purpose
pkg/ir/types_test.go Unit tests
pkg/ir/load_test.go Unit tests
pkg/validate/schema_test.go Unit tests
pkg/validate/typecheck_test.go Unit tests
pkg/validate/references_test.go Unit tests
pkg/codegen/typescript_test.go Unit tests
pkg/policy/opa_test.go Unit tests
cmd/canon/integration_test.go Integration tests
examples/policy-demo/violation.canon.json Example
examples/data-pipeline/pipeline.canon.json Example
examples/enum-demo/enum.canon.json Example

Priority Order

  1. Phase 1 - Complete validation (struct fields, list ops, custom calls, match codegen, DAG detection)
  2. Phase 2 - Capability scope enforcement (security-critical)
  3. Phase 4.1 - Go unit tests (verify correctness as we go)
  4. Phase 3 - Policy engine improvements
  5. Phase 5 - Runtime effect handlers
  6. Phase 6 - Additional examples

Success Criteria

V1 is complete when:

  1. All node types generate correct TypeScript (including match)
  2. Type checking catches struct field mismatches
  3. Type checking catches list operation type errors
  4. Capability scopes are enforced (unauthorized hosts rejected)
  5. DAG cycles are detected and rejected
  6. Policy violations report specific reasons
  7. Unit tests pass for all packages
  8. All examples build and test successfully