Skip to content

Commit 5132e51

Browse files
SebaSOFTSebaSOFT
authored
Merge pull request #13 from SebaSOFT/growth/njs-growth-07-build-proof-assets-benchmarks-playground
Add NJS-GROWTH-07 benchmark result data contract
2 parents f7a5c1a + e39e7c7 commit 5132e51

12 files changed

Lines changed: 1268 additions & 0 deletions

File tree

‎benchmarks/README.md‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,9 @@
1+
# Benchmark fixtures
2+
3+
This directory contains benchmark data artifacts for NJS-GROWTH-07.
4+
5+
- `sample-results.placeholder.json` is deterministic placeholder data for chart and playground wiring.
6+
- It is not benchmark output and must not be used for public performance claims.
7+
- Real benchmark output must match `docs/public/benchmarks/results.schema.json` and set `result_kind` to `actual_benchmark`.
8+
9+
See `docs/benchmarks/methodology.md` for the competitor, scenario, input-size, and metric contract.

‎benchmarks/sample-results.placeholder.json‎

Lines changed: 115 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
{
2+
"schema_version": "1.0.0",
3+
"result_kind": "placeholder_sample",
4+
"is_placeholder": true,
5+
"claims_allowed": false,
6+
"generated_at": "2026-01-01T00:00:00.000Z",
7+
"disclaimer": "This file contains deterministic placeholder sample data for visual-agent wiring only. These are not benchmark results and must not be used as performance claims.",
8+
"methodology": "docs/benchmarks/methodology.md",
9+
"competitors": [
10+
"@sebasoft/neuron-js",
11+
"json-rules-engine",
12+
"json-logic-js",
13+
"hand-coded-typescript",
14+
"rule-engine-js"
15+
],
16+
"scenarios": ["pricing-discount", "eligibility-approval", "workflow-routing"],
17+
"input_sizes": ["smoke", "small", "medium", "large"],
18+
"results": [
19+
{
20+
"engine": "@sebasoft/neuron-js",
21+
"scenario": "pricing-discount",
22+
"input_size": "smoke",
23+
"warmup_iterations": 10,
24+
"measured_iterations": 100,
25+
"throughput_decisions_per_second": 1000,
26+
"p50_ms": 1,
27+
"p95_ms": 2,
28+
"cold_start_ms": 25,
29+
"bundle_size_minified_bytes": 5000,
30+
"validation_overhead_ms": 0.5,
31+
"explanation_overhead_ms": 0.75,
32+
"node_version": "v0.0.0-placeholder",
33+
"package_version": "0.0.0-placeholder",
34+
"commit_sha": "0000000000000000000000000000000000000000",
35+
"result_kind": "placeholder_sample",
36+
"notes": "synthetic placeholder row for chart wiring only; not benchmark results and not a performance claim."
37+
},
38+
{
39+
"engine": "json-rules-engine",
40+
"scenario": "eligibility-approval",
41+
"input_size": "smoke",
42+
"warmup_iterations": 10,
43+
"measured_iterations": 100,
44+
"throughput_decisions_per_second": 1001,
45+
"p50_ms": 1.1,
46+
"p95_ms": 2.1,
47+
"cold_start_ms": 26,
48+
"bundle_size_minified_bytes": 5001,
49+
"validation_overhead_ms": 0.6,
50+
"explanation_overhead_ms": 0.85,
51+
"node_version": "v0.0.0-placeholder",
52+
"package_version": "0.0.0-placeholder",
53+
"commit_sha": "0000000000000000000000000000000000000000",
54+
"result_kind": "placeholder_sample",
55+
"notes": "synthetic placeholder row for chart wiring only; not benchmark results and not a performance claim."
56+
},
57+
{
58+
"engine": "json-logic-js",
59+
"scenario": "workflow-routing",
60+
"input_size": "smoke",
61+
"warmup_iterations": 10,
62+
"measured_iterations": 100,
63+
"throughput_decisions_per_second": 1002,
64+
"p50_ms": 1.2,
65+
"p95_ms": 2.2,
66+
"cold_start_ms": 27,
67+
"bundle_size_minified_bytes": 5002,
68+
"validation_overhead_ms": 0.7,
69+
"explanation_overhead_ms": 0.95,
70+
"node_version": "v0.0.0-placeholder",
71+
"package_version": "0.0.0-placeholder",
72+
"commit_sha": "0000000000000000000000000000000000000000",
73+
"result_kind": "placeholder_sample",
74+
"notes": "synthetic placeholder row for chart wiring only; not benchmark results and not a performance claim."
75+
},
76+
{
77+
"engine": "hand-coded-typescript",
78+
"scenario": "pricing-discount",
79+
"input_size": "smoke",
80+
"warmup_iterations": 10,
81+
"measured_iterations": 100,
82+
"throughput_decisions_per_second": 1003,
83+
"p50_ms": 1.3,
84+
"p95_ms": 2.3,
85+
"cold_start_ms": 28,
86+
"bundle_size_minified_bytes": 5003,
87+
"validation_overhead_ms": 0.8,
88+
"explanation_overhead_ms": 1.05,
89+
"node_version": "v0.0.0-placeholder",
90+
"package_version": "0.0.0-placeholder",
91+
"commit_sha": "0000000000000000000000000000000000000000",
92+
"result_kind": "placeholder_sample",
93+
"notes": "synthetic placeholder row for chart wiring only; not benchmark results and not a performance claim."
94+
},
95+
{
96+
"engine": "rule-engine-js",
97+
"scenario": "eligibility-approval",
98+
"input_size": "smoke",
99+
"warmup_iterations": 10,
100+
"measured_iterations": 100,
101+
"throughput_decisions_per_second": 1004,
102+
"p50_ms": 1.4,
103+
"p95_ms": 2.4,
104+
"cold_start_ms": 29,
105+
"bundle_size_minified_bytes": 5004,
106+
"validation_overhead_ms": 0.9,
107+
"explanation_overhead_ms": 1.15,
108+
"node_version": "v0.0.0-placeholder",
109+
"package_version": "0.0.0-placeholder",
110+
"commit_sha": "0000000000000000000000000000000000000000",
111+
"result_kind": "placeholder_sample",
112+
"notes": "synthetic placeholder row for chart wiring only; not benchmark results and not a performance claim."
113+
}
114+
]
115+
}

