Class: Textus::Read::Get

Inherits:
Object
  • Object
show all
Extended by:
Contract::DSL
Defined in:
lib/textus/read/get.rb

Overview

The one read path. ‘fetch:` controls behavior:

fetch: false (default) — pure read: the on-disk envelope annotated with
  a freshness verdict. NEVER builds the orchestrator (no threads/forks/
  locks/events). This is the safe default for direct (in-process)
  callers — accept/reject/publish, materializer, uid, validate_all/
  validator, schema tooling, and the hook context — that must read
  persisted truth without triggering a fetch.
fetch: true — read-through: after a stale verdict, hands off to the
  fetch orchestrator per the entry's fetch rule (degrades to the pure
  result when the key has no rule).

The public ‘get` verb is read-through because the contract declares `arg :fetch, default: true`, injected on every verb surface (RoleScope + MCP map_args, ADR 0062 amendment). Direct construction bypasses that injection and so gets the safe `fetch: false` method default.

Instance Method Summary collapse

Methods included from Contract::DSL

arg, around, cli, cli_stdin, contract, contract?, summary, surfaces, verb, view

Constructor Details

#initialize(container:, call:, evaluator: Textus::Domain::Freshness::Evaluator, orchestrator: nil) ⇒ Get

Returns a new instance of Get.



35
36
37
38
39
40
41
42
 
# File 'lib/textus/read/get.rb', line 35

def initialize(container:, call:, evaluator: Textus::Domain::Freshness::Evaluator, orchestrator: nil)
  @container  = container
  @call       = call
  @manifest   = container.manifest
  @file_store = container.file_store
  @evaluator  = evaluator
  @orchestrator = orchestrator # nil → built lazily on first fetch only
end

Instance Method Details

#call(key, fetch: false) ⇒ Object 



44
45
46
47
48
49
50
51
52
53
54
55
56
 
# File 'lib/textus/read/get.rb', line 44

def call(key, fetch: false)
  envelope = annotated_envelope(key)
  return envelope if envelope.nil?
  return envelope unless fetch && envelope.freshness&.stale

  fetch_policy = fetch_policy_for(key)
  return envelope if fetch_policy.nil?

  policy  = fetch_policy.to_freshness_policy
  verdict = Textus::Domain::Freshness::Verdict.stale(envelope.freshness.reason)
  outcome = orchestrator.execute(policy.decide(verdict), key: key)
  resolve(outcome, envelope)
end

#get(key, fetch: false) ⇒ Object

Strict variant: raises UnknownKey when the entry is missing. Used by consumers (e.g. uid, Validator) that distinguish absence.



60
61
62
63
 
# File 'lib/textus/read/get.rb', line 60

def get(key, fetch: false)
  call(key, fetch: fetch) ||
    raise(UnknownKey.new(key, suggestions: @manifest.resolver.suggestions_for(key)))
end