This guide is the companion to The Deterministic Core: A Fixed Foundation for AI-Augmented Applications. That paper defines the architecture, names its primitives, and documents its reference implementation. This guide describes how to apply it. Read the paper first. Then build.
The methodology has eight phases. Each phase produces a verifiable artifact. Skip none. The order is structural — each phase depends on the one before it.
Phase 1
Identify the Operational Decision
Every deterministic core begins with a single question: what decision, if it were wrong, would break trust in the entire system?
This is not a design question. It is a boundary question. You are identifying the line between what must be deterministic and what may be probabilistic. The line is drawn not by technical convenience but by operational consequence.
In CSI Pro, the decision is the renewal probability score. If that score fluctuates — same account, same data, different model, different session, different number — the entire application loses credibility. The QBR that follows from it becomes suspect. The triage recommendation becomes unreliable. The advisor paths become arbitrary. Everything downstream inherits the error.
So the score is deterministic. It is computed by a fixed formula that cannot be influenced by any model. The AI enriches the narrative around the score. It never touches the computation.
What to produce: A single sentence naming the decision that must be deterministic, and a second sentence describing what breaks if it isn't.
Phase 2
Design the Deterministic Computation
The computation must be expressed as a pure function. Same inputs — same outputs, every platform, every invocation, with or without AI, online or offline.
Start with a reasonable baseline. In CSI Pro, the scoring baseline is 60 — a neutral starting point that assumes neither health nor risk. From there, each signal applies a weighted adjustment: usage trend, support ticket volume, sentiment score, compound modifiers for converging signals. The formula is simple enough to explain to a customer. It is precise enough to produce identical results in any implementation.
The coefficients are not sacred. The 0.6× multiplier on positive usage trend and the 1.5× penalty on tickets above 10 are domain-informed defaults — calibration points, not empirical constants. Organizations adopting this pattern should expect to tune these thresholds against their own data. What does not change is the structure: a baseline, weighted signals, a clamping range, and a fixed output.
What to produce: The function, expressed in code or pseudocode, with every coefficient documented and every edge case handled. The function must be reviewable by someone who never built the system.
Phase 3
Build the Core First
The deterministic core is built and verified before any AI integration begins. This is not a sequencing preference. It is a structural requirement. If the core is incomplete, the AI layer will be asked to compensate — and compensation is where drift enters.
Build the computation layer. Write acceptance criteria that are specific and verifiable: "Given usage trend -12%, tickets 18, sentiment score -8, the score is 32." Not "the score seems reasonable." Not "the score is in the right range." An exact number. If the function produces a different number, the core is not done.
In CSI Pro, the acceptance criteria are embedded in the self-test suite — activated by appending ?test=true to the URL. The suite runs all scoring scenarios, asserts exact values, and reports pass/fail with a visual overlay. The test suite is part of the artifact itself. Not external. Not optional.
What to produce: A working computation layer with a test suite that asserts exact outputs for known inputs. The tests pass before Phase 4 begins.
Phase 4
Add the AI Enrichment Layer
The AI layer is an annotation engine. It receives computed truth from the core and contextualizes it. It does not compute. It does not decide. It does not mutate state.
In CSI Pro, the QBR generator has two paths. The deterministic path assembles a structured draft from the computed score, the risk patterns, the adoption stage, and the renewal timeline — all data that the core has already produced. The AI path takes the same data and generates richer narrative: more specific language, better flow, deeper contextualization. Both paths produce complete output. The AI path fires in parallel.
This is the Enhancement Boundary — the architectural primitive that separates computation from annotation. The boundary is one-directional. Data flows from core to model to output layer. Model output never flows back into the computation pipeline. This single constraint prevents drift from propagating. The model can hallucinate in its narrative, and the computation layer is structurally unaffected.
What to produce: For every AI-enhanced feature, a deterministic fallback that produces complete output, and an AI pipeline that fires in parallel. Both paths produce complete results. Neither blocks the user.
Phase 5
Implement the Validation Gate
Between the AI output and the user-facing output sits a validation gate. Its job is not to verify correctness — the computation layer already guarantees that. Its job is to verify coherence. Does the AI output contradict the deterministic data it was given?
In CSI Pro, this is lightweight. The QBR output is rendered into a structured DOM container. If the AI returns an empty response or an error, the deterministic output is displayed instead. The validation gate is a structural guarantee: the user never sees a blank panel, a loading spinner on core features, or AI output that contradicts the computed data.
For more complex systems, the validation gate can be richer: schema validation on AI-generated structured data, constraint checking on numerical outputs, keyword verification against the deterministic inputs. The sophistication of the gate scales with the consequence of failure. What does not scale is the principle: AI output is verified before it reaches the user.
What to produce: A gate that intercepts AI output and verifies it against the deterministic core data before rendering. The gate is not optional. It is the last structural defense against drift becoming visible.
Phase 6
Design the Degradation Paths
Graceful degradation is not a fallback strategy. It is the default operating assumption. The system is designed to function completely without AI, without network, without external services. Availability of these services is a bonus, not a requirement.
This means every feature has a degradation path. The path is not "show an error message." The path is "produce complete, coherent output using only the deterministic core." The user may notice that the AI-enhanced version is richer when it is available. They should never encounter a situation where AI unavailability means feature unavailability.
In CSI Pro, the degradation paths are explicit: if the AI times out, the deterministic QBR renders. If the network is offline, the entire application functions identically — only the AI enrichment and web research features are dimmed, and even those show cached results from the last successful session. The status bar displays the current AI state. The user always knows what is available and what is degraded.
What to produce: A documented degradation path for every AI-enhanced feature. Each path produces complete output. Each path is tested by disabling the AI and verifying the result.
Phase 7
Audit for Accessibility, Security, Edge Cases
The deterministic core guarantees computational coherence. It does not guarantee that the application is usable, secure, or robust. Those guarantees come from auditing against fixed standards.
Run an accessibility audit against WCAG 2.1 AA. Verify keyboard navigation, screen reader announcements, focus management, color contrast, and reduced-motion support. The Aether benchmark specifies the full audit criteria. Pass them.
Run a security audit against the OWASP baseline. Verify the Content Security Policy, the crypto implementation, the input sanitization, the API key handling. The Aether benchmark specifies the full security categories. Pass them.
Run edge-case testing. Offline mode. Mobile viewport. Privacy-focused browser. Storage quota exceeded. AI timeout. AI error. AI cancellation mid-response. Concurrent operations. Rapid input. Every edge case that is not handled becomes a bug that the user discovers before you do.
What to produce: An audit report with pass/fail for every applicable standard from the Aether benchmark. Failures are corrected before shipping. The audit is not a formality. It is the gate between development and deployment.
Phase 8
Ship as a Sovereign Artifact
The delivery format depends on the domain. CSI Pro ships as a single HTML file — zero dependencies, zero installation, opens in any browser. Archeo ships as a PyPI-packaged CLI. Other artifacts ship as portable binaries or self-contained archives. The format varies. The principle does not.
A sovereign artifact is one that the user owns. It runs without phoning home. It stores data locally. It encrypts at rest. It exports in open formats. It never gatekeeps functionality behind a subscription that the user did not explicitly choose. The economic model is separate from the architecture — the paper describes the three-lane model in full — but the artifact itself is always complete at the moment of download.
The single-file HTML form factor is the most constrained instantiation of the sovereign artifact principle. It enforces every architectural commitment by physical necessity: no dependencies means no npm. No external services means no cloud requirement. Offline-primary means the file must contain everything it needs. It is the form factor that proves the pattern at maximum constraint. If the architecture works here, it works anywhere.
What to produce: A deliverable that the user can download, open, and use — with no registration, no configuration file, no dependency installation. The artifact is complete. The user owns it.
The methodology transfers. These eight phases were applied to CSI Pro, Archeo, FlakeCapsule, and three other production artifacts. The primitives — the Enhancement Boundary, the Sovereign Artifact, Graceful Degradation by Design — recur across all of them. The domain changes. The structure holds. Start with the decision that must never be probabilistic. Build outward from there.