lawspec 0.26.0 → 0.28.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (55) hide show
  1. package/CHANGELOG.md +178 -1
  2. package/NORMALIZATION-LICENSES.txt +296 -0
  3. package/README.md +8 -0
  4. package/bin/lawspec.mjs +126 -33
  5. package/build.json +159 -131
  6. package/builtin-data-names.mjs +4 -4
  7. package/core.wasm +2 -2
  8. package/core_jsffi.js +5 -5
  9. package/doctor.mjs +14 -4
  10. package/examples/native-payments/elixir/lib/payments_domain.ex +1 -1
  11. package/examples/native-payments/erlang/src/payments_domain.erl +1 -1
  12. package/examples/native-payments/prolog/lawspec.json +20 -0
  13. package/examples/native-payments/prolog/src/domain/payments.pl +23 -0
  14. package/examples/native-payments/prolog/tests/domain/payment_generators.pl +17 -0
  15. package/examples/rc1/bit-codec.lawspec +6 -6
  16. package/examples/rc1/native-payments.lawspec +6 -6
  17. package/examples/rc1/nesting/rrr.lawspec +2 -2
  18. package/examples/rc1/nesting/rru.lawspec +4 -4
  19. package/examples/rc1/nesting/rur.lawspec +4 -4
  20. package/examples/rc1/nesting/ruu.lawspec +5 -5
  21. package/examples/rc1/nesting/urr.lawspec +4 -4
  22. package/examples/rc1/nesting/uru.lawspec +5 -5
  23. package/examples/rc1/nesting/uur.lawspec +5 -5
  24. package/examples/rc1/nesting/uuu.lawspec +6 -6
  25. package/examples/rc1/recursive-records.lawspec +5 -5
  26. package/examples/rc1/refund-policy.lawspec +4 -0
  27. package/examples/specs/approvals.lawspec +3 -3
  28. package/examples/specs/builtins.lawspec +2 -2
  29. package/examples/specs/collections.lawspec +8 -8
  30. package/examples/specs/composition.lawspec +10 -10
  31. package/examples/specs/contracts.lawspec +2 -2
  32. package/examples/specs/crypto.lawspec +2 -2
  33. package/examples/specs/domain_modeling.lawspec +20 -0
  34. package/examples/specs/flow_stack.lawspec +4 -4
  35. package/examples/specs/generation.lawspec +2 -2
  36. package/examples/specs/limits.lawspec +1 -1
  37. package/examples/specs/list_contracts.lawspec +3 -3
  38. package/examples/specs/lists.lawspec +6 -6
  39. package/examples/specs/matching.lawspec +8 -8
  40. package/examples/specs/payments.lawspec +5 -5
  41. package/examples/specs/records.lawspec +4 -4
  42. package/examples/specs/refinements.lawspec +4 -0
  43. package/examples/specs/resilience.lawspec +2 -2
  44. package/examples/specs/resources.lawspec +5 -5
  45. package/examples/specs/sequences.lawspec +1 -1
  46. package/examples/specs/sum_refinements.lawspec +11 -11
  47. package/examples-command.mjs +3 -1
  48. package/index.d.ts +160 -4
  49. package/native-evidence.mjs +25 -12
  50. package/native-examples.mjs +1 -1
  51. package/package.json +2 -1
  52. package/proof.d.ts +57 -12
  53. package/proof.mjs +277 -13
  54. package/templates.mjs +84 -3
  55. package/test-command.mjs +40 -4
package/index.d.ts CHANGED
@@ -16,7 +16,12 @@ export type Target =
16
16
  'scala' |
17
17
  'groovy' |
18
18
  'clojure' |
19
- 'swift';
19
+ 'swift' |
20
+ 'prolog' |
21
+ 'hcl' |
22
+ 'yaml' |
23
+ 'antlr4' |
24
+ 'make';
20
25
 
