Why Ekwo OS is shaped the way it is: one record per decision, each with its context, the rule it sets and what follows from it, so that a contributor can argue with the reason rather than guess at it.
Each record is written as the rule it establishes and states what holds today.
A decision that changes is rewritten in place, and its record says what the
rule now is; the history of the change is in the git log and in
CHANGELOG.md.
A record has five parts: Status, Context, Decision,
Consequences and See also (the files, migrations, tests and other
records it relies on). New records take the next free number. A record whose
status is proposed is a design no code carries yet: it says what would hold
and what it waits for, and it becomes accepted in the change that builds it.
A weakness that is still open is not written here. The records are public,
and a record describing a gap an attacker could still use would be a recipe.
A security issue goes first through a private advisory, as
SECURITY.md describes; the record that tells its story
is written, or rewritten, once the fix has shipped, and names the release that
carries it. A limit that is accepted by design — stated, reasoned and not
exploitable beyond what the design allows — belongs in a record like any other
consequence.
The instance and who may act
- 0001 — One installation belongs to one customer
- 0065 — A shared instance keeps its tenants apart
- 0002 — The surface is closed, not merely empty
- 0003 — The schema grants its own rights
- 0004 — A permission is a capability; a role is a preset
- 0005 — A guard answers true or false, and reads as the schema
- 0006 — A machine key is a caller narrower than a person
- 0007 — An invitation names an address, not a user id
The ledger
- 0008 — Documents and entries are two joined layers
- 0069 — A piece goes on its document
- 0076 — An analytic value is entered on the line, and read from the ledger
- 0009 — Accounts have types and are resolved by role
- 0010 — Amounts are positive; totals are derived
- 0011 — An amount is rounded at the decimals of its currency
- 0012 — A number is drawn at posting, from the country's pattern
- 0013 — Locks live in the database, and everything raises
- 0014 — A posted entry is immutable, in an open period too
- 0015 — A posted document is frozen
- 0016 — A correction is one gesture
- 0017 — An append-only audit trail surrounds the ledger
- 0018 — Reports read the ledger and know no country
Taxes
- 0019 — A tax posting carries the account and the box
- 0020 — One tax engine, several kinds of tax
- 0021 — Cash-basis VAT waits; exchange differences are realised
- 0022 — A price that holds its tax is converted per group
- 0077 — A tax computed inside its own base is one key of the tax
- 0080 — A regime where one tax on turnover replaces VAT
- 0079 — A tax collected for the next links of the chain, on a presumed base (proposed)
- 0023 — Declaration boxes are data, with no expression language
- 0024 — A tax follows the territory of the parties
- 0083 — A tax lands by its code, not on a line
Country packs
- 0025 — A country is a pack of data, compiled into SQL
- 0026 — Ekwo maintains a pack; only an accountant reviews one
- 0027 — The sources of a pack are a register, not a bibliography
- 0028 — A pack upgrade is never silent
- 0029 — A golden year is the contract of a pack
- 0030 — A country has charts, and a financial statement is data
- 0031 — Opening and closing are parameters, not code
- 0032 — The audit file carries opening balances, never posted
- 0067 — An opening on the day of the takeover, with its open items
- 0068 — An analysis for every country, by account type
- 0033 — What a country requires on a document is data
- 0034 — A label is data, and a declared language is a promise
- 0035 — The chart stays whole; the working list is derived
Declarations
- 0036 — Filing cadence is data, counted in months
- 0037 — A filed declaration is frozen and superseded, not edited
- 0038 — A deadline is a rule of the country; null is an answer
- 0039 — A deposit is an event, written from the frozen figures
- 0040 — A portfolio is what the caller may read
- 0066 — A filing is proved by its hash, on a public ledger
- 0087 — A declaration is paid to a contact the pack names, and is paid when its debt is matched
- 0088 — A deposit is written by the core's functions, and the administration is named in the company's language
Companies, documents and the bank
- 0041 — A company has a profile; its first year is a parameter
- 0042 — A document is shared by a link that is the whole secret
- 0043 — A company leaves with its books
- 0044 — A product is a catalogue entry in the core, not stock
- 0078 — A line names what was sold, by the classification its country declares
- 0045 — A counterparty is recognised from learned patterns
- 0046 — Settling applies identification, offers resemblance
- 0047 — A bank statement is imported once
- 0070 — A third-party line that names nobody is named once
- 0071 — Several lines settle together, and a small difference is booked
- 0072 — A line may be left unnamed, and a name among several is a doubt
- 0073 — The sure pairs are matched in one gesture, and what undoes an entry is matched as it is posted
- 0074 — Two contacts of one company are merged, and the absorbed one is retired
- 0075 — The contacts that are probably one party are proposed
- 0081 — A company is archived before it leaves, and deleted by its owner by name
- 0082 — A company numbers its documents its own way, and a change continues the series
- 0091 — A document sent from a phone is a draft purchase, and waits for its contact
- 0092 — A late payment mention is the company's choice, on an invoice to a business
- 0094 — An archive is read in pages, and is the same archive
Formats and modules
- 0048 — Format libraries are MIT, one package per format
- 0049 — A statement reader reports and never corrects
- 0050 — An invoice file is written from the books
- 0051 — A module has its own schema and posts through a function
- 0090 — The socle has its own schema,
ekwo(proposed) - 0063 — A module code outlives its names
- 0084 — A contract issues drafts of the socle
- 0085 — One reader for a received invoice, and the model's part is data
- 0086 — A company files under a VAT scheme, and its scheme decides its forms
- 0095 — A group of companies is owned by its parent, and reads its members as the caller
- 0096 — An operation between companies of a group is paired by their identifiers and its number, never guessed
- 0097 — A group translates a member's currency at the rates it sets itself, by the closing rate method
Installer, command line and MCP server
- 0052 — The installer needs only Node and the customer's project
- 0053 — The MCP server acts as the user
- 0064 — A key writes as the person who issued it
- 0089 — An agent posts in the mode its company chose: review or autopilot
- 0054 — The command line answers one document and an exit code
- 0055 — The command line acts as a signed-in person
- 0056 — The command line computes no amount
- 0057 — Two install paths make one installation
- 0058 —
ekwo doctorcompares against a generated inventory - 0059 — A release has a tag, a schema version and a schema floor