@ordinatio/core

Shared types, covenants, construction standards, admission pipeline, council orchestrator, intermittent machine, and Pugil integration bridge for the Ordinatio architecture.

This is the foundational package that all other @ordinatio/* packages depend on for shared type definitions, architectural primitives, and governance infrastructure.

559 tests. Zero runtime dependencies.

What's in the box

| Module | Location | Purpose | |--------|----------|---------| | Covenants | src/covenants/ | 17 module covenants (12 Canonical + 5 Ecclesial), capability registry, covenant types | | Construction Standards | src/construction/ | Book V codified: covenant validator, Builder's Questions, boundary checker, complexity meter, pre-disputation audit, module scaffolder | | Admission Pipeline | src/admission/ | Book VI codified: 5 mechanical gates (structural, permission, conflict, governance, sandbox), pipeline orchestrator, module registry, council admission workflow | | Council Orchestrator | src/council/ | Book II codified: Scholastic Method engine, 8 Offices, artifact helpers (SHA-256), artifact validator, office briefs, stall detection, freeze/resume | | Intermittent Machine | src/execution/ | Book IV codified: wake-on-event execution, awakening classification, budget tracking, governance evaluation, pause/resume via ContinuationToken | | Pugil Bridge | src/council/pugil-bridge.ts | Converts Vitest test results into TrialReportContent artifacts for Council consumption | | Serializable Transactions | src/transactions/ | runSerializable(prisma, tx => …) runs a SERIALIZABLE transaction with jittered-backoff retry when it loses a race, and isSerializationConflict(error) recognizes a Postgres serialization failure in every shape Prisma has reported one (P2034 on Prisma 7.6 model operations, P2010-wrapped on 7.6 raw queries, a raw DriverAdapterError on 7.10 — observed on those two versions only; the checks are structural). fn is re-run in full on each retry, so keep external side effects outside it. Zero dependencies, structural checks only — a P2034-only check silently stops retrying after a Prisma upgrade | | Bounded lock waits | src/transactions/ | limitLockWait(tx, ms) sets Postgres lock_timeout for the current transaction (before the locks it should bound; per lock wait; a value above 2147483647 ms is rejected by Postgres, not by a RangeError), and isLockTimeout(error) recognizes the resulting SQLSTATE 55P03 (also raised by a NOWAIT failure: for a caller the answer is the same) in every wrapper Prisma uses. Lets a user-facing action say "busy, try again" in seconds instead of holding a pooled connection for the whole transaction timeout. Zero dependencies | | Text cleaning | src/text/ | cleanOutsideText(text, maxGraphemes?) (also exported as cleanForLog, its original name) makes outside text (a subject, a sender's display name) safe and small for a feed, a label or a screen reader: removes invisible/bidi/format characters, judges one grapheme at a time (keeps real names whole in Burmese, Thai, Indic, Arabic, emoji ... and drops lookalike joiner tricks), bounds the result by construction, idempotent (fuzz-tested); keeps Bengali/Indic ra-phala joiner words, Burmese marks and the Mongolian vowel separator inside Mongolian words whole; throws a RangeError for a bad limit. Zero dependencies; needs Intl.Segmenter | | Runtime guards | src/guards/ | createRuntimeSwitch({ read, override }): a kill switch an operator flips at runtime (any present value except an empty string, 0, false or no means OFF, so a typo fails safe), cached, shared in-flight read, keeps the last known answer when the store fails. createOptInSwitch({ read, envValue, now }): the opposite default, a feature that is OFF unless a stored on (a failed read keeps the last known answer, off if none). createProviderSwitch({ providers, read }): per mail provider, "on since" a time (a failed read is 'unknown', never an earlier on). Both share the lever, cache, shared read and timeout of the kill switch, and take the clock and the environment from the caller. @ordinatio/core/crypto also has createSealedBox({ key }) and createVersionedSealedBox({ current, key }): AES-256-GCM sealing of a stored secret, bound to its row by AAD (a copy moved to another row fails to open), fresh IV each time, iv | tag | ciphertext in base64 (the versioned one prefixes <version>: so keys can be rotated); the key comes from a function you pass (asked on every call), the random source is injectable for tests. createKeyedThrottle({ intervalMs }): let the first event per key through, then none for a while (bounded memory). Both use a monotonic clock and validate their options (RangeError). Zero dependencies, storage injected | | Domus Module Contract | src/domus-contract.ts | The event/module contract every Domus module implements (DomusEvent, EventHandler, ModuleEventDeclaration, ModuleDefinition) — lives here, not in @ordinatio/domus, so contract consumers can't form package cycles with domus (see the file header) |

Installation

npm install @ordinatio/core

Publish ordering (v1.2.0+)

v1.2.0 added the Domus module-contract types (src/domus-contract.ts). @ordinatio/domus and @ordinatio/realtime deliberately pin workspace:^1.2.0 (not workspace:*): if either is published before core 1.2.0 reaches npm, the rewritten ^1.2.0 range is unresolvable and the consumer's install fails loudly — instead of resolving npm's older core and shipping d.ts that reference types it doesn't have. Publish core first. Tracked in .autocode/debt.md PKG-1.

Pugil Integration Bridge

The Pugil bridge converts test suite results into Council-consumable trial_report artifacts. Used by all @ordinatio/* packages that implement Pugil reporters.

import {
  buildTrialReport,
  createTrialArtifact,
  assessOverall,
  extractIssues,
} from '@ordinatio/core';
import type { PugilTestResult, PugilSuiteResult, PugilTestCategory } from '@ordinatio/core';

// Build a trial report from test results
const report = buildTrialReport(suiteResult);

// Create an artifact for Council consumption
const artifact = createTrialArtifact(report, cycleId);

Test categories: unit, integration, chaos, adversarial, concurrency

Testing

pnpm --filter @ordinatio/core test:run
# 575 tests

Documentation

• Ordinatio Founding Documents
• Construction Standards
• Admission Pipeline
• Council Orchestrator
• Intermittent Machine

Pugil Integration

This package includes a Pugil reporter that generates Council-consumable trial_report artifacts from test results.

# Normal test run (no Pugil overhead)
pnpm --filter @ordinatio/core test:run

# With Pugil trial report generation
PUGIL_ENABLED=true pnpm --filter @ordinatio/core test:run

# With Council cycle integration
PUGIL_ENABLED=true PUGIL_CYCLE_ID=cycle-core-v1 pnpm --filter @ordinatio/core test:run

• Config: src/pugil.config.ts — maps test files to categories (unit, integration, adversarial, chaos, concurrency)
• Reporter: src/pugil-reporter.ts — Vitest custom reporter, writes to pugil-reports/
• Types: PugilTestResult, PugilTestCategory from @ordinatio/core

License

MIT