R76.P1 Packet — κ Rule Engine Phase 1 Deep Task Breakdown

Step 3 of 5. Gates implementation (Step 4). This packet enumerates the 20 sub-tasks, their one-line summaries, and whether each carries forward an existing task-breakdown.md entry or fills a gap.

1. Final sub-task manifest (20 total, 5 groups)

P1.1 — Integer Math Library (3 sub-tasks)

ID Title Effort One-line summary Carry-forward?
P1.1.1 Basis Point Arithmetic S bps_mul, bps_div, decay, apply_bps — integer-only helpers with overflow detection. Yes — existing task-breakdown.md entry at lines 461–473. Path prefix changed src/rules/ → src/domains/rules/.
P1.1.2 Determinism Verification Harness S Property + fuzz tests ensuring identical inputs → identical bit-outputs across 10k random pairs. No wall clock / RNG / async. Yes — existing at lines 475–484. Path prefix changed.
P1.1.3 BPS Constants + Overflow Protection S Constants table (BPS_100_PERCENT, DECAY_EXECUTION, etc.), safe_mul, safe_div, explicit overflow error types. No — new. Fills gap between P1.1.1’s helpers and their consumers.

P1.2 — DSL Parser (4 sub-tasks)

ID Title Effort One-line summary Carry-forward?
P1.2.1 Lexer / Tokenizer M Chevrotain-based tokenizer covering keywords + integer literals; rejects floats; line/column tracking. Yes — existing at lines 488–499. Chevrotain ratified per ADR-006.
P1.2.2 Parser (Tokens → AST) L Chevrotain parser emitting AST matching extraction §2 node types; operator precedence NOT > AND > OR, */% > +-; error recovery. Yes — existing at lines 501–513.
P1.2.3 AST Validator M Rejects forbidden ops (clock, fs, network, randomness outside VRF), type checks, scope checks, cycle detection. Yes — existing at lines 515–527.
P1.2.4 Rule Loader / Registry M Parses a ruleset file, constructs sorted registry, detects specificity ties at load time (refuse boot). No — new. Fills gap for the RULE_REGISTRY from extraction §8.

P1.3 — Deterministic Interpreter (4 sub-tasks)

ID Title Effort One-line summary Carry-forward?
P1.3.1 Core Evaluation Loop L Recursive AST evaluator, fixed ordering Admission → StateTransition → Consequence → Promotion, 10k-node timeout, collect-then-apply. Yes — existing at lines 531–542.
P1.3.2 Built-in Functions M Integer min, max, abs, cap, isqrt, ilog2, decay, diminishing, bps_mul, bps_div, hash, vrf_verify — all pure. Yes — existing at lines 544–556.
P1.3.3 State Access Layer M Read-only state snapshot with reputation[node][domain], tokens[node], stake[node], epoch; emit diff list per mutation. Yes — existing at lines 558–568.
P1.3.4 Policy Gating / Pre-guards M Policy P1–P13 pre-guard chain from extraction §9; short-circuits on first failure; policies are DSL expressions. No — new. Fills gap for the pre-guard pipeline from extraction §9.

P1.4 — Admission Layer (4 sub-tasks, all new)

ID Title Effort One-line summary Carry-forward?
P1.4.1 Admission Evaluator L evaluate_admission(caller, tool, mode, rep_snapshot, rule_version) → {admit|deny, reason} called from α’s tool-lock stage. No — new.
P1.4.2 Denial Reason Taxonomy S Typed enum of denial reasons (no_rule_matched, budget:integer_ops, budget:call_depth, effect_invariant_violated, axiom_violation, etc.) with structured error payloads. No — new.
P1.4.3 Admission Budgets / Evaluation Budget M Enforcement of MAX_INTEGER_OPS=10_000, MAX_CALL_DEPTH=16, MAX_ARG_COUNT=8. Instrumentation hooks for α’s audit layer. No — new.
P1.4.4 Tool-Lock Integration Spec M Contract adapter exposing κ admission at α’s 5-stage middleware tool-lock (stage 1) hook. Not implemented inline — lands as a factory function registered at server boot. No — new.

P1.5 — Governance / Rule Versioning (5 sub-tasks)

