docs(readme): add bilingual DDN discoverability

README.fi.md

@@ -0,0 +1,152 @@
+[English](README.md) | **Suomi**
+
+# DDN — Deterministic Decision Network -referenssitoteutus
+
+Avoimen lähdekoodin referenssiarkkitehtuuri kryptografisesti todennettaville
+päätöksille, jotka suorittaa deterministinen, versioitu liiketoimintasääntö.
+
+DDN on referenssitoteutus, ei tuotantovalidaattoriverkko, eikä osoitus siitä,
+että taustalla oleva liiketoimintasääntö on oikea, reilu, lainmukainen tai
+sopiva tiettyyn käyttötarkoitukseen. Se näyttää konkreettisesti, miltä
+deterministinen policyn suoritus yhdistettynä kynnysarvopohjaisesti
+allekirjoitettuun attestointiin ja auditoitaviin päätöskuitteihin voi
+näyttää päästä päähän — policy-as-code-määrittelystä riippumattomaan
+kuitin todentamiseen asti, ilman että kenenkään tarvitsee luottaa
+koordinaattorin omaan väitteeseen siitä, että päätös on lopullinen.
+
+## Mikä DDN on
+
+Referenssipino käynnistää yhden Rust-validaattoribinäärin kolmena
+eristettynä aliprosessina samalla hostilla. Päätös hyväksytään vain, kun
+vähintään kaksi konfiguroidun kolmen jäsenen trusted validator setin
+jäsentä tuottaa keskenään yhtenevän Ed25519-allekirjoitetun attestoinnin
+samasta suoritustuloksesta. Kyseessä on kiinteä 2-of-3-luottamusmalli, ei
+permissionless-verkko eikä riippumattomien operaattoreiden välinen
+Byzantine-fault-tolerant-konsensusprotokolla.
+
+Hyväksytty päätös tuottaa sisältöosoitteisen `DecisionReceiptV1`-kuitin.
+Kuitti sisältää kunkin hyväksyvän validaattorin Ed25519-allekirjoitetun
+attestoinnin; koordinaattori ei lisää erillistä allekirjoitusta koko
+kuitin ylle. Standardi verifier tarkistaa attestoinnit, kynnyksen,
+request-bindingit, hashit, Merkle-todisteen ja konfiguroidun EVM-ankkurin.
+Policyn semantiikan uudelleensuoritus vaatii erillisen
+`replay-verify`-polun ja täsmällisen policy-paketin.
+
+Repositorio sisältää canonical JSON- ja crypto-toteutukset, WebAssemblyksi
+käännetyn deterministisen neuvottelupolicyn, TypeScript-API:n ja SDK:t,
+kuittiverifierin, Merkle-batchauksen, Solidity-ankkurisopimuksen ja
+selaindemon. Blocking full-chain E2E käyttää oikeita
+validaattorialiprosesseja, API:a, selainsovelluksia, paikallista
+Anvil-ketjua ja sopimusta ilman mockeja. Tämä väite ei koske jokaista
+yksikkötestiä.
+
+## Kenelle referenssi on tarkoitettu
+
+Referenssi on tarkoitettu insinööreille ja arkkitehdeille, jotka arvioivat
+arkkitehtuurimalleja automaattisille päätöksentekojärjestelmille, jotka
+tarvitsevat todennettavan jäljen — tiimeille, jotka tutkivat
+deterministisen policyn suoritusta, kynnysarvopohjaisesti allekirjoitettua
+attestointia tai auditoitavia päätöskuitteja suunnittelumallina, sekä
+turvallisuus- tai protokolla-arvioijille, jotka haluavat konkreettisen,
+ajettavan artefaktin tutkittavaksi whitepaperin sijaan. Se ei ole
+suoraan käyttöönotettava tuotantopalvelu, eikä sitä tarjota sellaisena.
+
+## Mitä päätöskuitti todistaa
+
+Kolmas osapuoli, joka vastaanottaa `DecisionReceiptV1`-kuitin ja ajaa
+julkaistun verifierin — luottamatta koordinaattorin "finalized"-väitteeseen
+— voi itsenäisesti tarkistaa, että:
+
+- syöte on kanonisoitu ja sidottu täsmällisiin policy-, manifest- ja
+  execution-profile-hasheihin;
+- vähintään kaksi kolmesta konfiguroidusta trusted-validaattorista on
+  itsenäisesti suorittanut saman WASM-policy-paketin ja tuottanut
+  keskenään yhtenevät Ed25519-allekirjoitetut attestoinnit tuloksesta;
+- kuitin muoto, hashit, request-bindingit, validaattori-identiteetit ja
+  -allekirjoitukset sekä konfiguroitu kynnysarvo ovat kaikki voimassa;
+- Merkle-todiste sitoo kuitin batch-juureen, ja juuri vastaa sitä, mitä
+  konfiguroitu EVM-ankkurisopimus palauttaa konfiguroidun
+  RPC-päätepisteen kautta — tähän mennessä osoitettu paikallisella
+  Anvil-ketjulla.
+
+## Mitä DDN ei todista
+
+- Että policyyn koodattu liiketoimintasääntö on oikea, reilu, lainmukainen
+  tai sopiva tiettyyn käyttötarkoitukseen. DDN todistaa, että policyn
+  suoritus tapahtui deterministisesti ja attestoitiin — ei sitä, että
+  itse sääntö on hyvä.
+- Että tavallinen verifier tarkisti policyn semantiikan. Se ei suorita
+  policya; vain erillinen `replay-verify`-polku, täsmällisellä
+  policy-paketilla, tekee sen.
+- Että kolme validaattoria ovat riippumatonta infrastruktuuria.
+  Referenssideploymentissa ne ovat yhden binäärin aliprosesseja samalla
+  hostilla saman operaattorin alla, eivät riippumattomien operaattoreiden
+  verkko.
+- Että ankkuri on julkisesti havaittavissa. Tässä osoitettu EVM-ankkurointi
+  ajetaan paikallisella Anvil-ketjulla, ei julkisessa testiverkossa tai
+  mainnetissa.
+- Että päätöstila säilyy. Koordinaattorin ja ankkurin repositoriot ovat
+  muistissa eivätkä säily uudelleenkäynnistyksen yli.
+- Että DDN tarjoaa KMS/HSM-pohjaisen avainten säilytyksen, rotaation tai
+  peruutuksen. Allekirjoitusavaimet ovat tässä referenssissä
+  paikallisia tiedostoja.
+- Että DDN arvioi tai varmentaa tekoälymallin vapaamuotoista päättelyä.
+  Järjestelmässä, joka hyödyntää myös LLM:ää tai muuta tekoälymallia,
+  DDN:n deterministinen policykerros voi toimia auditointirajana niille
+  päätöksen osille, jotka on koodattu policy-as-codena — mutta se ei
+  varmenna, rajoita eikä auditoi itse mallin päättelyä.
+- Että DDN käsittelee maksuja. Ei käsittele.
+
+## Referenssiarkkitehtuuri
+
+- `apps/` — TypeScript-palvelut (`api`, `coordinator`, `anchor-service`,
+  `explorer`, `demo-reference`) sekä Rust-validaattoripalvelu
+  (`apps/validator`).
+- `packages/` — jaetut kirjastot. `canonical-json` ja `crypto` sisältävät
+  sekä TypeScript- että Rust-toteutuksen, jotka on ristiinvarmennettu
+  toisiaan vasten jaettujen testivektoreiden avulla.
+- `policies/` — versioidut päätöspolicyt, kirjoitettu Rustilla, käännetty
+  WebAssemblyksi.
+- `contracts/` — Foundry (Solidity) -projekti, joka sisältää
+  decision-anchor-sopimuksen.
+- `infra/` — Dockerfilet toistettaville ja eristetyille
+  build-profiileille.
+
+Katso [CONTRIBUTING.md](./CONTRIBUTING.md) täydellinen repositorion
+rakenne ja arkkitehtuuripäätökset (ADR:t) hakemistosta `docs/decisions/`.
+
+## Nykyinen näyttö ja rajoitukset
+
+Nykyinen näyttö on tarkoituksella suppea:
+
+- kolme validaattoria ajetaan yhdellä hostilla samalla binäärillä;
+- EVM-ankkurointi on osoitettu vain paikallisella Anvil-ketjulla;
+- verifier luottaa konfiguroituun RPC-päätepisteeseen eikä ole light
+  client;
+- repositorio- ja idempotenssitila ovat muistissa eivätkä säily
+  uudelleenkäynnistyksen yli;
+- KMS/HSM:ää, avainrotaatiota tai riippumattomia validaattorioperaattoreita
+  ei ole toteutettu;
+- policyn toistettavuus on osoitettu pinnatulle Linux/arm64-profiilille;
+  Linux/amd64 on edelleen kokeellinen eikä julkaisuväite;
+- DDN ei käsittele maksuja eikä korvaa liiketoimintasääntöä, jota se
+  varmentaa;
+- tämä referenssitoteutus ei ole aktiivinen tuotantointegraatio.
+
+Lue [luottamusmalli](./docs/trust-model.md),
+[tunnetut rajoitukset](./docs/limitations.md) ja
+[uhkamalli](./docs/threat-model.md) ennen koodin arviointia tai ajamista.
+Vahvistettu julkisen projektin kuvaus löytyy
+[englanniksi ja suomeksi](./docs/public-project-description.md).
+
+## Aloittaminen
+
+Katso [CONTRIBUTING.md](./CONTRIBUTING.md) esivaatimukset, koko
+repositorion rakenne ja yleiset komennot (`pnpm install`, build/lint/test,
+policyn build ja verifiointi sekä oikea end-to-end-testisarja).
+
+## Tietoturva
+
+Katso [SECURITY.md](./SECURITY.md). Älä avaa julkista issueta epäillystä
+haavoittuvuudesta — käytä sen sijaan tämän repositorion GitHub Private
+Vulnerability Reportingia.

