okf 1.12.0 → 2.0.0

data/lib/okf/cli/validate.rb

@@ -2,7 +2,7 @@
 
 module OKF
   class CLI
-    # The §9 conformance judge: is this legal OKF? Binary and tolerant — it is
+    # The §11 conformance judge: is this legal OKF? Binary and tolerant — it is
     # forbidden from failing a bundle over a broken link or a missing optional
     # field, which is lint's job. Exit 1 when non-conformant.
     class Validate < Command
@@ -16,7 +16,7 @@ module OKF
 
       def self.help_rows
         [
-          [ "validate  <dir|@slug> [--json]", "check OKF v0.1 conformance" ]
+          [ "validate  <dir|@slug> [--json]", "check OKF v#{OKF::SPEC_VERSION} conformance" ]
         ]
       end
 
@@ -38,7 +38,7 @@ module OKF
 
       def print_validation(dir, result)
         counts = result.counts
-        @out.puts "OKF v0.1 conformance — #{bundle_label(dir)}"
+        @out.puts "OKF v#{OKF::SPEC_VERSION} conformance — #{bundle_label(dir)}"
         @out.puts "  concepts: #{counts[:concepts]}   index.md: #{counts[:indexes]}   log.md: #{counts[:logs]}"
         result.errors.each { |e| @out.puts "  #{paint("✗ ERROR", 31)}  #{e[:path]}: #{e[:message]}" }
         result.warnings.each { |w| @out.puts "  #{paint("! warn", 33)}  #{w[:path]}: #{w[:message]}" }

data/lib/okf/cli.rb

@@ -39,8 +39,10 @@ module OKF
       # would let `--fields slug` pass on a search whose rows have none, and hand
       # back an empty object per match under a count that says otherwise.
       "matches_by_ref" => %w[slug id title type dir top_dir tags matched score snippet],
-      "concepts" => %w[id title type description tags timestamp status backlog_ref dir top_dir links_out links_in],
+      "concepts" => %w[id title type description tags generated_at generated_by generated trust status
+                       stale_after sources backlog_ref dir top_dir links_out links_in],
       "files" => %w[path id dir type title description],
+      "references" => %w[path dir kind referenced_by],
       "directories" => %w[dir ancestor index_path present synthesized count types tags subdirs body listing],
       "dirs" => %w[dir ancestor count subtree subdirs],
       "bundles" => %w[slug title dir mount default missing]
@@ -505,6 +507,7 @@ require "okf/cli/stats"
 require "okf/cli/types"
 require "okf/cli/tags"
 require "okf/cli/files"
+require "okf/cli/references"
 require "okf/cli/catalog"
 require "okf/cli/graph"
 

data/lib/okf/concept/file.rb

@@ -14,6 +14,13 @@ module OKF
     #
     # NOTE: this class is named File, which shadows Ruby's File inside the
     # OKF::Concept namespace — every filesystem call here uses ::File explicitly.
+    #
+    # absolute_path guards the *name* lexically (Path.join_under!), which is all a
+    # write needs — the file may not exist yet. A read has more to prove: the file
+    # is on disk now, so it may be a symlink whose name is inside the root but
+    # whose target is not, and File.expand_path does not resolve links. So #read
+    # goes through SafeRead, which realpath-resolves and refuses a target outside
+    # the root, closing the same escape Bundle::Reader closes on the bulk read.
     class File
       attr_reader :root, :path, :concept
 
@@ -53,11 +60,19 @@ module OKF
       end
 
       def reload
-        content = ::File.read(absolute_path, encoding: "UTF-8")
-        frontmatter, body = Markdown::Frontmatter.parse(content)
+        frontmatter, body = Markdown::Frontmatter.parse(read)
         @concept = Concept.new(path: @path, frontmatter: frontmatter, body: body)
         self
       end
+
+      # The file's own bytes, refused if the resolved target escapes the root by
+      # symlink. This is the guarded read a caller that wants the raw markdown
+      # (not a re-serialized `concept.to_markdown`) must use instead of reading
+      # #absolute_path itself — that path guards the *name* lexically, which a
+      # write needs but a read does not, since the file exists and may be a link.
+      def read
+        SafeRead.read!(@root, absolute_path)
+      end
     end
   end
 end

data/lib/okf/concept.rb

