Decispec separates semantic compilation from authoritative evaluation.
flowchart TD
B["Browser"] -->|"TXT/PDF"| X["Server document extraction"]
X --> S["Stable source-segment registry"]
B -->|"Explicit Test decision"| A["Server analysis route"]
S --> P["Optional GPT semantic proposal"]
P --> Z["Strict Structured Output + Zod"]
Z --> V["Segment, provenance, graph, unit, and calculation validation"]
V --> E["Deterministic TypeScript engine"]
E --> T["Decision Test Suite"]
E --> G["Proof DAG"]
E --> R["Report + evaluated JSON export"]
The live workflow enters through server extraction and the provider boundary, then must pass every local validation stage before deterministic execution.
The decision graph contains typed claim nodes—fact, policy, calculation, comparison, assumption, and recommendation—and typed dependency edges. Calculation specifications reference operands by node ID. Local dependency materialization converts those references into calculation-input edges and converts selector policy references into typed policy edges.
Before evaluation, the engine:
Evaluation proceeds in topological order. Source-bound facts become supported, executable nodes become calculated, explicit assumptions remain assumed, and invalid nodes become broken. A broken dependency propagates to downstream claims, totals, and the recommendation.
Documents are segmented deterministically into paragraphs, sentences, clauses, and numeric-evidence atoms. Segment IDs combine document identity, segment type, ordinal, and a stable content hash. The provider references IDs only; it does not author quotations, offsets, or page labels.
Local materialization restores each binding from the source registry. Multi-segment textual bindings must be adjacent, ordered, and from one document. Numeric facts must reference a numeric-evidence atom. Source text remains authoritative even if a provider proposes a conflicting value or unit.
TXT files are decoded as UTF-8. Text-based PDFs are extracted page by page with unpdf; page labels are preserved in normalized content. Limits are eight files, 10 MB per file, and 120,000 extracted characters per document. Empty, encrypted, malformed, duplicate, image-only, and oversized inputs fail safely. OCR is not implemented.
Decispec accepts only enumerated structured operations, including addition, subtraction, multiplication, division, percentage adjustment, explicit duration conversion, the bundled lower-total comparison, and the live provider’s typed candidate selector. Arbitrary expressions, generated code, eval, and provider tools are forbidden.
Each numeric node declares a canonical unit. The engine models currency, devices, and time dimensions, including month/year time bases. It validates additive compatibility and derives multiplicative dimensions from operands. A monthly recurring rate multiplied by a year operand fails because time bases differ unless a typed conversion is explicit.
Source-bound numbers are recovered locally. Currency formatting and commas normalize conservatively. Percentages allow only explicit equivalent forms such as source 7% with percent value 7, or ratio value 0.07. A direct value of 1.07 is not accepted as source evidence; it must result from a structured percentage adjustment.
The live provider represents a recommendation as select-candidate with:
The provider sets the recommendation value to null. Local code evaluates eligibility, compares executable totals, resolves or rejects ties, and produces the authoritative winner. An asserted vendor string without executable support is rejected.
The engine evaluates a node only after its dependencies. A unit mismatch may still retain the arithmetic value for inspection, but the node status becomes broken. Any downstream node whose conclusion depends on that broken node also becomes broken. A failing path is presented from the source-bound rate through the calculation and candidate total to the recommendation.
Vendor A monthly support rate
→ Vendor A support cost
→ Vendor A three-year total
→ Recommendation
The focused graph renders those four nodes while temporarily hiding unrelated claims. The complete graph remains available.
A correction identifies a target calculation and a replacement structured operation. Application is atomic:
When a correction replaces an incompatible duration with a source-bound monthly duration, evidence remains unchanged and the graph recomputes all dependent values and the recommendation.
The semantic diff compares evaluated nodes by value and status. The UI presents only material changes. Undo restores the original evaluated graph and the failure view remains traceable.
Captured provider replays exercise the same validation and engine pipeline without a paid request. Replay tests locate nodes and corrections through typed semantics rather than provider-generated IDs, array positions, or candidate ordering. Randomized IDs and orderings protect that contract.
Reports have explicit phases: not verified, verified, and corrected. Recommendation state is separately recorded as not verified, valid, broken, or corrected. correctedValues is null before correction and contains recomputed values afterward.
Before export, evaluated statuses and values are materialized into the graph. The proof JSON contains the evaluated graph and the report generated from the same result. Tests assert agreement across pre-verification, broken, and corrected exports, including correction dependencies and absence of stale pending states.
The printable report includes:
The synthetic school-device fixture contains four documents, 11 exact source spans, 15 claim nodes, 15 initial dependencies, and one source-bound correction. The original memo’s faulty calculation is preserved rather than silently fixed. The fixture is stable, credential-free, and labeled deterministic throughout the UI and exports.
The public route constructs the OpenAI provider only after an explicit user action. The request uses the Responses API, store: false, no tools, no conversation linkage, bounded output, a timeout, and zero automatic retries. Documents and the draft memo are labeled untrusted evidence, and the system prompt explicitly rejects instructions contained within them.
Every Structured Output property is required; absence is represented with null. Provider values and units on source facts are discarded in favor of locally recovered evidence. Provider statuses, results, integrity, and winner values are not part of the authoritative contract.
If no server key is configured, the route returns HTTP 503 with code configuration and Live analysis is not configured. No deterministic fixture is substituted. The public deployment intentionally uses this no-key behavior.
Validation errors use stable codes and may contain only stage, code, schema path or safe ID, counts/booleans, request ID, latency, and aggregate token usage. Quotations, documents, prompts, provider output, secrets, environment values, and raw provider errors are excluded from client responses.
The repository includes 125 active unit, component, route, provider, replay, export, and metadata tests plus six Playwright scenarios. Coverage includes:
The production application is a native Next.js build deployed from main to Vercel at https://decispec.vercel.app. vercel.json pins the Next.js framework and npm run build:vercel. Canonical and social metadata resolve to the public production host. Live analysis requires server-side provider configuration.
The repository also retains a Vinext/Vite/Cloudflare-compatible build path. No D1 database or R2 bucket is configured for this product state.
NEXT_PUBLIC_ secret path exists.The proof is only as complete as the represented evidence and rules. The operation/unit set is constrained. Human review remains necessary for evidence completeness, policy interpretation, assumptions, and action. OCR, scanned PDFs, spreadsheets, durable storage, collaboration, identity, and signed verification artifacts are outside the current build.