create-arxo 0.2.0 → 0.2.2

package/README.md

@@ -1,4 +1,37 @@
 # create-arxo
 
-`npm create arxo` copies a project that opens `de.bgb.fristen@0.1.0` and asks
-one `truth` question.
+```
+npm create arxo@latest my-app
+cd my-app && npm install && npm start
+```
+
+```
+de.bgb.fristen@0.1.0 opened (local)
+
+Does a 14-day period from 2026-03-06 end on 2026-03-20?
+  evaluationStatus  COMPUTED
+  truthStatus       TRUE_ONLY  (established: yes)
+  rules applied     TagesfristEnde
+  hashes
+    program  sha256:…
+    result   sha256:…
+  document          … bytes, canonical evaluation document
+```
+
+The project is TypeScript (`tsx`, no build step): `src/ask.ts` opens the
+pinned canon `de.bgb.fristen@0.1.0` (§§ 187, 188 BGB, installed with
+`@arxo/canon-bgb-fristen`), asks one `truth` question and prints the
+answer — statuses, the rule applied, sources, hashes, the attached
+evaluation document. It then asks the same question **without** the
+duration and shows how `whyNot` turns into a request for the missing fact.
+
+Scripts of the created project:
+
+| Command | What it does |
+|---|---|
+| `npm start` | runs `src/ask.ts` |
+| `npm test` | the same question as a `node --test` test |
+| `npm run typecheck` | checks predicate names against the canon's declarations |
+
+Next: https://docs.arxo.io/guide/quickstart/ and
+https://docs.arxo.io/guide/reading-an-answer/.

package/index.js

@@ -1,13 +1,21 @@
 #!/usr/bin/env node
