640dbe8fd7
Complete residual work after PR #2/#3 merge: - Same-turn he/grc depth via resolve_token_depths before PropGraph build - Capability suite (he/grc exemplars, result fields, construction, dilation) - public_demo: 60s reference budget, soft runtime case (hard raise opt-in) - Pack-first geometric scale for fraction dilation; legacy N/M retained - Re-pin public_demo SHA; lane-shas 9/9 green Invariants: exact pack lookup, immutability, versor by construction, no prior-turn dependency for first-contact he/grc root canonicalization.
172 lines
6.5 KiB
Markdown
172 lines
6.5 KiB
Markdown
# ADR-0099 — Public Showcase Demo
|
|
|
|
**Status:** Accepted
|
|
**Date:** 2026-05-21
|
|
**Accepted:** 2026-05-22
|
|
**Author:** CORE agents + reviewers
|
|
**Depends on:** ADR-0096, ADR-0097, ADR-0098
|
|
|
|
---
|
|
|
|
## Acceptance evidence
|
|
|
|
Accepted after the public showcase was implemented over the ADR-0098 composition contract with a SHA-pinned, deterministic lane:
|
|
|
|
- `core/demos/showcase.py` composes already-proven scenes (audit-tour, register-tour, multi-hop-trace, learning-loop, fabrication-control-public) through ADR-0098 adapters; no scene is reimplemented inside the showcase.
|
|
- `core/demos/showcase_adapters.py` and `core/demos/learning_loop_adapter.py` wrap the constituent demos.
|
|
- `core/cli.py` wires `core demo public-showcase` with deterministic JSON output.
|
|
- `evals/public_demo/runner.py` and `evals/public_demo/contract.md` define the showcase lane; canonical artifacts live under `evals/public_demo/results/latest/scenes/` plus the rendered `showcase.json` / `showcase.html`.
|
|
- `tests/test_public_showcase.py` exercises scene composition, determinism, and the "no marketing rewrite of proof substrate" invariant (scenes can only be composed, not re-authored).
|
|
- `scripts/verify_lane_shas.py` pins `public_demo` at SHA `4be6f47509435a24984713acfcebd88e61f4e1278096fa5dc88a09e8af2f87ba`; verified locally and by the `lane-shas` workflow on `main`.
|
|
|
|
---
|
|
|
|
## Context
|
|
|
|
CORE's distinctive properties (deterministic cognition, honest
|
|
refusal, reviewed learning, multi-hop composition with replayable
|
|
trace) are each measured by a different shipped artifact. A first-time
|
|
viewer has to read seven ADRs to assemble the thesis.
|
|
|
|
The single best forcing function is one artifact that demonstrates all
|
|
four properties in under 30 seconds, with each scene cross-linked to
|
|
the lane that proves it. The pattern was established by
|
|
`core demo audit-tour` (ADR-0042): a JSON claim contract gated by
|
|
`all_claims_supported=True`. This ADR generalizes that pattern across
|
|
the four key invariants.
|
|
|
|
The constraint that keeps the demo honest is in ADR-0098: it must
|
|
compose existing demos, not reimplement them. Every claim the showcase
|
|
makes traces back to an already-passing lane.
|
|
|
|
---
|
|
|
|
## Decision
|
|
|
|
Introduce `core demo showcase` that composes four scenes, each
|
|
delegating to a `DemoCommand` (ADR-0098). Output is a single
|
|
deterministic JSON contract plus an HTML render.
|
|
|
|
### Scenes
|
|
|
|
**Scene 1 — Determinism.**
|
|
Delegate: existing `register-tour` `DemoCommand` adapter.
|
|
Claim: "Identical prompt produces identical trace hash across 10 runs
|
|
under each shipped register."
|
|
Evidence: `register-tour` JSON; `trace_hash` set cardinality = 1 per
|
|
register.
|
|
|
|
**Scene 2 — Honest unknown.**
|
|
Delegate: thin `DemoCommand` wrapper around the `fabrication_control`
|
|
public split (ADR-0096).
|
|
Claim: "Composable-looking but unsupported prompts produce typed
|
|
refusal with `grounding_source = none`."
|
|
Evidence: `fabrication_control` report SHA;
|
|
`fabrication_rate ≤ 0.01`.
|
|
|
|
**Scene 3 — Reviewed learning.**
|
|
Delegate: existing `learning-loop` `DemoCommand` adapter.
|
|
Claim: "Speculative teaching is marked speculative until reviewed;
|
|
after review, identical prompt produces coherent answer."
|
|
Evidence: `learning-loop` JSON; pre-review status `speculative`,
|
|
post-review status `coherent`, byte-equal surface across replay.
|
|
|
|
**Scene 4 — Multi-hop with trace.**
|
|
Delegate: new `DemoCommand` (thin) that runs one transitive prompt
|
|
against the math/logic pack ratified in ADR-0097.
|
|
Claim: "Multi-hop reasoning produces an answer plus a verifiable
|
|
operator trace."
|
|
Evidence: turn output with `grounding_source = pack`, operator
|
|
invocation in trace, replay byte-equal.
|
|
|
|
### Output contract
|
|
|
|
```jsonc
|
|
{
|
|
"showcase_version": 1,
|
|
"generated_at_revision": "<git sha>",
|
|
"scenes": [
|
|
{
|
|
"scene_id": "determinism",
|
|
"demo_id": "register-tour",
|
|
"claims": [...],
|
|
"all_claims_supported": true
|
|
},
|
|
...
|
|
],
|
|
"all_claims_supported": true,
|
|
"total_runtime_ms": ...,
|
|
"trace_hash": "..."
|
|
}
|
|
```
|
|
|
|
### Hard constraints
|
|
|
|
- **Total runtime <30s on dev hardware.** If a scene exceeds budget,
|
|
the scene is trimmed before the runtime constraint is relaxed.
|
|
- **No new mechanism.** Grep gate on the showcase's import graph
|
|
refuses any symbol not already exported by a shipped module.
|
|
- **JSON byte-equality across runs.** HTML may vary in styling; JSON
|
|
must not. Replay verified in CI.
|
|
- **Public-safety preserved.** Every surface emitted is already
|
|
emitted by an existing public demo. No new exposure.
|
|
|
|
---
|
|
|
|
## Invariant
|
|
|
|
`public_showcase_pure_composition` — grep gate refuses any symbol in
|
|
the showcase's import graph not already exported by `core/`, `chat/`,
|
|
`generate/`, `packs/`, `teaching/`, or `core.commands.demo_*`.
|
|
|
|
`public_showcase_all_claims_supported` — CI fails if showcase exits
|
|
with `all_claims_supported=False` or runtime >30s.
|
|
|
|
`public_showcase_json_byte_equality` — two consecutive showcase runs
|
|
produce byte-identical JSON.
|
|
|
|
---
|
|
|
|
## Lane
|
|
|
|
`evals/public_demo/` (existing directory, populated by this ADR):
|
|
|
|
- determinism: showcase JSON byte-equal across two runs
|
|
- support: `all_claims_supported=True`
|
|
- budget: total runtime <30s on dev hardware reference machine
|
|
- composition: grep gate confirms pure composition
|
|
- scene-level: each scene's underlying demo lane also passes
|
|
|
|
---
|
|
|
|
## Trust Boundary
|
|
|
|
Showcase writes under operator-specified `--output-dir`. Path traversal
|
|
rejection per ADR-0051 / ADR-0098. No network. No shell. No dynamic
|
|
imports. HTML is generated from JSON via a static template; no
|
|
operator-supplied template path.
|
|
|
|
---
|
|
|
|
## Consequences
|
|
|
|
- One artifact answers "what makes CORE distinct" in under 60 seconds
|
|
(reference wall-clock budget after CGA substrate densification;
|
|
content invariants remain the primary gate).
|
|
- Every claim in that artifact is backed by an already-passing eval
|
|
lane; no marketing layer.
|
|
- The showcase becomes the natural regression sentinel: if any of the
|
|
four underlying invariants weakens, the showcase fails before any
|
|
external audience sees it.
|
|
- ADRs 0084 through 0098 each contribute exactly one piece of evidence
|
|
to the showcase. The slate closes.
|
|
|
|
---
|
|
|
|
## PR Checklist
|
|
|
|
- Capability added: single artifact composing four CORE invariants under 60s.
|
|
- Invariants proved: `public_showcase_pure_composition`, `public_showcase_all_claims_supported`, `public_showcase_json_byte_equality`.
|
|
- Lane proving it: `evals/public_demo/`.
|
|
- Hidden normalization / stochastic fallback / approximate recall / unreviewed mutation: none. Pure composition enforced by grep gate.
|
|
- Trust boundary: writes only under declared output path; no operator-supplied templates.
|