@@ -8,12 +8,114 @@ module OKF
     RESERVED_FILENAMES = %w[index.md log.md].freeze
 
     # The lint checks that apply to a single concept out of bundle context. The
-    # rest (orphan, backlog, duplicate_title, …) need the whole bundle.
+    # rest (orphan, backlog, duplicate_title, broken_source, …) need the whole
+    # bundle. Linter#selected_checks intersects silently, so a stale id here
+    # quietly stops Concept#lint running the check — a test pins the list
+    # against Linter::CHECKS.
     CONCEPT_SCOPED_CHECKS = %i[
-      stub missing_title missing_description missing_timestamp
-      uncited_external self_link unused_reference_def undefined_reference
+      stub missing_title missing_description missing_generated
+      expired uncited_external unattributed_claim unused_source
+      unprefixed_actor incomplete_computation
+      legacy_timestamp legacy_citations
+      self_link unused_reference_def undefined_reference
     ].freeze
 
+    # The spec versions this gem has a reader for, newest first — what a root
+    # `index.md`'s `okf_version` is checked against (§12). A document is always
+    # read as the newest version, without sniffing its shape: §13.1 makes the
+    # legacy fallbacks part of v0.2's own reading rule, so a v0.2 reader handed
+    # a v0.1 document is the correct reader for it.
+    KNOWN_SPEC_VERSIONS = %w[0.2 0.1].freeze
+
+    # The prefix §7 reserves for a person, and the whole of what §5.3's tier
+    # classifier keys off — which is why §7 makes producers MUST use it for
+    # hand-authored or human-confirmed content.
+    HUMAN_ACTOR = "human:"
+
+    # §5.4. The three values the spec names. A producer MAY use another (§4.1),
+    # and consumers MUST tolerate it, so this is what the validator warns
+    # against — never what a reader rejects.
+    STATUSES = %w[draft stable deprecated].freeze
+
+    # §5.4: "Absent `status` ⇒ `stable`."
+    DEFAULT_STATUS = "stable"
+
+    # §5.5's date spelling, strict. Both ends of the `today >= stale_after`
+    # comparison read it: #stale_after_date below, and the clock the linter is
+    # handed. Date.iso8601 alone also parses the basic (20260101) and week
+    # (2026-W01-1) forms, which would put the two ends on different grammars.
+    ISO_DATE = /\A\d{4}-\d{2}-\d{2}\z/.freeze
+
+    # The grammar for a *cutoff* a reader supplies (`--stale-after`, the MCP
+    # `stale_after`). Wider than ISO_DATE on purpose: a cutoff is a moment
+    # rather than a calendar day, and the value a caller has to hand is a
+    # concept's own `generated.at` — a full timestamp, which Date.iso8601
+    # reduces to its date. Narrow enough to still refuse the basic (20260101)
+    # and week (2026-W01-1) spellings, which are the ones a reader never means
+    # and the parser would silently reinterpret.
+    # `T` only: Date.iso8601 raises on the space-separated form, so admitting
+    # it here described a grammar one branch wider than the parser behind it —
+    # a value that matched the rule and was refused anyway.
+    ISO_CUTOFF = /\A\d{4}-\d{2}-\d{2}(?:T.+)?\z/.freeze
+
+    # §10.1. The type that carries a sanctioned computation.
+    ATTESTED_COMPUTATION = "Attested Computation"
+
+    # The narrowing semantics every surface shares — the CLI's --status/--trust
+    # and the MCP shell's filters both fold through here, so a tweak to either
+    # rule cannot land on one surface and not the other (which is exactly how
+    # `--status stable` and the MCP catalog once answered opposite things
+    # about one bundle).
+    #
+    # `--status` matches the EFFECTIVE status: absent (or blank) reads stable
+    # per §5.4, and the value folds through the same serialization #status
+    # keeps, so a YAML-boolean `status: no` is "false" everywhere.
+    def self.effective_status(value)
+      text = fold_status(value)
+      text.empty? ? DEFAULT_STATUS : text
+    end
+
+    # The case-fold *without* §5.4's default — what a filter's argument gets.
+    # The default belongs to a concept that declared no status; a caller who
+    # asked for one and supplied "" asked for a status no concept has, and
+    # answering `stable` there made the CLI's one empty filter that matches
+    # something (`--tag ""` and `--trust ""` both match nothing).
+    def self.fold_status(value)
+      value.nil? ? "" : value.to_s.strip.downcase
+    end
+
+    # A tier prints hyphenated (`machine-confirmed`); a caller may echo that
+    # back or type the underscore form — both fold to the wire spelling.
+    def self.fold_tier(value)
+      value.to_s.downcase.tr("_", "-")
+    end
+
+    # Whether a surface should *claim* a tier — the display half of §5.3, and
+    # deliberately not the same question as "what is the tier".
+    #
+    # §5.3 derives `unverified` for every concept that declares no verification,
+    # which is every concept of every v0.1 bundle. Displaying that unconditionally
+    # would paint a provenance verdict onto documents that never made one — the
+    # false claim the trust system exists to prevent — so the tier is computed for
+    # filtering and withheld from display. A concept that declared `generated` has
+    # opted into §5, and its `unverified` is a real answer worth showing; one that
+    # declared nothing is silent, and so is every surface reading this.
+    #
+    # Takes the two wire values so one rule serves both shapes: a Concept asks
+    # through #shows_trust?, a catalog row through Bundle::RowFilter.shows_trust?.
+    # Shared rather than re-spelled because the gate, the counts and the narrowing
+    # have to agree — a gate disagreeing with the counts beside it reads
+    # "unverified 3" over two chipped cards.
+    def self.shows_trust?(tier, declared_generated)
+      folded = fold_tier(tier)
+      # A blank tier is nothing to claim. #trust never returns one, so this is
+      # the client-side twin's `!!(c.trust && …)` guard kept in step rather than
+      # a case the Ruby can reach on its own — and the two are asserted equal.
+      return false if folded.empty?
+
+      !(folded == "unverified" && !declared_generated)
+    end
+
     # Whether a bundle-relative path names a reserved file rather than a concept.
     # `::File` is explicit: OKF::Concept::File (the on-disk handle) shadows Ruby's
     # File inside this namespace.