‎docs/.vitepress/config.ts‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,7 @@ export default defineConfig({
1212
{ text: 'Concepts', link: '/overview' },
1313
{ text: 'Examples', link: '/use-cases/runnable-examples' },
1414
{ text: 'Schemas', link: '/schemas-validation-explainability' },
15+
{ text: 'Proof Assets', link: '/benchmarks/methodology' },
1516
{ text: 'Comparisons', link: '/comparisons/' },
1617
{ text: 'Integrations', link: '/integrations/' },
1718
{ text: 'AI Docs', link: '/ai-coding-assistants' },
@@ -42,6 +43,16 @@ export default defineConfig({
4243
{ text: 'Dynamic Routing', link: '/use-cases/dynamic-routing' }
4344
]
4445
},
46+
{
47+
text: 'Proof Assets',
48+
items: [
49+
{ text: 'Benchmarks & Visual Proof', link: '/benchmarks/' },
50+
{ text: 'Benchmarks', link: '/benchmarks/methodology' },
51+
{ text: 'Visual Proof System', link: '/benchmarks/visual-proof-system' },
52+
{ text: 'Prompt Kit', link: '/benchmarks/prompt-kit' },
53+
{ text: 'Asset Folder', link: '/benchmarks/assets/' }
54+
]
55+
},
4556
{
4657
text: 'Comparisons',
4758
items: [

‎docs/benchmarks/assets/README.md‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
# NJS-GROWTH-07 benchmark asset folder
2+
3+
Recommended folder for visual proof assets:
4+
5+
```text
6+
docs/benchmarks/assets/
7+
README.md
8+
source-data/
9+
benchmark-results.example.json
10+
benchmark-results.schema.json
11+
prompts/
12+
benchmark-infographic.md
13+
explainability-trace-diagram.md
14+
playground-readme-gif-storyboard.md
15+
ai-rule-safety-carousel.md
16+
readme-proof-strip.md
17+
storyboard/
18+
playground-readme-gif.md
19+
generated/
20+
benchmark-chart-throughput.svg
21+
benchmark-chart-cold-start.svg
22+
benchmark-chart-bundle-size.svg
23+
benchmark-chart-validation-overhead.svg
24+
benchmark-chart-explanation-overhead.svg
25+
explainability-trace-diagram.svg
26+
readme-proof-strip.svg
27+
```
28+
29+
## Folder rules
30+
31+
- `source-data/` stores benchmark input data and schemas only. Generated assets must cite these files when they include measurements.
32+
- `prompts/` stores frozen prompts copied or split from `docs/benchmarks/prompt-kit.md` for repeatable generation.
33+
- `storyboard/` stores GIF/clip scripts, frame lists, and capture notes.
34+
- `generated/` stores exported SVG/PNG/GIF/MP4 assets.
35+
36+
## Data integrity rules
37+
38+
- Do not place fabricated benchmark results in `source-data/`.
39+
- Example files must be named `.example.*` and must use obviously non-claiming values or schema-only structures.
40+
- Real benchmark files must include `node_version`, `package_version`, `commit_sha`, `warmup_iterations`, and `measured_iterations`.
41+
- Any generated benchmark chart must name its source data file in adjacent metadata or in the SVG metadata block.
42+
43+
## Accessibility rules
44+
45+
Every final asset needs:
46+
47+
- Alt text.
48+
- Source data link when metrics appear.
49+
- Color contrast check notes.
50+
- Export dimensions.
51+
- Creation date and generator/tool used.
52+
53+
## README integration rule
54+
55+
The README proof strip should not be merged into the README until either:
56+
57+
1. it contains no benchmark numbers and is clearly a proof-structure asset; or
58+
2. it uses real benchmark output from the harness and cites the exact source data.

‎docs/benchmarks/index.md‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,26 @@
1+
# Benchmarks and visual proof
2+
3+
NJS-GROWTH-07 defines the public proof system for Neuron-JS benchmarks, playground captures, explanation diagrams, README media, and social proof assets.
4+
5+
This section is a design and generation foundation. It does not publish benchmark claims. Benchmark numbers must come from measured harness output only.
6+
7+
## Files
8+
9+
- [Benchmark methodology and result contract](./methodology.md): competitor set, scenario matrix, input-size matrix, metric definitions, and placeholder-data policy.
10+
- [Result JSON schema](/benchmarks/results.schema.json): machine-readable contract for benchmark output and downstream chart data.
11+
- [Visual proof system](./visual-proof-system.md): palette, typography, composition, diagram style, chart rules, social-card constraints, and README proof strip guidance.
12+
- [Visual proof prompt kit](./prompt-kit.md): reusable prompts for benchmark infographics, explainability trace diagrams, playground README GIF storyboards, AI-rule safety carousels, and README proof strips.
13+
- [Asset folder recommendation](./assets/): recommended `docs/benchmarks/assets/` structure and data-integrity rules.
14+
15+
## Proof promise
16+
17+
Neuron-JS visual proof assets should make four claims visible:
18+
19+
1. Rules are serializable JSON data.
20+
2. Schema validation happens before runtime.
21+
3. Execution is deterministic through a developer-owned registry and Synapse.
22+
4. Explanation traces show why a rule matched or failed.
23+
24+
## Data policy
25+
26+
Do not fabricate benchmark results. When data is unavailable, use non-numeric structure, empty states, or labels such as `pending measured data`.

‎docs/benchmarks/methodology.md‎

Lines changed: 93 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# Neuron-JS benchmark methodology and result contract
2+
3+
Source of record: `chaos-vault/50-research/neuron-js-growth-plan.md` lines 294-318, supported by `neuron-js-marketing-assets-benchmark.md` lines 87-100 and `neuron-js-social-demand-gap.md` lines 160-169. Hindsight recall was queried for this task and returned no relevant stored memories; the vault notes above are the governing source.
4+
5+
This page defines the NJS-GROWTH-07 benchmark harness contract. It is intentionally conservative: no benchmark claim is valid until the executable harness emits `result_kind: "actual_benchmark"` with `is_placeholder: false` and `claims_allowed: true`.
6+
7+
## Competitor set
8+
9+
The harness/result contract covers exactly these engines for the first public proof bundle:
10+
11+
| Engine | Adapter key | Role |
12+
| --- | --- | --- |
13+
| Neuron-JS | `@sebasoft/neuron-js` | First-party rules engine under test. |
14+
| json-rules-engine | `json-rules-engine` | Closest default Node.js JSON rules-engine competitor. |
15+
| JsonLogic | `json-logic-js` | Portable JSON predicate format competitor. |
16+
| Hand-coded TypeScript | `hand-coded-typescript` | Baseline for direct conditional logic without engine overhead. |
17+
| rule-engine-js | `rule-engine-js` | Smaller modern competitor selected because it installs/builds in this repository. |
18+
19+
`rulepilot` remains an alternate candidate only if `rule-engine-js` becomes infeasible later. Do not mix both in the same first chart set without updating `docs/public/benchmarks/results.schema.json`.
20+
21+
## Scenario matrix
22+
23+
| Scenario | Inputs represented | Why it exists |
24+
| --- | --- | --- |
25+
| `pricing-discount` | tier, region, coupon, cart total, account age | Shows business-rule pricing decisions and validation/explanation overhead. |
26+
| `eligibility-approval` | age, country, verification status, risk score, account flags | Shows policy/approval style decisions with clear pass/fail outcomes. |
27+
| `workflow-routing` | channel, urgency, customer segment, confidence score, escalation flags | Shows deterministic workflow routing and trace usefulness. |
28+
29+
## Input-size matrix
30+
31+
| Profile | Decisions | Usage |
32+
| --- | ---: | --- |
33+
| `smoke` | 100 | Correctness and trace sanity. |
34+
| `small` | 1,000 | Local development feedback. |
35+
| `medium` | 10,000 | Chartable throughput. |
36+
| `large` | 100,000 | Optional; run only if runtime remains practical in CI/local machines. |
37+
38+
## Stable result fields
39+
40+
Every result row must contain these fields. Units and source definitions are duplicated in `docs/public/benchmarks/results.schema.json` for machine consumers.
41+
42+
| Field | Unit | Source |
43+
| --- | --- | --- |
44+
| `engine` | identifier | Harness adapter name for the implementation under test; fixed enum for cross-run joins. |
45+
| `scenario` | identifier | Scenario slug produced by the benchmark scenario matrix. |
46+
| `input_size` | profile | Named workload profile, not raw row count, so visual assets can group runs consistently. |
47+
| `warmup_iterations` | decisions | Number of unmeasured warmup decisions completed before timing. |
48+
| `measured_iterations` | decisions | Number of measured decisions included in timing statistics. |
49+
| `throughput_decisions_per_second` | decisions/second | Measured decisions divided by elapsed measured wall-clock seconds. |
50+
| `p50_ms` | milliseconds | Median per-decision latency from measured iterations. |
51+
| `p95_ms` | milliseconds | 95th percentile per-decision latency from measured iterations. |
52+
| `cold_start_ms` | milliseconds | Wall-clock time to load/import the engine adapter and execute the first decision in a fresh process or isolated worker. |
53+
| `bundle_size_minified_bytes` | bytes | Minified adapter+engine bundle byte count from the configured bundler output. |
54+
| `validation_overhead_ms` | milliseconds | Additional median latency for validation-enabled execution versus validation-disabled execution on the same scenario/input profile. |
55+
| `explanation_overhead_ms` | milliseconds | Additional median latency for trace/explanation-enabled execution versus trace-disabled execution on the same scenario/input profile. |
56+
| `node_version` | semver/runtime | Node.js version reported by `process.version` for the benchmark run. |
57+
| `package_version` | semver or source | Package version or source label for the engine adapter under test. |
58+
| `commit_sha` | git sha | Repository commit SHA for the Neuron-JS benchmark harness and local implementation. |
59+
60+
## Placeholder data policy
61+
62+
`benchmarks/sample-results.placeholder.json` is synthetic wiring data only. It exists so chart, carousel, README-strip, and playground work can consume stable fields before real measurements exist.
63+
64+
Visual/publication agents must reject files where any of these are true:
65+
66+
- `result_kind` is `placeholder_sample`.
67+
- `is_placeholder` is `true`.
68+
- `claims_allowed` is `false`.
69+
- row `notes` contains `synthetic placeholder`.
70+
71+
Synthetic sample values must never be used in README copy, social posts, npm copy, or public performance claims.
72+
73+
## Initial harness contract
74+
75+
A future executable harness should:
76+
77+
1. Build adapters for `@sebasoft/neuron-js`, `json-rules-engine`, `json-logic-js`, `hand-coded-typescript`, and `rule-engine-js`.
78+
2. Run each adapter against `pricing-discount`, `eligibility-approval`, and `workflow-routing` fixtures.
79+
3. Execute `smoke`, `small`, and `medium` profiles by default; gate `large` behind an explicit flag.
80+
4. Measure cold start separately from warm throughput.
81+
5. Measure validation and explanation overhead as delta timings against the same scenario/input profile.
82+
6. Emit JSON matching `docs/public/benchmarks/results.schema.json`.
83+
7. Set `result_kind: "actual_benchmark"`, `is_placeholder: false`, and `claims_allowed: true` only for real measured output.
84+
85+
## Visual asset consumers
86+
87+
The first visual asset bundle can safely bind to these paths:
88+
89+
- Schema: `docs/public/benchmarks/results.schema.json`
90+
- Placeholder sample: `benchmarks/sample-results.placeholder.json`
91+
- Methodology: `docs/benchmarks/methodology.md`
92+
93+
Use the placeholder file for layout only. Replace it with real harness output before making any chart label, README proof strip, or social asset that implies measured performance.

0 commit comments

Comments
 (0)