Companion to: V0.2-BEHAVIORAL-TYPES.md Status: Engineering plan (2026-05-27). Reviewable; not yet started.
PULSE/
├── schemas/
│ ├── pulse-loop-manifest.v0.1.json (frozen — keep as-is)
│ ├── pulse-loop-manifest.v0.2.json ← NEW
│ ├── pulse-tokens.v0.2.json ← NEW (typed token registry)
│ ├── pulse-choreography.v0.2.json ← NEW
│ └── tokens/ ← NEW (per-token payload schemas)
│ ├── topology_context.v0.2.json
│ ├── deliberation_request.v0.2.json
│ ├── deliberation_result.v0.2.json
│ ├── outcome_signal.v0.2.json
│ ├── reputation_update.v0.2.json
│ ├── consolidation_event.v0.2.json
│ ├── surprise_signal.v0.2.json
│ └── session_fidelity_violation.v0.2.json
├── manifests/ (loop manifests AND choreographies co-located)
│ ├── graphonomous.continual_learning.json (upgrade to v0.2 fields)
│ ├── prism.benchmark.json (upgrade)
│ ├── agentromatic.deliberation.json (upgrade)
│ ├── body-browser.embodiment.json (upgrade)
│ ├── body-os.embodiment.json (upgrade)
│ └── continual_learning_with_prism.choreography.json ← NEW (co-located, not separate dir)
├── src/
│ ├── schema.ts (extend: load v0.2 + tokens registry)
│ ├── tokens.ts (extend: linearity + variance + registry partial order)
│ ├── conformance.ts (extend: T13–T23)
│ ├── session_type.ts ← NEW (regex/automaton derivation)
│ ├── projection.ts ← NEW (choreography → local view)
│ ├── subtype.ts ← NEW (A <: B relation)
│ ├── refinement.ts ← NEW (vendored mini-evaluator, no Z3)
│ ├── runtime_fidelity.ts ← NEW (trace ↔ session-type diff)
│ ├── cli.ts (add: check, compat, project)
│ ├── tools.ts (extend: MCP tools for v0.2)
│ └── resources.ts (extend: expose derived session types)
├── test/
│ ├── conformance.test.ts (existing — keep + extend)
│ ├── session_type.test.ts ← NEW
│ ├── projection.test.ts ← NEW
│ ├── subtype.test.ts ← NEW
│ ├── refinement.test.ts ← NEW
│ └── runtime_fidelity.test.ts ← NEW
└── docs/
├── V0.2-BEHAVIORAL-TYPES.md (design — written)
└── V0.2-IMPLEMENTATION-PLAN.md (this file)Each task is independently shippable. Pause for review at any checkpoint.
Deliverables
schemas/pulse-tokens.v0.2.json with 8 canonical tokens, each declaring
linearity, variance, ttl_ms, and a path to a payload schema.
8 payload schemas under schemas/tokens/*.json.
src/tokens.ts extended to load + index the registry and expose the
partial-order check (isAdditiveExtension(a, b)) over payload schemas.
src/schema.ts adds a loadTokenRegistry() entry point.
Linearity defaults (per resolved Q1 — linear is the default for new canonical tokens; opt down to affine only for observational tokens):
| Token | Linearity | Rationale |
|---|---|---|
TopologyContext | linear | drives routing |
DeliberationRequest | linear | triggers inner loop |
DeliberationResult | linear | feeds act |
OutcomeSignal | linear | audit primitive |
ReputationUpdate | affine | long-window; next update overrides |
ConsolidationEvent | affine | idempotent housekeeping |
SurpriseSignal | linear | OS-011 prediction error |
SessionFidelityViolation | linear | violation reports |
Tests (test/tokens.test.ts)
Each canonical token name resolves to a payload schema.
Each payload schema is a valid JSON Schema draft 2020-12.
Linearity + variance fields are present and use enumerated values.
Registry partial order: a v0.2 payload schema that adds an optional
field passes isAdditiveExtension(v0.2, v0.1); one that removes a field fails.
Vendor-namespaced token IDs match ^[a-z0-9]+\.v[0-9]+\.[A-Z][a-zA-Z0-9]+$
and are accepted by the registry alongside canonical names.
Acceptance
npm test green.
Existing 12 conformance tests still pass on all 5 reference manifests.
Deliverables
schemas/pulse-loop-manifest.v0.2.json extends v0.1.1 with optional
inputs, outputs, effects, refinements, successors fields.
The v0.2 schema validates v0.1.1 manifests unchanged (compat).
src/schema.ts loads v0.2 by default; v0.1.1 still selectable via
--schema-path flag.
Tests (test/schema.test.ts — extend existing)
v0.1.1 reference manifests validate under v0.2.
A v0.2-enriched manifest fragment (handwritten fixture) validates.
A v0.2-enriched fragment with bad effect-row shape fails with a clear
error path.
Acceptance
5 reference manifests validate under v0.2 without modification.
Deliverables
src/session_type.ts builds an automaton from phase successors:
Nodes = phase IDs
Edges = declared successors
Initial state(s) = phases with no predecessor or kind=retrieve
Accepting state(s) = phases with empty successors or kind=consolidate
Functions: reachable_set(automaton), has_progress(automaton),
derive_regex(automaton).
src/refinement.ts vendored mini-evaluator (per resolved Q4) covering
≤, <, ≥, >, ==, !=, set membership, ∧/∨/¬. No Z3, no optional peer dep. Used by T19.
Effect rows use field names calls / mutates (per resolved Q3),
with values being substrate operation IDs from OS-010 §9. The schema validator rejects effect rows that reference storage paths like sqlite.kg.nodes (must be substrate operations only).
New conformance tests T13–T19 in src/conformance.ts.
pulse check <manifest> CLI verb (src/cli.ts).
Tests (test/session_type.test.ts)
Linear-token consumer-uniqueness violation (handwritten fixture) is caught.
Affine-token over-consumption is caught.
Unreachable phase is reported.
A successful derivation produces a regex matching at least one accepted run
per reference manifest.
Acceptance
All 5 reference manifests pass pulse check after Task 2 enrichment OR
pass with degraded_checks: true if left as v0.1.1 shapes.
Deliverables
src/runtime_fidelity.ts initial cut: given an in-memory trace
(array of {phase_id, emitted: Token[], consumed: Token[]}), verify linear/affine/relevant constraints.
DB-backed variant: enforce against signals stored by emit_signal /
receive_signal MCP tools.
New conformance tests T21–T23.
Tests (test/runtime_fidelity.test.ts)
Linear emission with two consumers → violation.
Linear emission with no consumer (after window expiry) → violation.
Affine emission with zero consumers → pass.
Effect-row violation (phase called undeclared substrate operation, e.g.
invoked memory.store_node without declaring it in mutates) → violation.
Acceptance
SessionFidelityViolation token emitted via existing CloudEvents
envelope plumbing on detected violations.
Deliverables
src/subtype.ts implements the A <: B relation per the
V0.2-BEHAVIORAL-TYPES spec section 5.
pulse compat <a@v> <b@v> CLI verb.
Counterexample reporting (which phase/field broke the relation, with
witness values).
Tests (test/subtype.test.ts)
loop@v == loop@v is reflexive.
Adding a phase: subtype holds.
Removing an output token: subtype breaks (covariance violation).
Widening an input: subtype holds (contravariance).
Dropping an invariant: subtype breaks.
Acceptance
pulse compat [email protected] [email protected] produces a
meaningful verdict against the actual deployed versions.
Deliverables
schemas/pulse-choreography.v0.2.json.
manifests/continual_learning_with_prism.choreography.json (co-located
with loop manifests per resolved Q2) — the first real choreography spanning graphonomous + prism + agentromatic.
src/projection.ts implements C↓P producing per-participant connection
obligations.
New conformance test T20 (projection consistency).
New CLI verb pulse project <choreography> --participant <id>.
New MCP tool project_choreography.
Tests (test/projection.test.ts)
Round-trip: choreography → project to all 3 participants → re-merge →
equals original up to step ordering.
Inconsistent participant (declares emit but choreography says receive)
→ projection error.
Guarded steps (e.g. kappa > 0) project guard predicates into each
participant's connection block.
Acceptance
pulse check over all 3 participants of the reference choreography
reports projection-consistency green.
Deliverables
Update README.md PULSE conformance section: 23 tests (was 12).
Update docs/NPM_PACKAGE.md: new MCP tools + resources.
New docs/V0.2-MIGRATION.md: a 1-page "upgrade your v0.1.1 manifest"
walkthrough using graphonomous as the worked example.
Update docs/THREE_PROTOCOL_STACK.md: note v0.2 typed protocol layer
(currently describes v0.1 only).
Acceptance
A reader unfamiliar with v0.2 can take a v0.1.1 manifest and produce a
fully-typed v0.2 manifest by following V0.2-MIGRATION.md alone.
| Phase | Days |
|---|---|
| Task 1 — Token registry | 1–2 |
| Task 2 — Phase signatures + effects | 1 |
| Task 3 — Session-type derivation | 3–5 |
| Task 4 — Linear-token runtime | 1–2 |
| Task 5 — Subtyping | 2 |
| Task 6 — Choreography + projection | 7–10 |
| Task 7 — Docs + migration | 2 |
| Total | ~3–4 weeks focused |
Tasks 1–5 alone (~1.5 weeks) get PULSE to ~36/40, already past Agent Behavioral Contracts (33/40). Task 6 is the difference between "great" and "top of ranking" (39/40).
All 5 reference manifests upgraded to v0.2 shapes (Task 2 + Task 3).
The 12 existing conformance tests still pass on all 5 manifests.
The 11 new conformance tests (T13–T23) pass on all 5 manifests after
upgrade.
The continual_learning_with_prism.choreography.json round-trips through
projection cleanly.
CLI verbs pulse check, pulse compat, pulse project documented in
--help and README.md.
npm test green; no decrease in coverage.
Backwards compat verified: a v0.1.1 manifest still validates and runs
under v0.2 with degraded_checks: true.
| Risk | Likelihood | Mitigation |
|---|---|---|
| Manifest size doubles (annotation overhead drives users away) | Med | Enforce 30–50% growth budget on reference manifests; if exceeded, default more fields |
| Vendored refinement evaluator too weak for some constraints | Med | Document supported subset; unsupported predicates pass through as documentation; runtime fidelity (T21–T23) catches violations not provable offline |
| Session-type derivation chokes on cyclic-but-valid phase graphs | Med | Accept loops if a consolidate or route-to-retrieve arc exists (cycle = continual loop, not deadlock) |
| Choreography projection blows up combinatorially with parallel branches | Med | Cap parallel depth at 4 for v0.2; document the limit |
| Existing PRISM benchmarks regress because they read v0.1.1 manifests | Low | v0.2 schema is additive; PRISM reads only fields it knows |
No new transport (still CloudEvents over stdio MCP).
No new persistence backend (still SQLite + sqlite-vec).
No formal verification of substrate-level behavior (the manifest is
typed; the underlying Elixir/TS code is not).
No automated v0.1 → v0.2 migration tool (migration is documented but
manual; reference manifests serve as worked examples).
[x] Q1 — Linearity default: linear for new canonical tokens; affine
only for observational/idempotent (resolved 2026-05-27 per OS-010 §7.3).
[x] Q2 — Choreography location: co-located in manifests/ (resolved
per STACK_TOPOLOGY_AS_AUTHORITY thesis).
[x] Q3 — Effect row granularity: operation-level, substrate API IDs
from OS-010 §9 (resolved per substrate-independence thesis).
[x] Q4 — Refinement checker: vendored mini-evaluator, no Z3, no SMT
(resolved per ≤25KB processor target).
[x] Q5 — Token subtyping: registry-level only; vendor-namespace for
custom payloads (resolved per OS-010 §1019–1051).
[ ] Spec review of updated V0.2-BEHAVIORAL-TYPES.md complete
[ ] Task 1 branch cut
Rationale evidence for each resolution is in docs/V0.2-RATIONALE.md (planned, optional — quotes are also folded into the spec body and into the "Resolved design questions" section of V0.2-BEHAVIORAL-TYPES.md).