ID Title Effort One-line summary Carry-forward?
P1.5.1 Version Hash Computation S rule_version = SHA-256(canonical(all_rules) || engine_version). Version stamped into event metadata; mismatched events rejected. Yes — was existing P1.4.1 at lines 572–581. Renumbered.
P1.5.2 Rule Migration L Test corpus ≥100 events; run under old + new rules; identical effect-hashes required outside declared divergence scope. Activation at epoch N+1; rollback on parity failure. Yes — was existing P1.4.2 at lines 583–592. Renumbered.
P1.5.3 Activation Epoch + Rollback M Activation scheduling (epoch N+1), rollback flow for parity-failed proposals; π governance hook at activation time. Fork trigger on rejection (links to ι). No — new.
P1.5.4 Canonical Serialization M Sorted-key deterministic JSON for rules; byte-identical outputs across implementations. Basis for version hashing (P1.5.1). No — new. Fills gap between P1.5.1’s “canonical serialization” input and its implementation.
P1.5.5 Test Corpus Parity Harness L Harness running corpus across any two rule versions, producing divergence set + effect-hash diff. Required to land before a π proposal can graduate. No — new. Fills gap for the parity enforcement point from rule-engine.md §Test corpus parity requirement.

Total: 10 carry-forward + 10 new = 20 sub-tasks. Exactly meets the ≥20 target.

2. Dependency graph (critical-path) 

P1.1.1  →  P1.1.2  →  P1.1.3
   │                      │
   └──────────┬───────────┘
              ↓
P1.2.1  →  P1.2.2  →  P1.2.3  →  P1.2.4
                         │
                         ↓
P1.3.2  ←  P1.3.1  →  P1.3.3  →  P1.3.4
                         │
                         ↓
P1.4.2  ←  P1.4.1  →  P1.4.3  →  P1.4.4
                                    ↓
                               (hooks into α tool-lock)

P1.5.4  →  P1.5.1  →  P1.5.2  →  P1.5.5
              │
              ↓
            P1.5.3

Canonical serial path (8 PRs minimum)

  1. P1.1.1 (Basis Point Arithmetic) — unblocks P1.1.2 / P1.1.3 / P1.3.2
  2. P1.1.3 (BPS Constants) — or run in parallel with P1.1.2
  3. P1.2.1 (Lexer) — unblocks P1.2.2
  4. P1.2.2 (Parser) — unblocks P1.2.3 / P1.2.4
  5. P1.3.1 (Evaluation Loop) — unblocks P1.3.2 / P1.3.3 / P1.3.4
  6. P1.4.1 (Admission Evaluator) — unblocks P1.4.2 / P1.4.3 / P1.4.4
  7. P1.5.1 (Version Hash) — unblocks P1.5.2 / P1.5.5 / consensus integration
  8. P1.5.2 (Rule Migration) — closes Phase 1 core

Parallelizable from #3 onward: roughly 3-lane parallelism is possible (parser + interpreter + admission-planning), subject to the 3-agents-at-once ceiling from feedback_rate_limit_parallel.md.

3. Edits to task-breakdown.md

Before (lines 457–593, 137 lines) 

## Phase 1: κ Rule Engine

### P1.1 — Integer Math Library
#### P1.1.1 — Basis Point Arithmetic
#### P1.1.2 — Determinism Verification Harness

### P1.2 — DSL Parser
#### P1.2.1 — Lexer/Tokenizer
#### P1.2.2 — Parser (Tokens → AST)
#### P1.2.3 — AST Validator

### P1.3 — Deterministic Interpreter
#### P1.3.1 — Core Evaluation Loop
#### P1.3.2 — Built-in Functions
#### P1.3.3 — State Access Layer

### P1.4 — Rule Versioning
#### P1.4.1 — Version Hash Computation
#### P1.4.2 — Rule Migration

After (20 sub-task entries) 

## Phase 1: κ Rule Engine

### P1.1 — Integer Math Library (3 sub-tasks)
#### P1.1.1 — Basis Point Arithmetic
#### P1.1.2 — Determinism Verification Harness
#### P1.1.3 — BPS Constants + Overflow Protection        [NEW]