README.md

@@ -1,53 +1,143 @@
+**English** | [Suomi](README.fi.md)
+
 # DDN — Deterministic Decision Network reference implementation
 
-DDN is a reference implementation for checking significant decisions made
-by deterministic, versioned business rules. It is not a production validator
-network and it is not evidence that the underlying business rule is correct,
-fair, lawful, or suitable for a particular use.
+Open-source reference architecture for cryptographically verifiable decisions
+executed by deterministic, versioned business rules.
+
+DDN is a reference implementation, not a production validator network, and
+not evidence that the underlying business rule is correct, fair, lawful, or
+suitable for a particular use. It shows, concretely, what deterministic
+policy execution combined with threshold-signed attestation and auditable
+decision receipts can look like end to end — from a policy-as-code
+definition through independent receipt verification, without asking anyone
+to trust the coordinator's own claim that a decision was finalized.
+
+## What DDN is
 
 The reference stack starts one Rust validator binary as three isolated child
 processes on the same host. A decision is accepted only when at least two
-members of the configured three-member trusted validator set attest to the
-same execution result. This is a fixed 2-of-3 trust model, not a permissionless
-network or a Byzantine-fault-tolerant consensus protocol between independent
-operators.
+members of the configured three-member trusted validator set produce
+matching Ed25519-signed attestations over the same execution result. This is
+a fixed 2-of-3 trust model, not a permissionless network or a
+Byzantine-fault-tolerant consensus protocol between independent operators.
 
 An accepted decision produces a content-addressed `DecisionReceiptV1`. The
 receipt contains each agreeing validator's Ed25519-signed attestation; the
 coordinator does not add a separate signature over the receipt as a whole.
 The standard verifier checks the attestations, threshold, request bindings,
