HOLCO Context and Rules

An open format for the two things an accounting firm entrusts to an AI layer: its working context (profile, memory, rules, drafts) and its traced decision rules, the firm's own jurisprudence.

Deterministic when possible. AI when necessary. Human when accountable.

This repository is a public, MIT-licensed specification with a dependency-free reference validator and synthetic examples. It contains no production code and no customer data. The format is open; a firm's rules are its own data and never ship with this repository.

Why this exists

When an AI layer works on a firm's dossiers, two artefacts deserve an open, exportable format:

1. The context snapshot (holco.control-context/1): what the AI layer knew when it worked: profile, memory notes, active rules, drafts. Controls such as the financial_workbook pack of holco-finance-controls consume exactly this snapshot as immutable, hashed bytes.
2. The rule record (holco.client-rule/1): a traced arbitration. The AI may propose; a named human decides; the rule carries its rationale, its scope, a bounded validity, and the result of its last replay. In French professional terms: proposition, décision, motif, portée, durée, rejeu.

The point of the open format is auditability and the absence of lock-in: a firm can export its rules, read them, and hand them to a reviewer. A rule is the firm's rule, never the AI's memory.

Invariants

• A rule has no force until a named human has decided it. The AI proposal is recorded verbatim but is only a proposal.
• Every accepted rule is bounded in time (scope_from to scope_to). An expired rule never applies silently: it is reported as expired.
• A rejected proposal is kept, never deleted. Jurisprudence includes refusals.
• A rule whose replay contradicted it stops applying and surfaces for human review. Replay never silently re-validates.
• Every application of a rule cites its id and version.
• Registering a JSON snapshot does not establish its authenticity: provenance and access control belong to the trusted host that captured it.

Quick start

Python 3.11+, no runtime dependency:

python -m pip install -e .
python -m unittest discover -s tests -v

import json
from holco_context_rules import validate_context, applicable_rules

snapshot = json.load(open("examples/synthetic-context.json"))
assert validate_context(snapshot) == []
report = applicable_rules(snapshot["rules"], on="2026-06-15")
print([r["id"] for r in report["applicable"]])
print([r["id"] for r in report["expired"]])

See SPEC.md for the normative format, schema/ for JSON Schemas, and examples/synthetic-context.json for a complete fictitious snapshot.

Relationship to other HOLCO repositories

• holco-finance-controls: the control protocol and reference engine; its financial_workbook pack consumes holco.control-context/1 snapshots and displays rule records for human review, never as executed logic.
• holco-fec-controls: deterministic FEC controls as a local MCP server.

Boundaries

This package validates structure and applies the lifecycle invariants above. It does not interpret rule text, does not execute rules, does not judge their professional merit, and provides no assurance about the data a host puts in a snapshot. Nightly replay, storage, consent and access control are host responsibilities.

Licence

MIT. Copyright (c) 2026 HOLCO INVEST.