Skip to content

ISSUE_25_COMPLETION_REPORT.md

Latest commit

 

History

History
216 lines (161 loc) · 7.8 KB

ISSUE_25_COMPLETION_REPORT.md

File metadata and controls

216 lines (161 loc) · 7.8 KB
Raw
title Issue #25 Completion Report: COP/Accounting Conformance Kernel
author Jean Hugues Robert
affiliation Institut Mariani / C.O.R.S.I.C.A.
license CC BY-SA 4.0
language en
date 2026-07-23
last_modified_at 2026-09-08
status stable
document_role operational
document_kind completion-report
visibility public
lifecycle_state active
update_policy UP-DEFAULT-REVIEWED
canonical_url https://github.com/JeanHuguesRobert/inseme/blob/main/ISSUE_25_COMPLETION_REPORT.md
related_issues
provenance
origin_type origin_repository origin_ref origin_date derived_from
repository
JeanHuguesRobert/inseme
67741c8
2026-07-23
packages/cop-core/COP_ACCOUNTING.md
review
status reviewed_by reviewed_at
human-validated
Jean Hugues Robert
2026-09-08

Issue #25 Completion Report: COP/Accounting Conformance Kernel

Files Changed

cop-core (Protocol Types and Schemas)

  • packages/cop-core/src/accounting.ts (new) - TypeScript protocol types
  • packages/cop-core/src/index.ts (modified) - Export accounting module
  • packages/cop-core/schemas/accounting/base.schema.json (new)
  • packages/cop-core/schemas/accounting/event.budget.schema.json (new)
  • packages/cop-core/schemas/accounting/event.reservation.schema.json (new)
  • packages/cop-core/schemas/accounting/event.transaction.schema.json (new)
  • packages/cop-core/schemas/accounting/event.reversal.schema.json (new)
  • packages/cop-core/schemas/accounting/event.account.schema.json (new)

cop-kernel (Implementation and Tests)

  • packages/cop-kernel/src/accounting/quantity.js (new) - Exact quantity arithmetic
  • packages/cop-kernel/src/accounting/validator.js (new) - Event validation
  • packages/cop-kernel/src/accounting/projector.js (new) - Deterministic projection
  • packages/cop-kernel/src/accounting/index.js (new) - Kernel entry point
  • packages/cop-kernel/src/index.js (modified) - Export accounting module
  • packages/cop-kernel/test/accounting.test.js (new) - Conformance tests

Commands Run

# Build cop-core with new types
pnpm --filter @inseme/cop-core build

# Run cop-kernel tests (including new accounting conformance tests)
pnpm --filter @inseme/cop-kernel test

Test Results

  • Total tests: 179
  • Passed: 179
  • Failed: 0
  • Accounting conformance tests: 32 (all passing)

Implementation Summary

1. Protocol Types (cop-core)

  • Defined TypeScript types for all accounting events (Budget, Reservation, Transaction, Reversal, Account)
  • ExactQuantity type using decimal coefficient + scale (no binary floating-point)
  • GovernanceContext with actor/principal separation and mandate linkage
  • Projection types (AccountBalance, BudgetStatus, ReservationStatus, PublicKudosProjection)

2. JSON Schemas (cop-core)

  • base.schema.json - Shared definitions (ExactQuantity, AccountIdentifier, Posting, etc.)
  • event.budget.schema.json - Budget grant/amend/revoke
  • event.reservation.schema.json - Reservation with TTL and budget reference
  • event.transaction.schema.json - Balanced transactions with postings
  • event.reversal.schema.json - Full/partial/compensating reversals
  • event.account.schema.json - Account lifecycle (create/modify/suspend/close)

3. Validator Kernel (cop-kernel)

  • Event-specific validators for each accounting event type
  • Balanced posting validation (debits = credits within unit/domain)
  • Cross-unit rejection without explicit conversion_rate
  • Mandate compliance checking (actor vs principal)
  • Budget availability checking for reservations
  • Idempotency enforcement via idempotency keys
  • Account identifier validation (HTTPS URL, URN, local, kudos formats)

