okf 1.13.0 → 2.1.0

data/lib/okf/skill/templates/attested-computation.md

@@ -0,0 +1,41 @@
+---
+type: Attested Computation
+title: <What the computation answers, e.g. Revenue for fiscal year>
+description: <Single sentence: what this computes and per whose definition.>
+tags: [<tag>]
+runtime: <REQUIRED — what runs it and what parameters mean: bigquery, dbt, python, …>
+parameters:
+  - { name: <name>, type: <type>, required: true }
+executor:
+  resource: <path to run instructions, e.g. /references/skills/run-on-bq.md>
+  receipt: [<field>, <field>]
+attester:
+  resource: <path to the deterministic check, e.g. /references/attesters/check.py>
+generated:
+  by: <actor per §7>
+  at: <ISO 8601>
+sources:
+  - id: <stable-key>
+    title: <the definition this computation implements>
+    resource: <url or path>
+---
+
+# Computation
+
+<The sanctioned computation, in one fenced block — OR set `computation: <path>`
+in the frontmatter instead and omit this section entirely (§10.3: a path is
+used *instead of* the fence; providing both leaves a consumer two candidate
+computations and no rule for which was sanctioned).>
+
+```<language>
+<the computation>
+```
+
+<Prose around it may cite sources per claim.[^<stable-key>]>
+
+<!-- rule:okf-computation-untouched -->
+<!-- §10.3, v0.2's only new MUST NOT: an agent MAY bind values for the declared
+     `parameters` and MUST NOT author or edit the computation itself. The whole
+     point of the type is that the computation is sanctioned — reviewed by a
+     person — and an improvised or "fixed" query silently loses that status.
+     If the computation is wrong, say so to a human; do not repair it. -->

data/lib/okf/skill/templates/concept.md

@@ -4,12 +4,23 @@ title: <Human-readable display name>
 description: <Single sentence summarizing the concept.>
 resource: <Canonical URI of the underlying asset — omit for abstract concepts>
 tags: [<tag>, <tag>]
-timestamp: <ISO 8601, e.g. 2026-06-14T10:00:00Z>
+generated:
+  by: <actor per §7 — human:<id>, process:<id>, or <producer>/<version>>
+  at: <ISO 8601, e.g. 2026-06-14T10:00:00Z>
+sources:
+  - id: <stable-key-the-body-cites>
+    title: <source title>
+    resource: <url, bundle-relative path, or scope descriptor>
+# Optional §5 families, when they apply:
+#   verified: [{ by: <actor>, at: <ISO 8601> }]   — who confirmed the content (a bare mapping reads as a one-element list)
+#   status: draft | stable | deprecated            — absent means stable
+#   stale_after: YYYY-MM-DD                        — stale on the day itself
 ---
 
 # Overview
 
-<What this concept is and why it matters.>
+<What this concept is and why it matters. Attribute each empirical claim to a
+source by its id: "The events table is sharded daily.[^<stable-key-the-body-cites>]">
 
 # Schema
 
@@ -18,7 +29,3 @@ timestamp: <ISO 8601, e.g. 2026-06-14T10:00:00Z>
 | Field | Type | Description |
 |-------|------|-------------|
 |       |      |             |
-
-# Citations
-
-[1] [<source title>](<url>)

data/lib/okf/skill/templates/root-index.md

@@ -1,5 +1,5 @@
 ---
-okf_version: "0.1"
+okf_version: "0.2"
 ---
 
 # <Directory / Group Heading>

data/lib/okf/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module OKF
-  VERSION = "1.13.0"
+  VERSION = "2.1.0"
 end

data/lib/okf.rb

@@ -16,7 +16,7 @@ module OKF
 
   # Blank in the frontmatter sense: nil, false, an empty/whitespace-only string,
   # or an empty collection. Numbers and other scalars are never blank. The one