@@ -61,6 +163,8 @@ module OKF
       frontmatter["tags"]
     end
 
+    # The raw v0.1 field, kept readable because §13.1 keeps it consumable; what
+    # it *means* is #generated's business.
     def timestamp
       frontmatter["timestamp"]
     end
@@ -69,21 +173,230 @@ module OKF
       self.class.reserved?(path)
     end
 
+    # ── §5.2 trust: generated, with §13.1's timestamp fallback ──
+
+    # How the current content was produced, as { "by", "at" }. A lifted
+    # `timestamp` yields no `by`: the v0.1 field never recorded an actor, and
+    # inventing one — the running user, the gem — is exactly the false
+    # provenance claim §5 exists to prevent. A non-mapping `generated` is
+    # ignored rather than rejected (§11) and falls back like an absent one.
+    def generated
+      # Memoized like #sources, on the same premise — the model is immutable
+      # once built — and for the same reason: one catalog row asks four times
+      # over (#generated_at and #generated_by each read this twice), and every
+      # call re-stringifies and re-allocates. `defined?` rather than `||=`
+      # because nil is the answer for a whole bundle mid-migration, and `||=`
+      # would recompute exactly there.
+      return @generated if defined?(@generated)
+
+      @generated = compute_generated
+    end
+
+    # The content's last meaningful change (ISO 8601). The fallback is per-key,
+    # not per-mapping: a half-migrated document carrying `generated: { by: … }`
+    # *plus* a legacy `timestamp` must not lose its date.
+    def generated_at
+      at = generated && generated["at"]
+      return at unless OKF.blank?(at)
+
+      timestamp unless OKF.blank?(timestamp)
+    end
+
+    def generated_by
+      generated && generated["by"]
+    end
+
+    # Whether the document *declares* a `generated` mapping — raw-key detection,
+    # never the fallback. The one predicate that distinguishes hand-written
+    # (no provenance at all) from v0.1-with-timestamp, which #generated_at
+    # alone conflates.
+    def declared_generated?
+      frontmatter.key?("generated")
+    end
+
+    # §5.2: "A single verifier MAY be written as one { by, at } mapping without
+    # the list dash. Consumers MUST treat a bare mapping as a one-element list."
+    # Entries that are not mappings are dropped here and warned about by the
+    # validator; `verified: []` and all-entries-dropped fold into the key-absent
+    # case — every degenerate shape reads as unverified.
+    def verified
+      @verified ||= compute_verified
+    end
+
+    # §5.3 — derived, never stored. A stored tier would be subjective,
+    # unportable between consumers, and stale the moment a verification lands,
+    # so the spec has consumers infer it and OKF record only the events.
+    def trust_tier
+      events = verified
+      return :unverified if events.empty?
+      # Stripped, because the linter strips before matching §7's forms: an
+      # unstripped compare here let one report call a padded `  human:…` actor
+      # human-reviewed in its message and machine-confirmed in its stat.
+      return :human_reviewed if events.any? { |event| event["by"].to_s.strip.start_with?(HUMAN_ACTOR) }
+
+      :machine_confirmed
+    end
+
+    # The wire spelling of #trust_tier — the hyphenated string every surface
+    # prints (rows, lint's trust stat, the page), pinned so a consumer comparing
+    # against a literal knows which form arrives.
+    def trust
+      trust_tier.to_s.tr("_", "-")
+    end
+
+    # Whether this concept's tier is one a surface should show — see
+    # .shows_trust? for why the display question is separate from the derivation.
+    def shows_trust?
+      Concept.shows_trust?(trust, declared_generated?)
+    end
+
+    # ── §5.1 provenance: sources, with §13.1's Citations fallback ──
+
+    # The materials this concept derives from, as a list of mappings each
+    # carrying at least a `resource`. The fallback to a legacy `# Citations`
+    # body list fires when the native value yields *zero mappings* — absent,
+    # non-list, or a list with no mapping entries — not merely when the key is
+    # absent: `sources: [prod-db, warehouse]` has always been a legal free-form
+    # key (§4.1), and it must not silently mask a document's real provenance.
+    def sources
+      # Memoized like the bundle's graph and for the same reason: the model is
+      # immutable once built, several lint checks and the row builder each ask,
+      # and the v0.1 fallback re-parses the body on every call.
+      @sources ||= compute_sources
+    end
+
+    # §5.1. Written once as a sibling of `sources`, framing every `usage_count`
+    # with a { from, to } range; an entry MAY override it (validated for shape,
+    # deliberately consumed by nothing — see model/concept.md).
+    def usage_window
+      mapping("usage_window")
+    end
+
+    # ── §5.4/§5.5 lifecycle ──
+
+    # The effective status, defaulted per §5.4. #declared_status keeps the raw
+    # value for the surfaces that must not fabricate frontmatter a concept
+    # never declared. Defaulted off the same serialization the row prints —
+    # not OKF.blank? — because Psych reads `status: no` as false, blank? folds
+    # false into "absent", and the row's `&.to_s` prints "false": one concept,
+    # two answers. Serializing first keeps every surface on the same string.
+    def status
+      # Defaulted, *not* folded — and the split is the point. Every surface
+      # that displays a status prints what the producer wrote: the catalog row
+      # (`declared_status&.to_s`), the card chip, the inspector line. Only
+      # comparison folds, which is `.effective_status`'s job and why it is a
+      # separate method. Folding here made the library accessor the one place
+      # answering `deprecated` where the whole CLI and page say `Deprecated`.
+      text = declared_status.nil? ? "" : declared_status.to_s.strip
+      text.empty? ? DEFAULT_STATUS : text
+    end
+
+    def declared_status
+      frontmatter["status"]
+    end
+
+    # §5.5. An absolute date, not a relative TTL — which is what keeps staleness
+    # a plain date comparison with no reference to when the concept was read.
+    def stale_after
+      frontmatter["stale_after"]
+    end
+
+    # The parsed `stale_after`, or nil when absent or unparseable — strict
+    # YYYY-MM-DD, the one spelling §5.5 names. Psych may already have yielded a
+    # Date; an unparseable string is a validator warning, never a read failure.
+    def stale_after_date
+      value = stale_after
+      # DateTime < Date, so a bare Date check would admit the one temporal
+      # class the strict-YYYY-MM-DD contract excludes — the same exclusion the
+      # validator's date check makes, kept in step so lint, validate and the
+      # page cannot answer three ways about one value.
+      return value if value.is_a?(Date) && !value.is_a?(DateTime)
+
+      text = value.to_s.strip
+      return nil unless text.match?(ISO_DATE)
+
+      begin
+        Date.iso8601(text)
+      rescue ArgumentError
+        nil
+      end
+    end
+
+    # Pure: it takes the day rather than reading the clock. §5.5 puts the
+    # boundary *on* the day itself: stale when `today >= stale_after`.
+    def stale_on?(today)
+      date = stale_after_date
+      !date.nil? && today >= date
+    end
+
+    # ── §10 attested computation ──
+
+    def attested_computation?
+      type.to_s.strip == ATTESTED_COMPUTATION
+    end
+
+    # §10.2. REQUIRED for the type — but §11's conformance conditions are only
+    # three, so its absence is a warning and never an error.
+    def runtime
+      frontmatter["runtime"]
+    end
+
+    # The typed, named holes an agent may fill (§10.3: bind values for declared
+    # parameters only; never author or edit the computation).
+    def parameters
+      Array(frontmatter["parameters"]).grep(Hash)
+                                      .map { |entry| Markdown::Frontmatter.stringify_keys(entry) }
+    end
+
+    # §10.3. A path to a file holding the computation, used instead of an inline
+    # body fence. Absent ⇒ the `# Computation` fence is the computation.
+    def computation
+      frontmatter["computation"]
+    end
+
+    # §10.2. How the computation is run: `resource` names run instructions,
+    # `receipt` declares the fields a run must return.
+    def executor
+      mapping("executor")
+    end
+
+    # §10.2. The deterministic (no-LLM) check that takes a receipt and returns a
+    # verdict. Meant to run consumer-side.
+    def attester
+      mapping("attester")
+    end
+
+    # The §13.1 lifted entries, parsed once for however many readers ask —
+    # #sources' fallback and the linter's broken_source (which checks the
+    # section's targets even beside a native list) share this parse.
+    def citation_entries
+      @citation_entries ||= Markdown::Citations.entries(body)
+    end
+
+    # ── detection (lint's and the surfaces'; never reading's) ──
+
+    def legacy_timestamp?
+      frontmatter.key?("timestamp")
+    end
+
+    # Memoized with defined? because the answer may be false: the linter asks
+    # per check, and each un-memoized ask was a full body scan.
+    def legacy_citations?
+      return @legacy_citations if defined?(@legacy_citations)
+
+      @legacy_citations = !Markdown::Citations.section(body).nil?
+    end
+
     # ── analysis (pure; the same primitives the graph/linter use) ──
 
