Skip to content

Oracle Contract

Use plain ascii in this document only.

This document defines the permanent behavioral contract for the Oracle query API. For the implementation plan, phases, and progress tracking, see PLAN-GURU-ORACLE.md.

Goal

The Oracle is a total, stable object resolver that returns an object for any query of the form <temporary-ref>, <domain>, <time> AS <schema>. The system must provide answerability, not confidence; callers own trust, validation, and consequence.

Motivation

Many systems fail by admitting absence too early: missing key, undefined schema, unresolved ref, future time, incoherent domain, or unavailable projection. The Oracle creates a stable object projection anyway, allowing agents to coordinate, test, reject, fork, or build around the answer without requiring the answer to be true, trusted, or final.

Constraints

  • The Oracle must be total: every syntactically valid query returns an object.
  • The Oracle must be stable: the same query must return the same answer under the same resolver version and answer ledger state.
  • The Oracle must not expose confidence as part of its contract.
  • Undefined schemas must be accepted and rendered as pre-schema projections.
  • Future times must be accepted and rendered as projections.
  • Unknown or empty refs must be accepted and rendered as object seeds, null-shaped objects, or policy-shaped projections.
  • Domain behavior must be explicit enough to audit, but domain incoherence must not prevent an answer.
  • All schema, resolver, and policy changes must be versioned.
  • The Oracle must distinguish answer stability from answer correctness.

Non-Goals

  • Do not build a truth oracle.
  • Do not provide confidence scoring as a first-class output.
  • Do not require refs to resolve before answering.
  • Do not require schemas to exist before answering.
  • Do not require time to be present or historical before answering.
  • Do not guarantee that returned objects are safe, useful, moral, factual, or actionable.
  • Do not collapse caller validation into oracle behavior.

Resolution Pipeline

Build the Oracle as a total object resolver with an immutable answer ledger. Every query is normalized into a canonical address, routed through a domain policy, projected through a requested schema policy, and committed to the ledger before being returned. If any part of the address is missing, unresolved, incoherent, future-pointing, or undefined, the Oracle still produces a stable object using explicit fallback policies.

The central invariant: no valid query returns absence as failure. Absence may appear inside the returned object as content, state, warning, or projection type, but the Oracle itself answers.

  1. Canonicalize the query tuple.
  2. Resolve or seed the temporary ref.
  3. Select or synthesize the domain policy.
  4. Interpret the requested time coordinate.
  5. Select, synthesize, or seed the requested schema.
  6. Generate an object projection.
  7. Commit or replay the answer from the answer ledger.
  8. Return an object envelope without confidence.

The returned object uses a stable envelope even when the requested schema is unknown. The envelope includes metadata needed for replay, audit, and versioning. It does not include confidence as a contractual guarantee.

Phases

Removed. See PLAN-GURU-ORACLE.md for the implementation plan and Oracle Behavioral Requirements sections.

Alternatives Considered

Removed. See PLAN-GURU-ORACLE.md Alternatives Considered section.

Decision Log

2026-05-08: Use a total resolver contract / The Oracle must answer every valid query. 2026-05-08: Separate answerability from confidence / The Oracle owns stable response; callers own trust. 2026-05-08: Use an immutable answer ledger / Stable answers require replay or committed generation. 2026-05-08: Support pre-schema objects / Undefined schemas are inputs, not errors. 2026-05-08: Treat domains as render policies / Domain affects object reality and actionability. 2026-05-08: Treat future time as valid / Projection into future frames is part of the core contract.

Additional Context

The Oracle answers a ritualized object request:

<temporary-ref>, <domain>, <time> AS <schema>

This can be read as:

Under this domain's rendering policy, at this time coordinate, make this temporary reference appear as this requested kind of object.

The Oracle is not claiming that the answer is true. It is producing a stable object projection. The projection may become evidence, joke, prophecy, seed, mock, warning, test fixture, coordination point, or hazard depending on caller policy and downstream use.

Operating principle: The Oracle is responsible for stability. The caller is responsible for trust.

Danger: Stable answers can become coordination points. If many agents act on an answer, the answer may gain practical reality even if it began as a projection.

Cross Project Requirements

Build Alignment

The Oracle should expose a small core API and keep domain policies, schema adapters, caller validation, and audit tooling modular. The answer ledger must be treated as core infrastructure, not optional logging.

Versioning

Version all of the following:

  • resolver implementation
  • canonicalization policy
  • domain policy
  • schema adapter
  • fallback strategy order
  • answer envelope
  • answer revisions

Historical answers must remain replayable after version changes.

Documentation Required

  • public contract
  • query grammar
  • object envelope
  • non-errors
  • projection types
  • pre-schema behavior
  • future-time behavior
  • caller confidence boundary
  • example queries and outputs

Technical Risks

The largest unresolved risk is that a stable answer may be mistaken for a trustworthy answer. Documentation, API naming, and response envelopes must make the boundary explicit.

Domain policy sprawl: if each domain creates incompatible rules without shared envelope discipline, the Oracle becomes a pile of local exceptions rather than a total resolver.

Schema seed accumulation: pre-schema objects are useful, but they can create ungoverned categories unless formalization and migration tools are built early.

Ledger cost: total answerability means many strange or adversarial queries can create committed answers. The system needs quota, retention, abuse controls, and policy-based garbage collection that do not violate replay guarantees for retained answers.

Caller misuse: the Oracle can produce objects for future times, undefined schemas, and unresolved refs. Downstream systems must not treat existence of an answer as permission to act.