-  # domain-wide predicate behind "non-empty type" (§9.2) and the recommended-field
+  # domain-wide predicate behind "non-empty type" (§11 cond. 2) and the recommended-field
   # warnings, kept here so the gem needs no ActiveSupport.
   def self.blank?(value)
     return true if value.nil? || value == false
@@ -25,6 +25,18 @@ module OKF
     value.respond_to?(:empty?) ? value.empty? : false
   end
 
+  # A temporal value as ISO 8601 — the one serialization rule for
+  # generated_at/stale_after, shared by the catalog row and /node/meta so the
+  # served and baked pages cannot drift over one concept's dates. YAML hands
+  # over a Date or a Time for an unquoted value (whose default to_s is not
+  # ISO); a String passes through; a degenerate value serializes as its
+  # string, never as raw structure.
+  def self.iso8601(value)
+    return nil if value.nil?
+
+    value.respond_to?(:iso8601) ? value.iso8601 : value.to_s
+  end
+
   # The directory a concept lives in, derived from its §2 id: the id *is* the
   # path minus `.md`, so putting the suffix back and taking the dirname is the
   # definition rather than a parse of it. One home for it because three views
@@ -36,11 +48,17 @@ module OKF
 
   require "okf/version"
 
+  # The OKF spec version this gem targets — one declaration behind the validate
+  # header and its help row, so the version a bundle is judged against cannot
+  # be stated two ways. The gem still *reads* v0.1 (§13.1); this is what it
+  # validates for. Known readable versions: Concept::KNOWN_SPEC_VERSIONS.
+  SPEC_VERSION = "0.2"
+
   # ── kernel: cross-cutting primitives ──
   require "okf/path"
   require "okf/safe_read"
 
-  # ── Markdown: parse structure out of a markdown document (§4/§5/§8) ──
+  # ── Markdown: parse structure out of a markdown document (§4/§6/§5.1) ──
   require "okf/markdown/frontmatter"
   require "okf/markdown/links"
   require "okf/markdown/citations"
@@ -49,6 +67,8 @@ module OKF
   require "okf/concept"
   require "okf/bundle"
   require "okf/bundle/graph"
+  require "okf/bundle/references"
+  require "okf/bundle/row_filter"
   require "okf/bundle/skeleton"
   require "okf/bundle/search"
   # These two lines ARE the engine preference order. Each engine registers itself

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: okf
 version: !ruby/object:Gem::Version
-  version: 1.13.0
+  version: 2.1.0
 platform: ruby
 authors:
 - Rodrigo Serradura
@@ -89,6 +89,8 @@ files:
 - lib/okf/bundle/linter.rb
 - lib/okf/bundle/linter/report.rb
 - lib/okf/bundle/reader.rb
+- lib/okf/bundle/references.rb
+- lib/okf/bundle/row_filter.rb
 - lib/okf/bundle/search.rb
 - lib/okf/bundle/search/index.rb
 - lib/okf/bundle/search/scan.rb
@@ -105,6 +107,7 @@ files:
 - lib/okf/cli/index.rb
 - lib/okf/cli/lint.rb
 - lib/okf/cli/loose.rb
+- lib/okf/cli/references.rb
 - lib/okf/cli/registry.rb
 - lib/okf/cli/render.rb
 - lib/okf/cli/search.rb
@@ -143,6 +146,15 @@ files:
 - lib/okf/skill/reference/SPEC.md
 - lib/okf/skill/reference/authoring.md
 - lib/okf/skill/reference/cli.md
+- lib/okf/skill/reference/cli/checks.md
+- lib/okf/skill/reference/cli/graph.md
+- lib/okf/skill/reference/cli/map.md
+- lib/okf/skill/reference/cli/registry.md
+- lib/okf/skill/reference/cli/search.md
+- lib/okf/skill/reference/cli/serve.md
+- lib/okf/skill/reference/cli/views.md
+- lib/okf/skill/reference/spec-map.md
+- lib/okf/skill/templates/attested-computation.md
 - lib/okf/skill/templates/concept.md
 - lib/okf/skill/templates/index.md
 - lib/okf/skill/templates/log.md