-hashes, Merkle proof and configured EVM anchor. Re-executing policy semantics
-requires the separate `replay-verify` path and the exact policy package.
+hashes, Merkle proof and configured EVM anchor. Re-executing policy
+semantics requires the separate `replay-verify` path and the exact policy
+package.
 
 The repository includes canonical JSON and crypto implementations, a
-deterministic negotiation policy compiled to WebAssembly, a TypeScript API and
-SDKs, a receipt verifier, Merkle batching, a Solidity anchor contract and a
-browser demo. The blocking full-chain E2E uses real validator subprocesses,
-API, browser applications, local Anvil chain and contract without mocks. That
-statement does not apply to every unit test.
+deterministic negotiation policy compiled to WebAssembly, a TypeScript API
+and SDKs, a receipt verifier, Merkle batching, a Solidity anchor contract
+and a browser demo. The blocking full-chain E2E uses real validator
+subprocesses, API, browser applications, local Anvil chain and contract
+without mocks. That statement does not apply to every unit test.
+
+## Who it is for
+
+This reference is for engineers and architects evaluating architectural
+patterns for automated decision systems that need a verifiable trail —
+teams researching deterministic policy execution, threshold-signed
+attestation, or auditable decision receipts as a design pattern, and
+security or protocol reviewers who want a concrete, runnable artifact to
+study rather than a whitepaper. It is not a drop-in production service and
+is not offered as one.
+
+## What a decision receipt proves
+
+A third party who receives a `DecisionReceiptV1` and runs the published
+verifier — without trusting the coordinator's "finalized" claim — can
+independently check that:
+
+- the input was canonicalized and bound to specific policy, manifest and
+  execution-profile hashes;
+- at least two of the three configured trusted validators independently
+  executed the same WASM policy package and produced matching
+  Ed25519-signed attestations over the result;
+- the receipt's shape, hashes, request bindings, validator identities and
+  signatures, and the configured quorum threshold are all valid;
+- a Merkle proof ties the receipt into a batch root, and that root matches
+  what the configured EVM anchor contract returns via the configured RPC
+  endpoint — demonstrated so far on a local Anvil chain.
+
+## What DDN does not prove
+
+- That the business rule encoded in the policy is correct, fair, lawful or
+  suitable for a given use. DDN verifies that policy execution happened
+  deterministically and was attested to — not that the policy itself is a
+  good rule.
+- That the ordinary verifier checked policy semantics. It does not execute
+  the policy; only the separate `replay-verify` path, given the exact
+  policy package, does that.
+- That the three validators are independent infrastructure. In the
+  reference deployment they are child processes of one binary on one host
+  under one operator, not a network of independent operators.
+- That the anchor is publicly observable. The EVM anchoring shown here runs
+  on a local Anvil chain, not a public testnet or mainnet.
+- That decision state persists. The coordinator and anchor repositories are
+  in memory and do not survive a restart.
+- That DDN provides KMS/HSM-backed key custody, rotation or revocation.
+  Signing keys are local files in this reference.
+- That DDN evaluates or verifies an AI model's free-form reasoning. In a
+  system that also relies on an LLM or other AI model, DDN's deterministic
+  policy layer can act as an audit boundary for the parts of a decision
+  that are encoded as policy-as-code — but it does not verify, constrain or
+  audit the model's own reasoning.
+- That DDN processes payments. It does not.
+
+## Reference architecture
+
+- `apps/` — TypeScript services (`api`, `coordinator`, `anchor-service`,
+  `explorer`, `demo-reference`) and the Rust validator service
+  (`apps/validator`).
+- `packages/` — shared libraries. `canonical-json` and `crypto` ship both a
+  TypeScript and a Rust implementation, cross-verified against each other
+  via shared test vectors.
+- `policies/` — versioned decision policies, written in Rust, compiled to
+  WebAssembly.
+- `contracts/` — a Foundry (Solidity) project with the decision-anchor
+  contract.
+- `infra/` — Dockerfiles for reproducible and isolated build profiles.
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for the full repository layout and
+the architectural decision records under `docs/decisions/`.
+
+## Current evidence and limitations
 
 Current evidence is intentionally narrow:
 
 - the three validators run on one host and use the same binary;
 - EVM anchoring has been exercised on a local Anvil chain only;
