Clausary is the system of record for the rules your business runs on. Specify them precisely, govern every change with evidence, and prove your systems conform.

Payment allocation

Invariant PA-4.2

Version 1.2.0, shown against 1.1.0

Version 1.2.0: The allocated amount never exceeds the removed: invoice total added: amount received, net of credit notes.

Correction, minor version

Finding F-12 showed overpayments being allocated beyond the money received. A correction must name the finding that prompted it.

Struck through: removed. Underlined: added. Each version keeps its own permanent link. Illustrative model.

One rule. Five answers.

Ask five teams how long a refund takes and you'll get five answers, each written down somewhere, none of them the authority.

Five places. Five different answers.

  • Refund policy, 2023 edition, page 7

    Refunds are issued within 14 days of the request.

  • Team wiki, last edited two years ago

    Refunds: 14 working days.

  • refund_service.py

    REFUND_WINDOW_DAYS = 21

  • Onboarding deck, slide 12

    Refunds in two weeks

  • Support ticket 4471

    Agreed 30 days as a one-off. Treat as standard going forward?

Clausary draws them into one rule.

RF-2.1Version 2.0.0, published and fixed

A refund is issued within 14 calendar days of the request being received.

Now each one cites it, and can't drift.

  • Refund policy cites RF-2.1
  • Wiki cites RF-2.1
  • Code tested against RF-2.1
  • Deck cites RF-2.1
  • Support macro cites RF-2.1

With Clausary there is one clause. The policy, the wiki, the deck and the code all point to it. Illustrative example.

  • Rules are scattered. Copies drift apart and nobody can say which one is right.
  • Explanations go stale. The rules change, the writing doesn't, and people act on what's no longer true.
  • Changes lose their reasons. You can see that a rule changed, rarely why. The evidence disappears into inboxes.
  • Systems can't be checked. Without a precise statement of the rules, there is nothing to test against.
  • Nothing stable to cite. Auditors and partners need the rule as it stood on a given date.
  • The cost adds up. Rework, late defects, slow onboarding and weak answers when a regulator asks how a decision was made.

Four parts, bound to one specification.

  1. Models

    Each business system becomes numbered clauses held in one registry. Every clause has a permanent id you can cite.

    • PA-1.2StateReceived, allocated or refunded
    • PA-3.1TransitionReceived to allocated, when an invoice matches
    • PA-4.2InvariantNever allocate more than was received
  2. Bound papers

    Articles quote clauses directly from the version they explain, so the explanation and the rule can't disagree.

    A newer version of this model, 1.2.1, is available.

    When a customer pays more than they owe, the surplus stays unallocated. That follows from Never allocate more than was received PA-4.2, which the rest of this paper relies on.

  3. Research records

    Questions, hypotheses, findings and decisions are kept as records. A correction must name the finding that prompted it.

    F-12Refuted

    Overpayments were being allocated beyond the amount actually received.

    Tested against version 1.1.0. Led to the correction in 1.2.0.

  4. Conformance

    Every version ships a machine-readable package to test an implementation against. Failing test vectors block publishing.

    • PA-T7Overpayment leaves the surplus unallocated
    • PA-T8Credit note reduces the allocation
    • PA-T9Partial refund after allocation
    See conformance checks at work

Rules your systems are held to.

Every version ships a conformance package. Test any implementation against it, and Clausary won't publish a version while its checks fail.

Payment allocationPADraft

  • Clauses
  • Conformance (current view)
  • Relations
  • Change log

Conformance package

pa-1.2.1.json

{
  "model": "PA",
  "version": "1.2.1",
  "clauses": ["PA-1.2", "PA-3.1", "PA-4.2"],
  "vectors": [
    {
      "id": "PA-T7",
      "given": { "invoice": 100, "received": 140 },
      "when": "allocate",
      "then": { "allocated": 100, "unallocated": 40 }
    },
    ...
  ]
}

Machine-readable and fixed. Its fingerprint is recorded when the version is published.

Publish checks

  • Every modified clause marked normative or editorial
  • Reason for the change written for the change log
  • Correction names its finding, F-12
  • 1 test vector failing, PA-T9

Publishing blocked

Fix the implementation or the rule, then run the checks again.

$ npm run models:check-vectors -- --draft
Checking the PA draft against the reference implementation
  PA-T7   Overpayment leaves the surplus unallocated   pass
  PA-T8   Credit note reduces the allocation           pass
  PA-T9   Partial refund after allocation              fail
          expected unallocated 40, got 0
2 passed, 1 failed.
An illustrative Clausary model screen showing a conformance package, publish checks with one failing test vector, and a terminal test run.

Illustrative model and results.

Every change keeps its reasons.

Follow any published version back to the question that started it. Research can stay private: public change logs say how many findings prompted a change, never which ones.

  1. Question

    Q-04

    Should overpayments be allocated at all?

  2. Hypothesis

    H-09

    Capping at the invoice total is safe.

  3. Finding

    F-12

    Refuted. Some allocations exceeded the money received.

  4. Decision

    D-07

    Cap allocation at the amount received.

  5. Published

    Version 1.2.0

    A correction naming F-12. Every bound paper shows a notice.

One answer to what your rules are, and why they are that way.

Leadership and risk
Trace every change from question to decision. Shorter audits and stronger answers for regulators and customers.
Architects
Version numbers that signal real impact, and relations that show which systems extend or depend on others.
Engineering
A contract to build and test against, served as data through the content API.
Authors and experts
Cite clauses instead of copying them, and propose new rules straight from the prose.
Readers
Clear articles that always say which version they describe, with an annotated view down to the clause.
Where Clausary sits
CapabilityDocumentation toolsRequirements toolsClausary
Precise, numbered rulesNoYesYes
Readable explanationsYesNoYes
Explanations bound to the rulesNoNoYes
Immutable, citable versionsNoVariesYes
Evidence behind each changeNoNoYes
Tests for implementationsNoVariesYes

Systems in Practice runs on Clausary.

Its models, specifications, papers and research records are all written, versioned and governed in Clausary, and read by the public at systemsinpractice.com.

[Add: number of published models and papers]

Visit Systems in Practice
The public page for the Repayment Arrangement Machine model, version 2.2.0, on Systems in Practice: its version list, a permanent link to this version, the conformance package and the content hash, with an on-this-page list of clause sections

A real model page, as readers see it.

  • Every published version listed, each one fixed
  • A permanent link to cite this exact version
  • The conformance package to test against
  • A content hash that proves nothing changed

Built for teams in

  • Financial services and payments
  • Insurance and claims
  • Public services
  • Standards bodies
  • Operating-model consultancies

Bring one rule you're not sure of.

We'll model it with you, bind an explanation to it and test an implementation against it, in one session.