21
26
  export interface Source {
22
27
  path: string;
@@ -425,13 +430,16 @@ export type DischargeStatus =
425
430
  'known-failing' |
426
431
  'flaky' |
427
432
  'skipped' |
433
+ 'pending' |
428
434
  'proved' |
429
435
  'exhaustively-checked' |
430
436
  'property-tested' |
431
437
  'measured' |
432
438
  'runtime-checked' |
433
439
  'default-handler' |
434
- 'assumed';
440
+ 'assumed' |
441
+ 'exempted' |
442
+ 'refuted';
435
443
 
436
444
  export interface ObligationEvidence {
437
445
  owner: string;
@@ -440,6 +448,7 @@ export interface ObligationEvidence {
440
448
  status: DischargeStatus;
441
449
  reason: string;
442
450
  claim: Expr | null;
451
+ exemption?: Exemption;
443
452
  environment?: string;
444
453
  environmentRun?: AttestedRun;
445
454
  against?: AttestedDependency[];
@@ -532,8 +541,84 @@ export interface CheckRequest {
532
541
  packages?: Package[];
533
542
  cacheDirectory?: string;
534
543
  attestation?: unknown;
544
+ proofCounterexamples?: ProofCounterexample[];
545
+ analysisResults?: AnalysisResult[];
546
+ projectVersion?: string;
547
+ now?: string;
548
+ modelResults?: ModelResult[];
535
549
  }
536
550
 
551
+ export interface ModelResult {
552
+ fingerprint: string;
553
+ outcome: string;
554
+ values: string;
555
+ invariant: string;
556
+ }
557
+
558
+ export interface ModelTaskRow {
559
+ owner: string;
560
+ declaration: string;
561
+ tasks: ModelTask[];
562
+ }
563
+
564
+ export interface ModelTask {
565
+ fingerprint: string;
566
+ kind: string;
567
+ script: string;
568
+ inputs: string[];
569
+ }
570
+
571
+ export interface Exemption {
572
+ reason: string;
573
+ until: string | null;
574
+ expired: boolean;
575
+ law: string | null;
576
+ }
577
+
578
+ export interface AnalysisResult {
579
+ fingerprint: string;
580
+ outcome: string;
581
+ values: string;
582
+ }
583
+
584
+ export type AnalysisStage = 'completeness' | 'overlap' | 'conflict' | 'vacuity';
585
+
586
+ export type AnalysisTaskRow =
587
+ {
588
+ owner: string;
589
+ declaration: string;
590
+ stage: AnalysisStage;
591
+ status: 'ready';
592
+ tasks: AnalysisTask[];
593
+ } |
594
+ {
595
+ owner: string;
596
+ declaration: string;
597
+ stage: AnalysisStage;
598
+ status: 'unsupported';
599
+ reason: string;
600
+ };
601
+
602
+ export interface AnalysisTask {
603
+ fingerprint: string;
604
+ encoding: 'lawspec-smtlib-v2';
605
+ script: string;
606
+ inputs: string[];
607
+ }
608
+
609
+ export interface AnalysisCheck {
610
+ owner: string;
611
+ declaration: string;
612
+ stage: AnalysisStage;
613
+ fingerprint: string;
614
+ status: AnalysisCheckStatus;
615
+ reason: string;
616
+ check: AnalysisCheckStatus;
617
+ }
618
+
619
+ export type AnalysisCheckStatus =
620
+ 'proved' | 'refuted' | 'exempted' | 'incomplete';
621
+
537
622
  export interface GenerationRequest extends CheckRequest {
538
623
  target: Target;
539
624
  sourceDir?: string;
@@ -543,7 +628,7 @@ export interface GenerationRequest extends CheckRequest {
543
628
 
544
629
  export type ProofTask =
545
630
  {
546
- encoding: 'lawspec-smtlib-v1';
631
+ encoding: 'lawspec-smtlib-v1' | 'lawspec-smtlib-v2';
547
632
  owner: string;
548
633
  declaration: string;
549
634
  at: Location;
@@ -553,9 +638,14 @@ export type ProofTask =
553
638
  script: string;
554
639
  taskFingerprint: string;
555
640
  trust: string;
641
+ counterexample?: CounterexampleQuery;
642
+ counterexampleUnsupported?: string;
643
+ recursion?: Recursion;
644
+ alternative?: AlternativeTask;
645
+ induction?: InductionPlan;
556
646
  } |
557
647
  {
558
- encoding: 'lawspec-smtlib-v1';
648
+ encoding: 'lawspec-smtlib-v1' | 'lawspec-smtlib-v2';
559
649
  owner: string;
560
650
  declaration: string;
561
651
  at: Location;
@@ -565,6 +655,66 @@ export type ProofTask =
565
655
  reason: string;
566
656
  };
567
657
 
658
+ export interface AlternativeTask {
659
+ recursion: Recursion;
660
+ script: string;
661
+ taskFingerprint: string;
662
+ }
663
+
664
+ export type InductionPlan =
665
+ {
666
+ on: string;
667
+ asked: boolean;
668
+ using: string[];
669
+ status: 'ready';
670
+ cases: InductionCase[];
671
+ } |
672
+ {
673
+ on: string;
674
+ asked: boolean;
675
+ using: string[];
676
+ status: 'unsupported';
677
+ reason: string;
678
+ };
679
+
680
+ export interface InductionCase {
681
+ case: string;
682
+ script: string;
683
+ recursion: Recursion;
684
+ taskFingerprint: string;
685
+ inputs: string[];
686
+ alternative?: AlternativeTask;
687
+ }
688
+
689
+ export type Recursion =
690
+ {encoding: 'guarded-axioms'; fuel: number;} | {encoding: 'define-fun-rec';};
691
+
692
+ export type ProofCounterexample =
693
+ {
694
+ owner: string;
695
+ declaration: string;
696
+ taskFingerprint: string;
697
+ values: string;
698
+ };
699
+
700
+ export type CounterexampleQuery =
701
+ {
702
+ encoding: 'lawspec-smtlib-v2';
703
+ script: string;
704
+ fingerprint: string;
705
+ inputs: {name: string; binder: string}[];
706
+ };
707
+
708
+ export type CounterexampleCheck =
709
+ {
710
+ owner?: string;
711
+ declaration?: string;
712
+ taskFingerprint?: string;
713
+ status: 'refuted' | 'model-not-confirmed' | 'incomplete';
714
+ reason: string;
715
+ inputs?: {name: string; value: string}[];
716
+ };
717
+
568
718
  export type NativeSeed = number | string;
569
719
 
570
720
  export type NativeFreshness =
@@ -724,6 +874,12 @@ export interface Result {
724
874
  formattedSources?: Source[];
725
875
  tests?: NativeTestEntry[];
726
876
  proofTasks?: ProofTask[];
877
+ analysisTasks?: AnalysisTaskRow[];
878
+ analysisEvidence?: ObligationEvidence[];
879
+ analysisChecks?: AnalysisCheck[];
880
+ modelTasks?: ModelTaskRow[];
881
+ modelEvidence?: ObligationEvidence[];
882
+ counterexampleChecks?: CounterexampleCheck[];
727
883
  evidence?: ObligationEvidence[];
728
884
  attestation?: AttestationView;
729
885
  packages?: PackageView[];
@@ -25,6 +25,7 @@ export function recordNativeAttempts(run, tests, {keys,seed,ok,profile,output,al
25
25
  const model=(entry.obligations?.length??0)>0;
26
26
  const complete=matched.length>0&&matched.every(test=>test.status==='passed')&&(ok||model);
27
27
  const outcome=matched.some(test=>test.status==='failed')?'failed':
28
+ matched.some(test=>test.status==='incomplete')?'incomplete':
28
29
  entry.skip?'skipped':complete?(entry.knownFailing?'known-failing':'passed'):
29
30
  matched.length&&matched.every(test=>test.status==='skipped')?'skipped':'incomplete';
30
31
  return [entry.law,{key:keys.get(entry.law),planKey:entry.key,seed:nativeSeed(seed),at,outcome,
@@ -41,10 +42,16 @@ export function recordNativeAttempts(run, tests, {keys,seed,ok,profile,output,al
41
42
  }));
42
43
  }
43
44
 
45
+ // A law an attestation touches is keyed by how its dependencies were wired:
46
+ // endpoint, kind, and a stand-in's product, version and conformance. What the
47
+ // run observed (reached, history digests, completion) and the identities
48
+ // reported beside it are not inputs, so they change no key.
44
49
  export function attestedKeys(result) {
50
+ const wiring=d=>[d.dependency,d.endpoint,d.kind,
51
+ ...(d.standIn?[d.standIn.identity,d.standIn.version,d.standIn.conformance]:[])];
45
52
  return new Map((result.evidence??[]).filter(item=>item.against||item.plannedAgainst)
46
53
  .map(item=>[item.declaration,JSON.stringify([
47
- item.environment??item.plannedEnvironment,item.against??item.plannedAgainst])]));
54
+ item.environment??item.plannedEnvironment,(item.against??item.plannedAgainst).map(wiring)])]));
48
55
  }
49
56
 
50
57
  const subject = (entry,item) => obligationTargets(entry).some(target=>
@@ -60,17 +67,22 @@ export async function readNativeObservations({compiler,input,selected,roots,conf
60
67
  const record=JSON.parse(await readFile(file,'utf8').catch(error=>{
61
68
  if(error.code==='ENOENT')return '{}';throw error;
62
69
  }));
63
- return {target,root,attempts:record.attempts??{},runs:record.laws??{}};
70
+ return {target,root,attempts:record.attempts??{},runs:record.laws??{},attestations:record.attestations??{}};
64
71
  }));
65
72
  if(!records.some(record=>Object.keys(record.attempts).length))return [];
66
73
  const observations=[];
67
- for(const {target,root,attempts,runs}of records){
74
+ for(const {target,root,attempts,runs,attestations}of records){
68
75
  const plans=new Map(),contexts=new Map();
69
- async function plan(minify){
70
- if(!plans.has(minify))plans.set(minify,await compiler.planGeneration({...input,target:target.language,
76
+ // An attempt is keyed by the wiring of the attestation it ran under: the
77
+ // one named now, or else the one lawspec test stored for its run.
78
+ const wiredBy=attempt=>attestation??(attempt?.environment?attestations[attempt.environment]:undefined);
79
+ const slot=(minify,wired)=>`${minify}\0${wired?.run?.id??''}`;
80
+ async function plan(minify,wired=attestation){
81
+ const key=slot(minify,wired);
82
+ if(!plans.has(key))plans.set(key,await compiler.planGeneration({...input,target:target.language,
71
83
  sourceDir:target.sourceDir,testDir:target.testDir,nativeBindings:target.nativeBindings,minify,
72
- ...(attestation?{attestation}:{})}));
73
- return plans.get(minify);
84
+ ...(wired?{attestation:wired}:{})}));
85
+ return plans.get(key);
74
86
  }
75
87
  const modes=[...new Set(Object.values(attempts).map(attempt=>attempt.profile?.minify)
76
88
  .filter(mode=>typeof mode==='boolean'))];
@@ -83,9 +95,10 @@ export async function readNativeObservations({compiler,input,selected,roots,conf
83
95
  continue;
84
96
  }
85
97
  const expected=new Map(base.tests.map(entry=>[entry.law,entry]));
86
- async function context(minify){
87
- if(contexts.has(minify))return contexts.get(minify);
88
- const generated=await plan(minify);
98
+ async function context(minify,wired){
99
+ const key=slot(minify,wired);
100
+ if(contexts.has(key))return contexts.get(key);
101
+ const generated=await plan(minify,wired);
89
102
  let result;
90
103
  if(generated.diagnostics.length)result={reason:'Native generation is unavailable for the recorded layout'};
91
104
  else {
@@ -103,7 +116,7 @@ export async function readNativeObservations({compiler,input,selected,roots,conf
103
116
  }
104
117
  }
105
118
  }
106
- contexts.set(minify,result);return result;
119
+ contexts.set(key,result);return result;
107
120
  }
108
121
  for(const [id,baseline]of expected){
109
122
  const attempt=attempts[id];
@@ -115,7 +128,7 @@ export async function readNativeObservations({compiler,input,selected,roots,conf
115
128
  typeof profile.minify!=='boolean'){
116
129
  observations.push({...row,freshness:'stale',reason:'Compiler, target or machine profile differs'});continue;
117
130
  }
118
- const current=await context(profile.minify);
131
+ const current=await context(profile.minify,wiredBy(attempt));
119
132
  if(current.reason){observations.push({...row,freshness:current.stale?'stale':'unavailable',reason:current.reason});continue;}
120
133
  const entry=current.generated.tests.find(entry=>entry.law===id);
121
134
  if(!entry||attempt.key!==current.keys.get(id)||attempt.planKey!==entry.key||
@@ -46,7 +46,7 @@ archive preserves distinct present and absent payments.
46
46
 
47
47
  The specification uses the canonical language profile. The version 2 project
48
48
  configuration selects its verification layers explicitly. Most targets bind
49
- application-owned domain types; C# and Clojure use the generated model data
49
+ application-owned domain types; C#, Clojure and Prolog use the generated model data
50
50
  and bind the application's functions and generators.
51
51
 
52
52
  ## Run
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "lawspec",
3
- "version": "0.26.0",
3
+ "version": "0.28.0",
4
4
  "description": "State the law once. Check it everywhere.",
5
5
  "license": "MIT",
6
6
  "repository": {
@@ -37,6 +37,7 @@
37
37
  "CHANGELOG.md",
38
38
  "LICENSE",
39
39
  "UNICODE-LICENSE.txt",
40
+ "NORMALIZATION-LICENSES.txt",
40
41
  "starter.lawspec",
41
42
  "starter-rc1.lawspec",
42
43
  "examples"
package/proof.d.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  // Generated from templates/npm/proof.d.ts by lawspec-dev generate. Do not edit.
2
- import type {CheckRequest,Compiler,Location,Result} from './index.d.ts';
2
+ import type {CheckRequest,Compiler,Location,Recursion,Result} from './index.d.ts';
3
3
 
4
4
  export interface Z3Options {
5
5
  binary?: string;
@@ -9,19 +9,10 @@ export interface Z3Options {
9
9
  seed?: number;
10
10
  maxOutputBytes?: number;
11
11
  }
12
- export interface SolverEvidence {
13
- owner: string;
14
- declaration: string;
15
- at: Location;
16
- encoding: 'lawspec-smtlib-v1';
17
- machineBits: 32 | 64;
18
- programFingerprint: string;
19
- taskFingerprint?: string;
20
- status: 'proved' | 'incomplete' | 'unsupported';
12
+ /** How a solver run went: shared by law and law-set evidence. */
13
+ interface SolverRun {
21
14
  outcome: 'unsat' | 'sat' | 'unknown' | 'timeout' | 'resource-limit' | 'out-of-memory' | 'unavailable' | 'failed' | 'unsupported';
22
15
  reason: string;
23
- model?: string;
24
- modelValidated?: false;
25
16
  stdout?: string;
26
17
  stderr?: string;
27
18
  elapsedMs?: number;
@@ -31,5 +22,59 @@ export interface SolverEvidence {
31
22
  prover?: {name:'z3'; version:string; binary:string; binaryFingerprint:string; fingerprint:string; arguments:string[]};
32
23
  configuration?: Required<Z3Options>;
33
24
  }
25
+ /** A law's proof task, run by Z3. */
26
+ export interface LawSolverEvidence extends SolverRun {
27
+ kind?: undefined;
28
+ owner: string;
29
+ declaration: string;
30
+ at: Location;
31
+ encoding: 'lawspec-smtlib-v1' | 'lawspec-smtlib-v2';
32
+ machineBits: 32 | 64;
33
+ programFingerprint: string;
34
+ taskFingerprint?: string;
35
+ status: 'proved' | 'refuted' | 'incomplete' | 'unsupported';
36
+ model?: string;
37
+ modelValidated?: boolean;
38
+ counterexample?: {inputs:{name:string;value:string}[]; values:string; fingerprint:string; runFingerprint:string;
39
+ check:'refuted'|'model-not-confirmed'|'incomplete'};
40
+ /** For a law over recursive definitions: the encoding of the run reported,
41
+ and each encoding tried, in order. */
42
+ recursion?: Recursion;
43
+ attempts?: {recursion:Recursion; taskFingerprint:string; outcome:SolverRun['outcome']; runFingerprint?:string; elapsedMs?:number}[];
44
+ /** Induction on an input: the cited laws, and each case's receipt. */
45
+ induction?: {on:string; using:string[]; asked?:boolean; cases:{case:string; outcome?:SolverRun['outcome']; recursion?:Recursion;
46
+ taskFingerprint?:string; runFingerprint?:string; values?:string; reason?:string;
47
+ attempts?:{recursion:Recursion; taskFingerprint:string; outcome:SolverRun['outcome']; runFingerprint?:string; elapsedMs?:number}[]}[]};
48
+ }
49
+ /** A law-set check's task (completeness, overlap, conflict or vacuity).
50
+ status is the task's own result; check is its row's. */
51
+ export interface AnalysisSolverEvidence extends SolverRun {
52
+ kind: 'analysis';
53
+ owner: string;
54
+ declaration: string;
55
+ stage: 'completeness' | 'overlap' | 'conflict' | 'vacuity';
56
+ encoding: 'lawspec-smtlib-v2';
57
+ taskFingerprint?: string;
58
+ status: 'proved' | 'refuted' | 'exempted' | 'incomplete' | 'unsupported';
59
+ check?: 'proved' | 'refuted' | 'exempted' | 'incomplete';
60
+ model?: undefined;
61
+ modelValidated?: undefined;
62
+ counterexample?: undefined;
63
+ }
64
+ /** A model law's task: induction, Spacer, an invariant re-check or the
65
+ bounded run search; the law's own row says what they settled. */
66
+ export interface ModelSolverEvidence extends SolverRun {
67
+ kind: 'model';
68
+ owner: string;
69
+ declaration: string;
70
+ task: string;
71
+ taskFingerprint: string;
72
+ encoding: 'lawspec-smtlib-v2';
73
+ status: 'proved' | 'incomplete';
74
+ model?: undefined;
75
+ modelValidated?: undefined;
76
+ counterexample?: undefined;
77
+ }
78
+ export type SolverEvidence = LawSolverEvidence | AnalysisSolverEvidence | ModelSolverEvidence;
34
79
  export function proofTaskFingerprint(task: {encoding:string;programFingerprint:string;machineBits:number;owner:string;declaration:string;script:string}):string;
35
80
  export function proveWithZ3(compiler:Compiler,request:CheckRequest,options?:Z3Options):Promise<Result & {solverEvidence:SolverEvidence[]}>;