-- the verifier trusts its configured RPC endpoint and is not a light client;
-- repository and idempotency state are in memory and do not survive restart;
-- no KMS/HSM, key rotation or independent validator operators are included;
-- policy reproducibility is established for the pinned Linux/arm64 profile;
-  Linux/amd64 remains experimental and is not a release claim;
-- DDN neither processes payments nor replaces the business rule it verifies;
+- the verifier trusts its configured RPC endpoint and is not a light
+  client;
+- repository and idempotency state are in memory and do not survive
+  restart;
+- no KMS/HSM, key rotation or independent validator operators are
+  included;
+- policy reproducibility is established for the pinned Linux/arm64
+  profile; Linux/amd64 remains experimental and is not a release claim;
+- DDN neither processes payments nor replaces the business rule it
+  verifies;
 - this reference implementation is not an active production integration.
 
 Read [the trust model](./docs/trust-model.md),
 [known limitations](./docs/limitations.md), and
-[threat model](./docs/threat-model.md) before evaluating or running the code.
-The verified public-project wording is available in
+[threat model](./docs/threat-model.md) before evaluating or running the
+code. The verified public-project wording is available in
 [English and Finnish](./docs/public-project-description.md).
 
 ## Getting started
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for setup and common commands.
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for prerequisites, the full
+repository layout, and common commands (`pnpm install`, build/lint/test,
+policy build and verification, and the real end-to-end suite).
 
 ## Security
 
-See [SECURITY.md](./SECURITY.md).
+See [SECURITY.md](./SECURITY.md). Do not open a public issue for a
+suspected vulnerability — use GitHub Private Vulnerability Reporting on
+this repository instead.