-    # Raw markdown cross-link targets in the body, in document order (spec §5).
+    # Raw markdown cross-link targets in the body, in document order (spec §6.1).
     def links
       Markdown::Links.extract(body)
     end
 
-    # Citation link targets under the `# Citations` section (spec §8), or [].
-    def citations
-      Markdown::Citations.targets(body)
-    end
-
     # Body links that point outside the bundle — external URLs and mailto:.
     def external_links
-      links.select { |raw| raw.match?(Markdown::Links::SCHEME) || raw.start_with?("mailto:") }
+      links.select { |raw| raw.match?(Markdown::Links::SCHEME) || raw.match?(Markdown::Links::MAILTO) }
     end
 
     # Serialize back to a markdown document (frontmatter + body) — the inverse of
@@ -97,5 +410,44 @@ module OKF
     def lint(**options)
       Bundle.new(concepts: [ self ]).lint(only: CONCEPT_SCOPED_CHECKS, **options)
     end
+
+    private
+
+    def compute_generated
+      native = frontmatter["generated"]
+      return Markdown::Frontmatter.stringify_keys(native) if native.is_a?(Hash)
+      return nil if OKF.blank?(timestamp)
+
+      { "at" => timestamp }
+    end
+
+    def compute_verified
+      raw = frontmatter["verified"]
+      entries = raw.is_a?(Hash) ? [ raw ] : Array(raw)
+      entries.grep(Hash).map { |entry| Markdown::Frontmatter.stringify_keys(entry) }
+    end
+
+    def compute_sources
+      native = frontmatter["sources"]
+      if native.is_a?(Array)
+        entries = native.grep(Hash)
+        return entries.map { |entry| Markdown::Frontmatter.stringify_keys(entry) } unless entries.empty?
+      end
+
+      citation_entries.map do |entry|
+        source = {}
+        source["title"] = entry[:text] unless OKF.blank?(entry[:text])
+        source["resource"] = entry[:target]
+        source
+      end
+    end
+
+    # A frontmatter value that must be a mapping, with its keys stringified — or
+    # nil when it is anything else. The validator warns about the "anything
+    # else" case; readers just see nothing, per §11's tolerate-don't-reject.
+    def mapping(key)
+      value = frontmatter[key]
+      value.is_a?(Hash) ? Markdown::Frontmatter.stringify_keys(value) : nil
+    end
   end
 end