### P1.2 — DSL Parser (4 sub-tasks)
#### P1.2.1 — Lexer/Tokenizer
#### P1.2.2 — Parser (Tokens → AST)
#### P1.2.3 — AST Validator
#### P1.2.4 — Rule Loader / Registry                     [NEW]

### P1.3 — Deterministic Interpreter (4 sub-tasks)
#### P1.3.1 — Core Evaluation Loop
#### P1.3.2 — Built-in Functions
#### P1.3.3 — State Access Layer
#### P1.3.4 — Policy Gating / Pre-guards                 [NEW]

### P1.4 — Admission Layer (4 sub-tasks)                 [NEW SECTION]
#### P1.4.1 — Admission Evaluator                        [NEW]
#### P1.4.2 — Denial Reason Taxonomy                     [NEW]
#### P1.4.3 — Admission Budgets                          [NEW]
#### P1.4.4 — Tool-Lock Integration Spec                 [NEW]

### P1.5 — Governance / Rule Versioning (5 sub-tasks)   [RENUMBERED FROM P1.4]
#### P1.5.1 — Version Hash Computation       [was P1.4.1]
#### P1.5.2 — Rule Migration                 [was P1.4.2]
#### P1.5.3 — Activation Epoch + Rollback              [NEW]
#### P1.5.4 — Canonical Serialization                  [NEW]
#### P1.5.5 — Test Corpus Parity Harness               [NEW]

All file-path prefixes in Output fields harmonize to src/domains/rules/....

4. Packet acceptance gate

Implementation (Step 4) may proceed only if:

  1. The audit (Step 1) has enumerated the 20 sub-tasks — done (see docs/audits/r76-p1-kappa-planning-audit.md §4).
  2. The contract (Step 2) has specified the prompt file structure and scope bounds — done (see docs/contracts/r76-p1-kappa-planning-contract.md §3).
  3. This packet enumerates the 20 sub-tasks with one-line summaries — done (see §1 above).
  4. No sub-task is marked [TBD], [placeholder], or [unknown].

Gate verdict: OPEN. Step 4 may proceed.

5. Risk register

Risk Mitigation
Executor confuses R76.P1 (planning) with R81+ (implementation) and writes κ code. Scope-bound language in preamble of the prompt file + “No κ code in R76” in PR description + CLAUDE.md §5 “keep changes scoped” rule.
Existing task-breakdown.md file-path prefix (src/rules/) drifts from Phase 0 convention (src/domains/...). Every sub-task’s Output field is rewritten to src/domains/rules/<name>.ts.
Chevrotain version drift between Phase 1 and Phase 0. P1.2.1 prompt pins Chevrotain install command and records the version at landing time.
Two competing grammar definitions (concept doc §EBNF vs extraction §1). P1.2 prompts explicitly adopt the extraction’s superset; concept doc §EBNF is kept as the narrower subset (both valid — extraction is the implementation target).
Activation epoch (P1.5.3) sequencing confusion with θ consensus (Phase 3). P1.5.3 prompt scopes the local epoch-based activation; consensus integration is explicitly deferred to P3.x (listed in Unblocks).
20 sub-tasks too granular; some will later be merged. Acceptable — 20 is the target per R76.P1 deliverable. Future rounds (R81+) may combine sub-tasks into PRs, but each keeps its prompt available for reference.

6. Verification plan (preview of Step 5)

  • Run npm run build && npm run lint && npm test — expected: all pass (docs-only PR, no code changes).
  • Word-count sanity: the new prompt file should fall between 2000 and 5000 lines. 20 sub-tasks × ~200 lines each ≈ 4000 lines is the target.
  • grep -c "^## P1\." docs/guides/implementation/task-prompts/p1.1-kappa-rule-engine.md → must return 20.
  • grep -c "^#### P1\." docs/guides/implementation/task-breakdown.md in the Phase 1 section must return 20.
  • No [TBD] or [placeholder] tokens anywhere in the new Phase 1 content.

Packet complete — proceed to implementation.

Back to top

Colibri — documentation-first MCP runtime. Apache 2.0 + Commons Clause.

This site uses Just the Docs, a documentation theme for Jekyll.