4. Projector Kernel (cop-kernel)

  • projectAccountBalances() - Derive account balances from transactions/reversals
  • projectBudgetStatus() - Track budget granted/available/reserved/committed/spent
  • projectReservationStatus() - Track reservation lifecycle
  • projectPublicKudos() - Privacy-preserving public projection
  • Deterministic replay (sorted by timestamp)
  • Idempotency (duplicate events skipped)

5. Exact Quantity Arithmetic (cop-kernel)

  • No binary floating-point for authoritative quantities
  • compareQuantities(), addQuantities(), subtractQuantities()
  • fromDecimal(), toDecimal() round-trip conversion
  • Scale-aware operations

Conformance Tests Passed

All 12 required conformance tests pass:

  1. ✅ Balanced transaction accepted - Debits equal credits
  2. ✅ Unbalanced transaction rejected - Atomically rejected
  3. ✅ Cross-unit balancing rejected - Without explicit conversion_rate
  4. ✅ Duplicate delivery - Idempotency, one accounting effect
  5. ✅ Competing reservations - Cannot overspend budget
  6. ✅ Expired/revoked mandates rejected - Budget status checked
  7. ✅ Reversal neutralizes effect - Without deletion
  8. ✅ Unauthorized creation/destruction rejected - Source/sink requires mandate
  9. ✅ Deterministic replay - Identical state from events
  10. ✅ HTTPS account URL accepted - https://jhn.baronsmariani.org/
  11. ✅ Public Kudos projection - Excludes private details
  12. ✅ Short lifecycle representation - No micro-events required

COP Invariants Preserved

  • Immutability - Events and Artifacts never modified; corrections via new events
  • Topic-local ordering - Events ordered by timestamp for deterministic replay
  • Idempotency - Duplicate delivery has one effect (via processedIdempotencyKeys tracking)
  • Durability - All state derivable from Events
  • Stateless agents - Projector is pure function over event stream
  • Isolation via events - No hidden mutable state; projection is deterministic
  • Schema versioning - All events carry schemaVersion: "1.0"
  • Transparency - Evidence references, mandate links, disclosure classes explicit

Known Limitations

  1. Reversal of type "full" without compensating_postings - Currently only processes compensating reversals with explicit postings. Full reversals would require storing original transactions for lookup.

  2. Account identifier format validation - Basic regex check (HTTPS URL, URN, local, kudos) but no full URL dereferencing or SEO metadata.

  3. Conversion rate validation - Presence of conversion_rate checked but rate value validation not implemented.

  4. Evidence artifact dereferencing - References stored but artifacts not fetched/verified.

  5. Real-time enforcement - No atomic locking for concurrent reservations; relies on idempotency and re-verification.

Remaining Risks

  1. Schema versioning - Need to define migration path when "1.0" → "1.1"

  2. Cross-unit conversion - Authorized conversions need governance model (who authorizes, how)

  3. Public projection semantics - May need refinement for edge cases (mixed domain transactions)

  4. Performance - Large event streams may need checkpointing/snapshotting

Next Steps

  1. Add COP_ACCOUNTING.md specification document (referenced but not created)
  2. Implement checkpoint/resume for long-running projections
  3. Add integration tests with real COP Store backend
  4. Define governance workflow for conversion rate authorizations
  5. Add CLI tooling for accounting state queries

Agent Trace

Agent: Claude (Opus 4.8) Principal: Jean Hugues Robert Mandate: inseme issue #25 (bounded implementation) Checks:

  • All tests pass (179/179)
  • No new durable primitives introduced (Events/Artifacts only)
  • Projection is storage-independent
  • TypeScript compiles without errors

Human validation needed: Yes - Please review:

  1. Schema completeness for your use cases
  2. Account identifier formats (https://jhn.baronsmariani.org/)
  3. Public projection privacy semantics
  4. Evidence reference model