data/lib/okf/markdown/citations.rb

@@ -2,7 +2,7 @@
 
 module OKF
   module Markdown
-    # Parses the conventional `# Citations` section of a concept body (spec §8): the
+    # Parses the retired `# Citations` section of a v0.1 concept body (§13.1): the
     # block of external sources listed at the bottom of a document. Pure and
     # fence-aware, mirroring Links; it reuses Links.extract to pull the citation link
     # targets so citations and cross-links agree on what counts as a link.
@@ -10,6 +10,13 @@ module OKF
       # A markdown ATX heading line: 1–6 `#`, whitespace, then the heading text.
       HEADING = /\A(\#{1,6})\s+(.*?)\s*\z/.freeze
       CITATIONS = /\ACitations\z/i.freeze
+      # A list item (or lone line) that is only a URL — the v0.1 spelling the
+      # v0.2 SPEC's own Appendix A uses — and the same item written as an
+      # autolink (which also admits mailto:). Both are citations with no text
+      # to lift into a title; both compose their scheme from Links' one
+      # grammar, so citations and cross-links answer the case question alike.
+      URL_ITEM = %r{\A(?:[-*+]\s+)?(#{Links::SCHEME_NAME}://\S+)\z}.freeze
+      AUTOLINK_ITEM = /\A(?:[-*+]\s+)?<(#{Links::SCHEME_NAME}:[^>\s]+)>\z/.freeze
 
       module_function
 
@@ -40,9 +47,39 @@ module OKF
         lines.join unless level.nil?
       end
 
-      # Citation link targets within the `# Citations` section (empty when absent).
-      def targets(body)
-        Links.extract(section(body).to_s)
+      # The citation entries as { text:, target: } pairs, in document order —
+      # what Concept#sources lifts into { "title", "resource" } mappings. Three
+      # item forms (§13.1): labelled links
+      # carry their text; bare-URL and autolink items have none; a
+      # reference-style citation still yields its target through Links.extract.
+      def entries(body)
+        text = section(body).to_s
+        definitions = Links.reference_definitions(text)
+        found = []
+        Links.each_prose_line(text) do |line|
+          item = line.strip
+          match = AUTOLINK_ITEM.match(item) || URL_ITEM.match(item)
+          if match
+            found << { text: "", target: match[1] }
+            next
+          end
+
+          # Both grammars scan the same line and merge by offset, so the list
+          # keeps document order *within* a line too — scanning all inline
+          # links before any reference links reversed a mixed line's own order,
+          # and a migration lifting sources off this output writes the list
+          # permanently. Reference items resolve in place, text kept.
+          items = []
+          line.scan(Links::INLINE_LINK) do |label, target|
+            items << [ Regexp.last_match.begin(0), { text: label.to_s.strip, target: target } ]
+          end
+          line.scan(Links::REFERENCE_LINK) do |label, explicit|
+            target = definitions[(explicit.empty? ? label : explicit).strip.downcase]
+            items << [ Regexp.last_match.begin(0), { text: label.to_s.strip, target: target } ] if target
+          end
+          items.sort_by(&:first).each { |_, entry| found << entry }
+        end
+        found
       end
     end
   end

data/lib/okf/markdown/frontmatter.rb

@@ -2,7 +2,7 @@
 
 module OKF
   # Primitives for parsing structure out of a markdown document — the format layer
-  # (§4 frontmatter, §5 links, §8 citations) shared by Concept, Bundle, and the
+  # (§4 frontmatter, §6 links, §5.1 sources) shared by Concept, Bundle, and the
   # analyzers. Pure string-in/string-out; no disk, no domain knowledge.
   module Markdown
     module Frontmatter