-import { cpSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { dirname, join } from 'node:path';
+import { cpSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const HERE = dirname(fileURLToPath(import.meta.url));
 const dest = process.argv[2] ?? 'arxo-app';
 mkdirSync(dest, { recursive: true });
 cpSync(join(HERE, 'template'), dest, { recursive: true });
+// npm renames .gitignore inside a published package, so the template ships _gitignore.
+if (existsSync(join(dest, '_gitignore'))) renameSync(join(dest, '_gitignore'), join(dest, '.gitignore'));
 const pkg = JSON.parse(readFileSync(join(dest, 'package.json'), 'utf8'));
-pkg.name = dest.replace(/[^a-z0-9-._]/gi, '-').toLowerCase();
+pkg.name = basename(resolve(dest)).replace(/[^a-z0-9-._]/gi, '-').toLowerCase();
 writeFileSync(join(dest, 'package.json'), `${JSON.stringify(pkg, null, 2)}\n`);
-console.log(`created ${dest}`);
+console.log(`created ${dest}
+
+Next:
+  cd ${dest} && npm install && npm start
+
+  npm start  — asks the canon one question and prints the answer with its proof
+  npm test   — the same question as a test`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-arxo",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Scaffold an Arxo Law project with one canon and one question",
   "license": "Apache-2.0",
   "type": "module",

package/template/README.md

@@ -0,0 +1,39 @@
+# arxo-app
+
+One canon, one question, answered by the Arxo engine with a proof.
+
+```
+npm install
+npm start
+```
+
+`src/ask.ts` opens the pinned canon `de.bgb.fristen@0.1.0` (§§ 186–213 BGB,
+installed with `@arxo/canon-bgb-fristen`) and asks: an event on 6 March 2026
+starts a period of 14 days — does it end on 20 March 2026?
+
+You will see:
+
+- `evaluationStatus COMPUTED` and `truthStatus TRUE_ONLY` — the engine
+  established the answer; a refusal would be a status, not an exception;
+- the rule applied and the sources behind it; the hashes that make the
+  answer reproducible; the size of the attached evaluation document;
+- the same question asked again **without the duration**: the answer is
+  `NEITHER`, `whyNot` names the premises the rule needs, and the program
+  asks you to add `frist_dauer_tage`.
+
+Facts and their meaning:
+
+| Fact | Meaning |
+|---|---|
+| `frist_ereignis(frist, 2026-03-06)` | the event that starts the period (§ 187 (1) BGB) |
+| `frist_dauer_tage(frist, 14 calendar_day)` | the length of the period in days (§ 188 (1) BGB) |
+| `frist_ende(frist, 2026-03-20)` | the question: does the period end on this date? |
+
+`npm test` runs the same question as a test; `npm run typecheck` checks
+the predicate names against the canon's declarations.
+
+Next:
+
+- Quickstart: https://docs.arxo.io/guide/quickstart/
+- Reading an answer (statuses, `whyNot`, proof, hashes): https://docs.arxo.io/guide/reading-an-answer/
+- More canons and questions: `npm view @arxo/law readme`

package/template/_gitignore

@@ -0,0 +1 @@
+node_modules/

package/template/package.json

@@ -1,12 +1,24 @@
 {
   "name": "arxo-app",
   "private": true,
+  "version": "0.1.0",
   "type": "module",
+  "description": "One canon, one question: §§ 187, 188 BGB with @arxo/law",
   "scripts": {
-    "test": "node --test test/"
+    "start": "tsx src/ask.ts",
+    "test": "node --import tsx --test test/frist.test.ts",
+    "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@arxo/law": "0.2.0",
-    "@arxo/canon-bgb-fristen": "0.1.2"
+    "@arxo/law": "0.3.0",
+    "@arxo/canon-bgb-fristen": "0.1.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0"
+  },
+  "engines": {
+    "node": ">=20"
   }
 }

package/template/src/ask.ts

@@ -0,0 +1,121 @@
+/**
+ * One canon, one question.
+ *
+ * §§ 187, 188 BGB (German Civil Code): an event on 6 March 2026 starts a
+ * period of 14 days. Does the period end on 20 March 2026?
+ *
+ * The answer is computed by the Arxo engine from the pinned canon
+ * `de.bgb.fristen@0.1.0` (installed with `@arxo/canon-bgb-fristen`); the
+ * canonical evaluation document that proves it is attached to the answer.
+ *
+ * Run: npm start
+ */
+import { open, type Answer, type CaseInput, type Fact } from '@arxo/law';
+// Type-only import: the canon registers its relation names in
+// `CanonRegistry`, so a misspelled predicate is an editor error.
+import type { RelationName } from '@arxo/canon-bgb-fristen';
+
+// `frist` names the period we ask about; the values are bare and typed by
+// the canon's declarations (a Date, a Quantity of days).
+const EVENT_DATE = '2026-03-06';
+const CANDIDATE_END = '2026-03-20';
+
+// frist_ereignis — the event that starts the period (§ 187 (1) BGB:
+// the day of the event itself is not counted).
+const eventFact: Fact = { predicate: 'frist_ereignis', args: ['frist', EVENT_DATE] };
+// frist_dauer_tage — the length of the period in days (§ 188 (1) BGB:
+// a period stated in days ends with the expiry of its last day).
+const durationFact: Fact = { predicate: 'frist_dauer_tage', args: ['frist', '14 calendar_day'] };
+
+// frist_ende(frist, date) — does the period end on this date?
+const question: RelationName = 'frist_ende';
+
+function caseInput(facts: Fact[]): CaseInput {
+  return {
+    // The date the question is asked on the legal axis; never "today".
+    legalTime: '2026-09-17',
+    timezone: 'Europe/Berlin',
+    // How days are counted is a policy of the canon, named explicitly.
+    deadlinePolicy: 'urn:de:corpus:clir:bgb-fristen#BGB_FRISTEN_TAG',
+    answers: facts,
+  };
+}
+
+const TRUTH: Record<string, string> = {
+  TRUE_ONLY: 'established: yes',
+  FALSE_ONLY: 'established: no',
+  NEITHER: 'not established either way',
+  BOTH: 'contradictory',
+};
+
+const localName = (id: unknown): string => String(id).split('#').pop() ?? String(id);
+
+function describe(label: string, r: Answer): void {
+  console.log(`\n${label}`);
+  console.log(`  evaluationStatus  ${r.evaluationStatus}`);
+  console.log(`  truthStatus       ${r.truthStatus ?? '—'}  (${TRUTH[r.truthStatus ?? ''] ?? 'see the document'})`);
+
+  // The proof graph: which rules of the canon were applied.
+  const rules = (r.proof?.nodes ?? [])
+    .filter((n) => n.kind === 'rule_application' && n.rule)
+    .map((n) => localName(n.rule));
+  console.log(`  rules applied     ${rules.length ? [...new Set(rules)].join(', ') : '—'}`);
+
+  // The norms behind the answer, with their pinned text, when the canon
+  // anchors its rules to the source (§ 187, § 188 BGB here).
+  const sources = Array.isArray(r.sources) ? r.sources : [];
+  if (sources.length) {
+    for (const s of sources) console.log(`  source            ${JSON.stringify(s)}`);
+  } else {
+    console.log('  sources           none anchored in this canon version — see the rule names above');
+  }
+
+  // Reproducibility: the same canon, case and semantics give the same hashes.
+  console.log('  hashes');
+  for (const [k, v] of Object.entries(r.hashes)) console.log(`    ${k.padEnd(8)} ${v}`);
+
+  if (r.via === 'local') {
+    console.log(`  document          ${r.document.byteLength} bytes, canonical evaluation document`);
+  }
+}
+
+const fristen = await open('de.bgb.fristen@0.1.0', { offline: true });
+console.log(`${fristen.name}@${fristen.version} opened (${fristen.via})`);
+
+// 1. Both facts given: is 20 March 2026 the end of the period?
+const answer = await fristen.truth(question, ['frist', CANDIDATE_END], caseInput([eventFact, durationFact]));
+describe(`Does a 14-day period from ${EVENT_DATE} end on ${CANDIDATE_END}?`, answer);
+
+// 2. The same question without the duration: the engine does not guess.
+//    `whyNot` returns the blocker graph — the premises each rule needs —
+//    and the application turns it into a request for the missing facts.
+const partial = await fristen.whyNot(question, ['frist', CANDIDATE_END], caseInput([eventFact]));
+describe(`The same question without frist_dauer_tage (why not?)`, partial);
+
+console.log(`  whyNot            ${partial.whyNot && Array.isArray(partial.whyNot) && partial.whyNot.length
+  ? partial.whyNot.map((w) => `${w.kind}: ${w.description}`).join('; ')
+  : 'no input requirement raised by the engine — the rule stays undetermined'}`);
+
+type Blocker = { rule?: string; conjuncts?: Array<{ literal?: { predicate?: string }; trigger?: string }> };
+const blockers: Blocker[] =
+  partial.value && typeof partial.value === 'object' && 'value' in partial.value
+    ? ((partial.value as { value?: { blockers?: Blocker[] } }).value?.blockers ?? [])
+    : [];
+const given = new Set([eventFact].map((f) => f.predicate));
+// Ask only for what the rules your facts already speak to still need; a
+// rule none of your facts touch is another route to the same conclusion.
+const missing = new Set<string>();
+for (const b of blockers) {
+  const needs = (b.conjuncts ?? []).map((c) => localName(c.literal?.predicate)).filter(Boolean);
+  const touched = needs.some((p) => given.has(p));
+  console.log(`  rule ${localName(b.rule).padEnd(17)} needs ${needs.join(', ')}${touched ? '' : '   (another route)'}`);
+  if (touched) for (const p of needs) if (!given.has(p)) missing.add(p);
+}
+const HINT: Record<string, string> = {
+  frist_ereignis: 'the event that starts the period, e.g. "2026-03-06"',
+  frist_dauer_tage: 'the length of the period in days, e.g. "14 calendar_day"',
+};
+if (missing.size) {
+  console.log('\nTo answer, please add:');
+  for (const p of missing) console.log(`  - ${p}: ${HINT[p] ?? 'see `fristen.questions()` for the declared type'}`);
+}

package/template/test/{frist.test.mjs → frist.test.ts}

@@ -1,16 +1,14 @@
 import assert from 'node:assert/strict';
 import test from 'node:test';
 import { open } from '@arxo/law';
+import type { RelationName } from '@arxo/canon-bgb-fristen';
 
 test('opens the bundled canon and asks one question', async () => {
-  const wasmPath = process.env.ARXO_WASM;
-  const fristen = await open('de.bgb.fristen@0.1.0', {
-    offline: true,
-    ...(wasmPath ? { wasmPath } : {}),
-  });
+  const fristen = await open('de.bgb.fristen@0.1.0', { offline: true });
   assert.equal(fristen.name, 'de.bgb.fristen');
   // 14 days from 6 March 2026, § 187 (1) and § 188 (1) BGB: does the period end on 20 March?
-  const r = await fristen.truth('frist_ende', ['frist', '2026-03-20'], {
+  const question: RelationName = 'frist_ende';
+  const r = await fristen.truth(question, ['frist', '2026-03-20'], {
     legalTime: '2026-09-17',
     timezone: 'Europe/Berlin',
     deadlinePolicy: 'urn:de:corpus:clir:bgb-fristen#BGB_FRISTEN_TAG',
@@ -22,5 +20,17 @@ test('opens the bundled canon and asks one question', async () => {
   assert.equal(r.via, 'local');
   assert.equal(r.evaluationStatus, 'COMPUTED');
   assert.equal(r.truthStatus, 'TRUE_ONLY');
-  assert.ok(r.document.byteLength > 0, 'the evaluation document is attached');
+  assert.ok(r.via === 'local' && r.document.byteLength > 0, 'the evaluation document is attached');
+});
+
+test('without the duration the answer is NEITHER, not a guess', async () => {
+  const fristen = await open('de.bgb.fristen@0.1.0', { offline: true });
+  const r = await fristen.truth('frist_ende', ['frist', '2026-03-20'], {
+    legalTime: '2026-09-17',
+    timezone: 'Europe/Berlin',
+    deadlinePolicy: 'urn:de:corpus:clir:bgb-fristen#BGB_FRISTEN_TAG',
+    answers: [{ predicate: 'frist_ereignis', args: ['frist', '2026-03-06'] }],
+  });
+  assert.equal(r.evaluationStatus, 'COMPUTED');
+  assert.equal(r.truthStatus, 'NEITHER');
 });

package/template/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noEmit": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["src", "test"]
+}