@nomosprotocol/sdk 2.5.0 → 2.7.0

package/README.md

@@ -97,6 +97,39 @@ can return their own chains with what they sign (`keyCerts`). On the relying par
 (NOMOS-SPEC-007 rev. 1.10). Revocations are never forgotten, and without a current list
 `accept()` answers 503 instead of committing.
 
+**Which laws govern the act (2.7.0).** An Act carries one authority, so on its own `accept()` checks
+the law the carrier chose. Pin registrars and `accept()` works out every law that governs the act here,
+now, and commits only if the Act carries every one (NOMOS-SPEC-014, Draft):
+
+```ts
+import { accept, registrarSource } from '@nomosprotocol/sdk';
+
+const platform = registrarSource({
+  id: 'platform',
+  url: 'https://www.nomosprotocol.com',
+  publicKeyPem: PLATFORM_KEY_PEM,   // pinned by you; heads signed by any other key are refused
+});
+
+const rp = accept({
+  // ...relyingPartyId, root, authorities (with registrarName), commit, as above
+  resolution: {
+    registrars: [platform],
+    // From YOUR knowledge and state, never from the Act: a carrier that stated its own
+    // jurisdiction would choose the law again.
+    context: (act, localFacts) => ({ jurisdiction: 'AE', established_in: 'DIFC', subjects_in: 'AE', output_used_in: 'AE' }),
+  },
+});
+```
+
+If another law also governs the act, the Act is held (`422 INCOMPLETE`, `reason_code:
+'laws_not_presented'`, the laws named) and nothing is committed. A context fact you leave out holds it
+too (`resolution_incomplete`, naming the fact). A registrar that cannot be read, a head older than
+`maxHeadAgeSeconds`, a head signed by a key you did not pin, or a log whose history was rewritten
+answers 503 with Retry-After. Receipts record the resolution (status, context, laws, log heads).
+Create each `registrarSource()` once and reuse it: the check that a registrar's history was only ever
+added to spans the source's lifetime (pass `initialHead` to carry the last head across restarts).
+Without `resolution`, `accept()` is unchanged.
+
 **The other roles** are one call each:
 - `issuer()` publishes your sealed policies and certificates;
 - `witness()` turns an existing lookup into signed statements;
@@ -122,9 +155,55 @@ It abstracts three different authority situations behind one call and one verdic
 | A public authority published on the NOMOS Exchange         | `nomos.can({ authority, ...facts })`                                |       No |
 | Your organization's sealed artifact                        | `client.can({ artifact_id, ...facts })`                             |      Yes |
 | A sealed artifact presented directly by an agent or system | `nomos.can({ artifact, key_certs, root_public_key_pem, ...facts })` |       No |
+| An act, and you don't know which laws govern it            | `nomos.can({ context, ...facts })`                                  |       No |
 
 The caller does not need to know which evaluation rail is being used. `can()` routes internally based on what you provide.
 
+### 0. Ask by context: let NOMOS find the laws (2.6.0)
+
+Naming a law lets the caller choose which law is checked, and leave out the strict one. Describe
+the act instead, and NOMOS works out which laws govern it, asks every one, and combines the answers:
+any deny denies, and a yes needs every law to say yes.
+
+```ts
+import { can } from '@nomosprotocol/sdk';
+
+const v = await can({
+  context: {
+    jurisdiction: 'AE',        // where the act takes effect
+    established_in: 'DIFC',    // where your organisation is incorporated or established
+    subjects_in: 'AE',         // where the people it concerns are
+    output_used_in: 'AE',      // where any AI output is used
+  },
+  action: 'share_customer_data_with_analytics_vendor',
+  processing_fair_and_transparent: false,
+});
+
+v.mode;            // 'resolution'
+v.verdict;         // 'DENIED': a DIFC firm acting in mainland Dubai answers to DIFC law
+v.answered_under;  // ['difc-data-protection-law-difc-law-no-5-of-2020']
+v.coverage;        // what the answer covers, in words
+v.members;         // each law's own answer, each a signed record (query_id)
+```
+
+What can come back besides a verdict:
+
+- `INSUFFICIENT_DATA` with `open_facts`: a fact that decides which law applies was not stated
+  (for example `established_in`). It is asked for, never assumed.
+- `INSUFFICIENT_DATA` for a place the registrar does not cover (Saudi Arabia, the US, an ADGM or
+  QFC firm today). "No law found" is never read as "no law applies".
+- `CONFLICT`: two registrars each claim exclusive precedence. A person decides.
+
+Which laws apply where comes from the NOMOS registrar: a signed, append-only list in the public
+log at `/.well-known/nomos-exchange-log`, verifiable offline. Each claim states the provision it
+rests on. It currently covers the EU AI Act, Qatar Law No. 13 of 2016, UAE Federal Decree-Law
+No. 45 of 2021 and DIFC Law No. 5 of 2020, and lists only its own laws, so other law may also
+apply. Only want the list of laws? `POST /api/v1/resolve { context }` returns it without asking
+them, and records nothing.
+
+The system that commits the change can resolve too, from registrars it pins and a context it supplies
+itself: see `accept({ resolution })` above (2.7.0).
+
 ### 1. Public authority
 
 Ask a published authority directly:
@@ -187,7 +266,11 @@ import { Nomos } from "@nomosprotocol/sdk";
 
 const client = new Nomos(process.env.NOMOS_API_KEY!);
 const r = await client.can(
-  { authority: "data-protection-law-difc-law-no-5-of-2020", days_since_access_request: 45 },
+  { authority: "difc-data-protection-law-difc-law-no-5-of-2020",
+    ...allTwelveNo,                 // the law's intake questions, listed on its page
+    q_individual_request: true,     // "yes": a request from a person
+    access_request_received: true, days_since_access_request: 45,
+    identity_doubt_unresolved: false, response_period_extended_with_notice: false },
   { awaitApproval: { timeoutMs: 10 * 60_000, onApproval: (a) => console.log("waiting on", a.url) } },
 );
 
@@ -196,6 +279,14 @@ else console.log(r.verdict, r.approval?.status); // DENIED, or rejected / timed_
 ```
 
 The approval is bound to the authority, the action and the facts: different facts need a new one.
+
+A large law carries a few yes/no **intake questions** (listed on its page). Each "no" rules out the
+articles it covers, so an ordinary action gets a firm answer in one call: on the DIFC Data Protection
+Law, all twelve "no" is `AUTHORIZED`.
+
+When a listing is replaced by a newer version and retired, calls to the old address throw a
+`NomosAPIError` with status 410: the message names the new version's address. Move to it; the old
+address is never answered from the old rules.
 When the law gets a new version, you get an email with what changed. Turn either email off on the
 same page.