Inputs and cost-effect certificates
Recognition Economics begins from the fixed physical structure of morality and ethics. Actions change moral states within that structure. This engine calculates accounting and network cost quantities; applying them to moral states requires identifying the actual people, physical relations, authored agreements and consequences. A selected numerical objective does not define the moral law.
The engine compares two records of one claim: the creditor's asset entry and the debtor's liability entry, each on its own books. It reports their differences, checks the books and calculates the effects of a proposed network rewrite. When an input contains only one side, it identifies the missing record.
Two rows sharing a document_id, one receivable from the creditor and one payable from the debtor, are treated as the two records of one claim. Their difference is the recorded gap. Matching documents, scope and dates against the actual obligation remains necessary. Agreement between records alone establishes neither truth nor consent.
Why the engine needs both parties’ books
ISO 20022 camt.053 statements, CCP position reports and trade repositories each carry one institution's view of each position. They are the who-owes-whom table, one number per link, and the theorems in the papers are about what that table cannot see. The two-record source is the pair of subledgers that already exists in every organisation: the receivables ledger of the creditor and the payables ledger of the debtor. The extract format below is what those two subledgers export when they are put side by side and matched on the document.
Format A: ledger-pair extract (CSV)
One row per entity per document line. Several rows for the same entity and document (invoice, credit note, partial payment) sum to that entity's record. Reader: actual_engine.load_ledger_pair_csv.
| column | required | meaning | what the engine does |
|---|---|---|---|
entity | yes | the organisation whose books this row is from | becomes a party; gets one free account equity |
counterparty | yes | the other party to the document | becomes a party; must agree across all rows of the document, else refused |
document_id | yes | the claim: invoice, note, contract line | becomes one relationship with a designated asset account AR:<id> on the creditor and a designated liability account AP:<id> on the debtor |
side | yes | receivable (this entity is the creditor) or payable (this entity is the debtor) | fixes which record the row is; any other value is refused |
amount | yes | signed amount in the extract's unit; a credit note or partial payment is a negative row | summed per (entity, document); the creditor's sum is the asset record, the debtor's sum the liability record; a non-number is refused |
currency | no | the unit | one unit per extract; a second currency is refused (the unit is the one free scalar of the calculus; conversion is a choice the engine will not make) |
as_of | no | the date the balance is stated at | carried into the report; the two records may bear different dates, which is what the genesis theorem says they will |
A document seen from one side only is a one-sided record: the engine uses zero as a placeholder for the missing entry and reports the input as one-sided. That placeholder is not evidence that the other party recorded zero. The resulting gap is a comparison with a placeholder and requires the missing record before it can be interpreted as a disagreement.
entity,counterparty,document_id,side,amount,currency,as_of Acme,Birch,INV-1001,receivable,1200.00,USD,2026-08-31 Birch,Acme,INV-1001,payable,1200.00,USD,2026-08-31 Cole,Acme,INV-3003,receivable,1000.00,USD,2026-08-31 Cole,Acme,INV-3003,receivable,-200.00,USD,2026-08-31 Acme,Cole,INV-3003,payable,1000.00,USD,2026-08-31 Acme,Cole,INV-3003,payable,-200.00,USD,2026-08-31
Format B: chart and books (JSON)
The engine's native form records parties, their accounts, relationships with their designated accounts, and balances. Use it when the books contain more than an AR/AP pair, such as cash accounts that are claims on an issuer, goods accounts or several designated accounts per counterparty. Reader: actual_engine.load_json.
{
"parties": ["Acme", "Birch", "Bank"],
"accounts": {
"Acme": ["AR:INV-1", "cash", "goods"],
"Birch": ["AP:INV-1", "cash", "goods"],
"Bank": ["owed:Acme", "owed:Birch"]
},
"relationships": [
{"id": "INV-1", "creditor": "Acme", "debtor": "Birch", "creditor_account": "AR:INV-1", "debtor_account": "AP:INV-1"},
{"id": "cash:Acme", "creditor": "Acme", "debtor": "Bank", "creditor_account": "cash", "debtor_account": "owed:Acme"},
{"id": "cash:Birch", "creditor": "Birch", "debtor": "Bank", "creditor_account": "cash", "debtor_account": "owed:Birch"}
],
"books": {
"Acme": {"AR:INV-1": 100, "cash": 20, "goods": -120},
"Birch": {"AP:INV-1": -100, "cash": -20, "goods": 120},
"Bank": {"owed:Acme": -20, "owed:Birch": 20}
},
"costs": [{"kind": "quadratic"}, {"kind": "J_log"}],
"share": 0.5
}
| field | meaning | refused when |
|---|---|---|
parties | the entities keeping books | empty (the degenerate input fails); duplicate names |
accounts | account names per party; an account no relationship designates is free | a party with no accounts |
relationships | one claim: creditor, debtor, the creditor's designated asset account, the debtor's designated liability account | creditor = debtor; an account designated by two relationships; an account that is an asset account for one relationship and a liability account for another; unknown party or account |
books | balances, debit positive: an asset record is positive, a liability record negative; unnamed accounts are zero | an account not in accounts |
costs | selected objectives: quadratic, J_amount with par, J_log, kinked with k. The exact recognition law is J(x) = (x + 1/x)/2 − 1 for positive x. A physical identification must supply the dimensionless multiplier; monetary amounts alone do not supply it. | unknown kind; nonfinite or negative k |
share | each creditor's allocation fraction (default one half). This input changes allocated charges, not the full incident cost or physical moral law. It does not record either party's acceptance. | cost-effect certificates refuse a nonfinite share or a value outside [0, 1] |
What comes out
The report first identifies what a who-owes-whom table omits: standing lines carrying nothing, differences between records, and any resulting change in who a rewrite affects. It then gives both records of every claim, their gap and dispute interval, followed by each party’s balances, nets and buffers.
For each selected cost, the report computes the cheapest rewrite at fixed positions, identifies who it reaches through a relationship that carried nothing, and gives the incident charge at the stated share. It closes with issuers, the sum of gaps and frozen parties. Every statement names its supporting theorem. These calculations describe the submitted books; they do not recommend a course of action.
Cost-effect certificate, schema version 2
placements.certify_rewrite checks a supplied proposal. certify_cheapest obtains a proposal from the numerical solver and requires it to report convergence. These are numerical calculations at stated tolerances. The certificate supplies no authored action or acceptance record, so consent_status is not_recorded.
| field | meaning |
|---|---|
charge_before, charge_after, change | Each party's allocated incident cost before and after the proposal, and their difference. |
non_worsened | The allocated change is at most tolerance. This comparison does not record consent. |
incident_cost_change | The sum of cost changes on every relationship incident to this party, without allocation weights. At half shares it equals twice the allocated change. Under the identified J-cost embedding it is the physical harm quantity. |
cost_increased_parties | Parties whose allocated change exceeds the tolerance. |
moved, drawn_in, bystanders_reached | Actual changes in the proposal, using a coordinate threshold of 1e-7. A kink introduces a marginal threshold; a sufficiently large rewrite can still reach a bystander. |
positions_fixed, tolerance | The incidence-weighted coordinate changes were checked against this finite, nonnegative tolerance. Nonfinite inputs, changes or costs are refused. |
The pair of certificates from certify_both_readings includes cost_comparisons_agree. This means that the two records give the same non-worsening classification for every party. It establishes neither truth of the amounts nor authorization of a rewrite.
Migrating historical certificate consumers
New certificates replace consents with non_worsened, and non_consenting with cost_increased_parties. Replace the old harm calculation with incident_cost_change when the intended quantity is the full incident change. These quantities can differ at unequal shares. For example, moving a J-cost of 1/4 from a creditor-side relation to a debtor-side relation leaves full incident cost unchanged; at creditor share 1/4 the allocated charge rises by 1/8.
The compatibility function legacy_cost_aliases(cert) exposes deprecated field names. Its harm field equals twice the allocated change, including at unequal shares; the name supplies no physical identification or consent. Use schema version 2 for reports.
Interpreting the results
The engine retains the submitted currency, figures and allocation parameter. It does not determine an actual obligation from the interval between records, infer authorization from benefit, or turn a numerical minimum into a moral recommendation. Those conclusions require the relevant physical relations, authorship, agreements and history. The governing moral law is fixed throughout.