Rigor Internal Specification

Status

Draft. This directory is the authoritative specification of Rigor’s analyzer-internal contracts: the engine-surface that downstream features depend on and the public type-object model that plugins, rules, and CLI components consume.

The documents under docs/internal-spec/ describe what the analyzer is internally — the immutable shapes, public method surfaces, identity rules, normalization routing, and stability guarantees that engine and plugin code MUST follow. Type-language semantics (RBS interop, value lattice, narrowing rules, normalization rules, erasure rules, diagnostic identifiers) live in docs/type-specification/ and bind whenever a description here would conflict with type-language behavior.

Design rationale, the decision history, options that were rejected or deferred, and open questions live in docs/adr/ (in particular docs/adr/3-type-representation.md for the type-object model). When the specification and an ADR appear to disagree on what the analyzer does, the specification binds and the ADR should be amended.

Conventions

The keywords MUST, MUST NOT, SHOULD, SHOULD NOT, and MAY in this specification are to be interpreted as described in RFC 2119 and RFC 8174.

Ruby identifiers (Rigor::Type, Rigor::Trinary, Rigor::Type::Combinator, …) are placeholder names used in this specification. They MAY be renamed during implementation as long as the contract they describe is preserved. Type expressions in examples follow the conventions of docs/type-specification/.

Relationship to other documents

• docs/type-specification/ defines what the type language means. This directory defines what the analyzer exposes to satisfy that meaning.
• docs/adr/1-types.md records the rationale behind the type model. The type spec binds the resulting behavior; this directory binds the resulting internal contracts.
• docs/adr/2-extension-api.md records the extension-API decisions. A subset of those contracts (Type queries, Scope queries, capability-role conformance) is normative here; the ADR remains the rationale.
• docs/adr/3-type-representation.md records the rationale and open questions for the internal type representation. The decisions that have stabilized are normative in internal-type-api.md.
• docs/adr/4-type-inference-engine.md records the rationale, slice roadmap, and tentative answers to ADR-3’s open questions for the type-inference engine. The decisions that have stabilized are normative in inference-engine.md.

Reading order

Document	Scope
implementation-expectations.md	Engine surface — Scope, fact store, effect model, capability-role inference, normalization, RBS-erasure routing, public stability rules.
internal-type-api.md	Type-object public contract — method surface, identity and equality, immutability, normalization routing through factories, diagnostics-display routing.
inference-engine.md	Rigor::Scope#type_of(node) query — purity, immutable Scope discipline, fail-soft Dynamic[Top] policy, environment-loading boundaries.
reflection.md	Rigor::Reflection read-side facade — unified read shape over ClassRegistry + RbsLoader + Scope discovered facts. Public read shape for v0.1.0 plugin-API readiness.
cache.md	Rigor::Cache layer — descriptor schema, filesystem-backed Store, first cached producer (RbsConstantTable), CLI observability, diagnostic provenance.
flow-contribution.md	Rigor::FlowContribution bundle — the public packaging plugins, RBS::Extended annotations, and built-in narrowing rules use to hand the analyzer facts and effects at a single call edge.
flow-contribution-merger.md	Rigor::FlowContribution::Merger — the deterministic merge policy that folds multiple contributions at one call edge into a single tagged element list, with authority tiers and conflict detection.
plugin.md	Plugin contract — Rigor::Plugin::Base, Manifest (all extension fields), Loader / Registry registration + topological ordering, and Services injection.
plugin-trust.md	Plugin trust & I/O policy — TrustPolicy (trusted_gems, allowed_read_roots, network_policy), the IoBoundary mediated file/network surface, and the Services additions.
plugin-cache-producers.md	Plugin-side cache producers — the Plugin::Base.producer DSL, #cache_for callable, descriptor auto-prefixing, and glob_descriptor discovery helper.
macro-substrate.md	Macro / DSL expansion substrate — the Plugin::Macro::* value-object shapes (Tiers A/B/C/D + nested-class emission) a plugin declares to teach Rigor a metaprogramming library’s call shapes (ADR-16 / ADR-18 / ADR-36).
public-api.md	Public-API stability boundary — which namespaces (Rigor::Scope, Type, Environment, Reflection, FlowContribution, Diagnostic) the plugin contract is designed against, and which surfaces stay internal.
diagnostic-shape.md	Rigor::Analysis::Diagnostic field shape — fields, the from_node / from_location position convention, qualified_rule derivation + provenance. Descriptive, not yet locked (see public-api.md).
baseline.md	Baseline bucket-key derivation — the [file, rule, message_regex] tuple, path relativization, and the :rule / :message match modes (ADR-22).
worker-session.md	Worker-session protocol — WorkerSession’s shareable inputs, per-worker ownership boundary, and the sequential-equivalence contract behind parallel analysis (ADR-15).
dependency-source-inference.md	Opt-in dependency-source inference (ADR-10) — dependencies.source_inference: configuration, walker / dispatcher tier, DependencyEntry cache slice, dynamic.dependency-source.* diagnostic family.

This list grows as further internal contracts stabilize.