okf 1.13.0 → 2.0.0

data/lib/okf/skill/reference/SPEC.md

@@ -1,7 +1,7 @@
 <!--
   Vendored from the Open Knowledge Format reference repository.
   Source:  https://github.com/GoogleCloudPlatform/knowledge-catalog/blob/main/okf/SPEC.md
-  Commit:  ee67a5ca27044ebe7c38385f5b6cffc2305a9c1a
+  Commit:  3fcbb9f828c2f23d109c855ee403c3a4c81f3a96
   License: Apache-2.0 (c) Google LLC — included verbatim under its terms.
            Full license text: ./APACHE-2.0.txt
   This is the canonical normative reference loaded by the okf skill.
@@ -9,10 +9,10 @@
 
 # Open Knowledge Format (OKF)
 
-**Version 0.1 — Draft**
+**Version 0.2**
 
 OKF is an open, human- and agent-friendly format for representing
-*knowledge* — the metadata, context, and curated insight that surrounds
+*knowledge*: the metadata, context, and curated insight that surrounds
 data and systems. It is designed to be authored by people, generated by
 agents, exchanged across organizations, and consumed by both.
 
@@ -21,6 +21,10 @@ YAML frontmatter. There is no schema registry, no central authority, and
 no required tooling. If you can `cat` a file, you can read OKF; if you
 can `git clone` a repo, you can ship it.
 
+This document is self-contained: it specifies everything needed to
+produce and consume OKF v0.2. A summary of what changed from v0.1 is in
+§13.
+
 ---
 
 ## 1. Motivation
@@ -35,69 +39,104 @@ formats that are:
 - **Diffable** in version control.
 - **Portable** across tools, organizations, and time.
 
-The format is minimally opinionated. It standardizes only the small set
-of structural conventions needed to make a knowledge corpus
-*self-describing* — anything beyond that is left to the producer.
+Increasingly, a knowledge corpus is not authored once and then read: it
+is **continuously written and maintained by agents**. When most concepts 
+are machine-generated, a consumer needs answers that a plain 
+markdown-plus-frontmatter convention does not make first-class:
+
+1. What was this created from, and how was it verified? (**provenance**)
+2. How much should I trust it? (**trust**)
+3. Is it still true? (**freshness**)
+4. Is it the current version? (**lifecycle**)
+5. Was this number produced the way we said it must be? (**attestation**)
+
+OKF v0.2 makes provenance, trust, lifecycle, and attestation first-class
+while keeping the format minimally opinionated. The format is minimally 
+opinionated. It standardizes only the small set of structural conventions 
+needed to make a knowledge corpus self-describing — anything beyond that
+is left to the producer.
 
 ### Goals
 
-1. Define a universal format that **enrichment agents** can write into.
-2. Inform how **consumption agents** should read and traverse it.
+1. Define a universal format that **producers** (people, agents, export
+   pipelines) can write into.
+2. Inform how **consumers** (agents, UIs, search indexes, deterministic
+   code) should read and traverse it.
 3. Facilitate **exchange** of knowledge across systems and organizations.
-4. Standardize the small number of **required** fields that must be
-   present for content to be meaningfully consumed.
+4. Standardize the small set of frontmatter fields that make an
+   agent-maintained corpus **trustable**, without prescribing any runtime.
 
 ### Non-goals
 
 - Defining a fixed taxonomy of concept types.
 - Prescribing storage, serving, or query infrastructure.
-- Replacing domain-specific schemas (Avro, Protobuf, OpenAPI, etc.) —
+- Replacing domain-specific schemas (Avro, Protobuf, OpenAPI, and so on).
   OKF *references* them; it does not subsume them.
+- Specifying a packaging or invocation standard for the code an executor
+  or attester points at. OKF fixes the interface, not the packaging.
 
 ---
 
 ## 2. Terminology
 
-- **Knowledge Bundle** — A self-contained, hierarchical collection of
-  knowledge documents. The unit of distribution.
-- **Concept** — A single unit of knowledge within a bundle. Represented
-  as one markdown document. May describe a tangible asset (a table, an
+- **Knowledge Bundle** (or **bundle**): A self-contained, hierarchical
+  collection of knowledge documents. The unit of distribution.
+- **Concept**: A single unit of knowledge within a bundle, represented as
+  one markdown document. It may describe a tangible asset (a table, an
   API), an abstract idea (a metric, a business process), or anything in
   between.
-- **Concept ID** — The path of the concept's file within the bundle,
-  with the `.md` suffix removed. For example, `tables/users.md` has
-  concept ID `tables/users`.
-- **Frontmatter** — YAML metadata block delimited by `---` at the top of
+- **Concept ID**: The path of the concept's file within the bundle, with
+  the `.md` suffix removed.
+- **Frontmatter**: A YAML metadata block delimited by `---` at the top of
   a markdown file.
-- **Body** — Everything in the file after the frontmatter.
-- **Link** — A standard markdown link from one concept to another, used
-  to express relationships beyond the implicit parent/child hierarchy.
-- **Citation** — A link from a concept to an external source that
-  supports a claim in the body.
+- **Body**: Everything in the file after the frontmatter.
+- **Link**: A standard markdown link from one concept to another, used to
+  express relationships beyond the implicit parent/child hierarchy.
+- **Source**: A material a concept derives from, external or internal to
+  the bundle, recorded in the `sources` frontmatter field.
+- **Provenance**: The set of sources a concept derives from.
+- **Credibility signal**: An objective, per-source fact (`author`,
+  `usage_count`, `last_modified`) used to infer trust; OKF records the
+  signals, not a verdict (see §5.1).
+- **Actor**: A string identifying who or what performed an action, using
+  the convention `<producer>/<version>` for agents, `human:<id>` for
+  people, and `process:<id>` for automated processes (see §7).
+- **Trust tier**: A level derived from a concept's `verified` field:
+  unverified, machine-confirmed, or human-reviewed (see §5.3).
+- **Attested Computation**: A concept (`type: Attested Computation`)
+  carrying a sanctioned way to compute a value, so a consumer can confirm
+  the value was produced by running it (see §10).
+- **Executor**: Run instructions or code that executes a computation and
+  returns a receipt (see §10.2).
+- **Receipt**: The evidence a run returns, shaped by `executor.receipt`; a
+  runtime artifact, not stored in the bundle (see §10).
+- **Attester**: Deterministic (no-LLM) code that inspects a receipt and
+  returns a verdict (see §10.2).
 
 ---
 
-## 3. Bundle Structure
+## 3. Bundle structure
 
 A bundle is a directory tree of markdown files. The directory structure
-is independent of the domain — producers organize concepts however makes
+is independent of the domain: producers organize concepts however makes
 sense for the knowledge being captured.
 
 ```
 path/to/bundle/
-├── index.md                      # Optional. Directory listing for progressive disclosure.
-├── log.md                        # Optional. Chronological history of updates.
-├── <concept>.md                  # A concept at the bundle root.
-└── <subdirectory>/               # Subdirectories organize concepts into groups.
-    ├── index.md
-    ├── <concept>.md
-    └── <subdirectory>/
-        └── …
+  index.md                      # Optional. Directory listing for progressive disclosure.
+  log.md                        # Optional. Chronological history of updates.
+  <concept>.md                  # A concept at the bundle root.
+  <subdirectory>/               # Subdirectories organize concepts into groups.
+    index.md
+    <concept>.md
+    <subdirectory>/
+      ...
 ```
 
 A bundle MAY be distributed as:
 
-- A git repository (recommended — provides history, attribution, diffs).
+- A git repository (recommended, since it provides history, attribution,
+  and diffs).
 - A tarball or zip archive of the directory.
 - A subdirectory within a larger repository.
 
@@ -106,26 +145,26 @@ A bundle MAY be distributed as:
 The following filenames have defined meaning at any level of the
 hierarchy and MUST NOT be used for concept documents:
 
-| Filename     | Purpose                                                |
-|--------------|--------------------------------------------------------|
-| `index.md`   | Directory listing. See §6.                             |
-| `log.md`     | Update history. See §7.                                |
+| Filename   | Purpose                          |
+|------------|----------------------------------|
+| `index.md` | Directory listing. See §8.       |
+| `log.md`   | Update history. See §9.          |
 
 All other `.md` files are concept documents.
 
-Tags themselves remain a first-class concept — see the `tags`
-frontmatter field in §4.1. OKF does not specify a separate file format
-for aggregating documents by tag; producers that want a tag-browsing
-view can synthesize one at consumption time by scanning frontmatter.
+Tags remain a first-class concept through the `tags` frontmatter field
+(§4.1). OKF does not specify a separate file format for aggregating
+documents by tag; a consumer that wants a tag-browsing view can
+synthesize one at consumption time by scanning frontmatter.
 
 ---
 
-## 4. Concept Documents
+## 4. Concept documents
 
-Every concept is a UTF-8 markdown file. It has two parts:
+Every concept is a UTF-8 markdown file with two parts:
 
-1. A **YAML frontmatter block**, delimited by `---` on its own line at
-   the start of the file and a closing `---` on its own line.
+1. A **YAML frontmatter block**, delimited by `---` on its own line at the
+   start of the file and a closing `---` on its own line.
 2. A **markdown body**, containing free-form content.
 
 ### 4.1 Frontmatter
@@ -136,54 +175,63 @@ type: <Type name>                  # REQUIRED
 title: <Optional display name>
 description: <Optional one-line summary>
 resource: <Optional canonical URI for the underlying asset>
-tags: [<tag>, <tag>, …]            # Optional
-timestamp: <ISO 8601 datetime>     # Optional last-modified time
-# … other producer-defined key/value pairs
+tags: [<tag>, <tag>, ...]          # Optional
+# ... trust, lifecycle, provenance, and computation families (see §5, §10)
+# ... other producer-defined key/value pairs
 ---
 ```
 
 **Required:**
 
-- `type` — A short string identifying the kind of concept. Consumers
-  use this for routing, filtering, and presentation. Example values:
+- `type`: A short string identifying the kind of concept. Consumers use it
+  for routing, filtering, and presentation. Example values:
   `BigQuery Table`, `BigQuery Dataset`, `API Endpoint`, `Metric`,
-  `Playbook`, `Reference`.
+  `Playbook`, `Reference`, `Attested Computation`.
 
   Type values are **not** registered centrally. Producers SHOULD pick
   values that are descriptive and self-explanatory; consumers MUST
-  tolerate unknown types gracefully (typically by treating them as
-  generic concepts).
+  tolerate unknown types gracefully, typically by treating them as generic
+  concepts.
+
+`type` is the only always-required key; a concept carrying just `type` is
+fully conformant (§11).
 
-**Recommended (in priority order):**
+**Recommended:**
 
-- `title` — Human-readable display name. If omitted, consumers MAY
-  derive a title from the filename.
-- `description` — A single sentence summarizing the concept. Used by
+- `title`: Human-readable display name. If omitted, consumers MAY derive a
+  title from the filename.
+- `description`: A single sentence summarizing the concept. Used by
   `index.md` generators, search snippets, and previews.
-- `resource` — A URI that uniquely identifies the underlying asset the
+- `resource`: A URI that uniquely identifies the underlying asset the
   concept describes. Absent for concepts that describe abstract ideas
   rather than physical resources.
-- `tags` — A YAML list of short strings for cross-cutting categorization.
-- `timestamp` — ISO 8601 datetime of last meaningful change.
+- `tags`: A YAML list of short strings for cross-cutting categorization.
+
+The optional **provenance**, **trust**, and **lifecycle** families (§5) and
+the **computation** fields for Attested Computation concepts (§10) may also
+appear.
 
 **Extensions:** Producers MAY include any additional keys. Consumers
-SHOULD preserve unknown keys when round-tripping and SHOULD NOT reject
+SHOULD preserve unknown keys when round-tripping and MUST NOT reject
 documents with unrecognized fields.
 
 ### 4.2 Body
 
-The body is standard markdown. Producers SHOULD favor structural
-markdown — headings, lists, tables, fenced code blocks — over freeform
-prose, since structure aids both human reading and agent retrieval.
+The body is standard markdown. Producers SHOULD favor structural markdown
+(headings, lists, tables, fenced code blocks) over freeform prose, since
+structure aids both human reading and agent retrieval.
 
-There are no required body sections. The following section headings have
+There are no required body sections. The following headings have
 **conventional** meaning and SHOULD be used when applicable:
 
-| Heading        | Purpose                                                |
-|----------------|--------------------------------------------------------|
-| `# Schema`     | Structured description of an asset's columns/fields.   |
-| `# Examples`   | Concrete usage examples, often as fenced code blocks.  |
-| `# Citations`  | External sources backing claims in the body. See §8.   |
+| Heading         | Purpose                                                |
+|-----------------|--------------------------------------------------------|
+| `# Schema`      | Structured description of an asset's columns/fields.   |
+| `# Examples`    | Concrete usage examples, often as fenced code blocks.  |
+| `# Computation` | The sanctioned computation of an Attested Computation. See §10. |
+
+Per-claim attribution to external sources uses markdown footnotes keyed to
+`sources` entries rather than a body citations list (§5.1).
 
 ### 4.3 Example: a concept bound to a resource
 
@@ -194,7 +242,7 @@ title: Customer Orders
 description: One row per completed customer order across all channels.
 resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
 tags: [sales, orders, revenue]
-timestamp: 2026-05-28T14:30:00Z
+generated: { by: reference_agent/gemini-2.5-pro, at: 2026-05-28T14:30:00Z }
 ---
 
 # Schema
@@ -209,10 +257,6 @@ timestamp: 2026-05-28T14:30:00Z
 # Joins
 
 Joined with [customers](/tables/customers.md) on `customer_id`.
-
-# Citations
-
-[1] [BigQuery table schema](https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders)
 ```
 
 ### 4.4 Example: a concept not bound to a resource
@@ -220,72 +264,260 @@ Joined with [customers](/tables/customers.md) on `customer_id`.
 ```markdown
 ---
 type: Playbook
-title: Incident response — data freshness alert
+title: "Incident response: data freshness alert"
 description: Steps to triage a freshness alert on the orders pipeline.
 tags: [oncall, incident]
-timestamp: 2026-04-12T09:00:00Z
+generated: { by: human:ahormati, at: 2026-04-12T09:00:00Z }
 ---
 
 # Trigger
 
-A freshness alert fires when `orders` lags more than 30 minutes behind
-its expected SLA. See the [orders table](/tables/orders.md).
+A freshness alert fires when `orders` lags more than 30 minutes behind its
+expected SLA. See the [orders table](/tables/orders.md).
 
 # Steps
 
 1. Check the [ingestion job dashboard](https://example.com/dash).
-2. …
+2. ...
 ```
 
 ---
 
-## 5. Cross-linking
+## 5. Provenance, trust, and lifecycle
 
-Concepts MAY link to other concepts using standard markdown links. Two
-forms are supported:
+These frontmatter families make "where did this come from," "how much
+should I trust it," and "is it still current" answerable from frontmatter.
+All are optional. Their absence carries meaning: an unverified concept is
+distinguishable from a verified one, but is never rejected (§11).
+
+### 5.1 Provenance: `sources`
 
-### 5.1 Absolute (bundle-relative) links
+`sources` records the materials a concept derives from, external or
+internal to the bundle.
 
-Begin with `/`, interpreted relative to the bundle root.
+```yaml
+sources:
+  - id: ga4-schema
+    resource: https://developers.google.com/analytics/bigquery/export-schema
+    title: GA4 BigQuery Export schema
+    author: team:ga4-docs
+    usage_count: 5000
+    last_modified: 2026-05-30
+usage_window: { from: 2026-06-01, to: 2026-06-30 }
+```
+
+Each `sources` entry:
+
+- `resource`: REQUIRED within an entry. Names either a concrete artifact a
+  consumer can follow (an absolute URL, a bundle-relative path, or a path
+  into a `references/` subdirectory, §6) or a population or scope descriptor
+  it cannot (for example `all queries in BigQuery project X`).
+- `id`: Optional. A stable key used to attribute individual claims (see
+  below). SHOULD be present when the body cites the source.
+- `title`: Optional. Human-readable label for the source.
+- The optional credibility signals `author`, `usage_count`, and
+  `last_modified`, described next.
+
+**Source credibility signals.** OKF records objective, per-source signals
+so a consumer can judge how much to trust a concept by judging the sources
+it was extracted from. It does not store a credibility score: a score is
+subjective, unportable across consumers, and goes stale. Credibility is
+*inferred* from the signals, the same way trust tiers are (§5.3), not
+stored. Each signal is optional and lives on a `sources` entry:
+
+- `author`: Who or what produced the source, in the actor convention (§7).
+  An authority signal.
+- `usage_count`: How often `resource` was exercised (dashboard views, query
+  executions, page reads) over `usage_window`. An adoption and liveness
+  signal. For a single artifact it is that artifact's own exercise count;
+  for a scope descriptor it is the number of exercises within the scope that
+  touch the concept.
+- `last_modified`: When the source itself last changed (`YYYY-MM-DD`). A
+  recency signal, distinct from `generated.at` (§5.2), which records when
+  the concept was written.
+- `usage_window`: Written once as a sibling of `sources`, it frames every
+  `usage_count` with a `{ from, to }` date range. A single entry MAY carry
+  its own `usage_window` to override the shared one.
+
+`usage_count` is a coarse signal. It is comparable at the
+alive-versus-dead and order-of-magnitude level, and against a source's own
+history over time, but not as a precise cross-kind ranking: a scheduled
+query's executions and a human's deliberate dashboard views do not carry
+equal weight. Consumers SHOULD read it as liveness and trend, not as a
+score.
+
+Lineage is expressed through links, not a dedicated field. When a
+`resource` points at another OKF concept, the derivation edge already
+exists in the bundle graph (§6), so a consumer MAY recurse into that
+source's own `sources` and let credibility propagate. External leaf sources
+carry only their intrinsic signals. Deeper lineage (an explicit external
+`derived_from`, or data lineage) is out of scope for v0.2.
+
+**Per-claim attribution.** To attribute a specific claim, use a markdown
+footnote whose label is a `sources[].id`:
 
 ```markdown
-See the [customers table](/tables/customers.md) for the join key.
+The `events_` table is sharded daily as `events_YYYYMMDD`.[^ga4-schema]
+
+[^ga4-schema]: GA4 BigQuery Export schema
 ```
 
-This is the **recommended** form because it is stable when documents are
-moved within their subdirectory.
+The footnote label is the join key into `sources`; consumers resolve
+attribution through the matching entry, not by parsing the footnote prose.
+Labels are keyed rather than positional (`sources[0]`) because agents
+constantly rewrite these documents: a positional index misattributes
+silently the moment the list is reordered, whereas a stable `id` survives
+reordering.
 
-### 5.2 Relative links
+### 5.2 Trust: `generated` and `verified`
 
-Standard markdown relative paths.
+`generated` records how the current content was produced. `verified`
+records who or what has confirmed the content against its sources or
+`resource`. They are kept distinct because who *wrote* a concept need not
+be who *confirmed* it.
 
-```markdown
-See the [neighboring concept](./other.md).
+```yaml
+generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T22:53:05Z }
+```
+
+- `generated.by`: REQUIRED within `generated`. An actor (§7).
+- `generated.at`: An ISO 8601 datetime marking the content's last
+  meaningful change. Consumers use it to tell a recent edit from a stale
+  fact.
+
+```yaml
+verified:
+  - { by: human:ahormati, at: 2026-06-25T09:00:00Z }
+  - { by: process:finance-nightly, at: 2026-06-26T02:00:00Z }
+```
+
+- `verified`: A list of verification events, each with `by` (an actor) and
+  `at` (an ISO 8601 datetime). Multiple entries capture independent
+  checks, for example a human sign-off plus a nightly process. "How
+  recently" is the latest `at`.
+- `verified` is independent of `generated.at`: content can change without
+  re-confirmation, and facts can be re-confirmed without regeneration.
+- 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:
+
+```yaml
+verified: { by: human:ahormati, at: 2026-06-25T09:00:00Z }
+```
+
+### 5.3 Trust tiers
+
+Consumers derive a trust tier from `verified`, lowest to highest:
+
+- No `verified` key ⇒ **unverified**.
+- `verified` by non-`human:` actors only ⇒ **machine-confirmed**.
+- `verified` by a `human:<id>` actor ⇒ **human-reviewed**.
+
+A concept with no trust frontmatter is still consumable; consumers MUST
+NOT reject it (§11). Trust tiers are advisory signals, not access control.
+
+### 5.4 Lifecycle: `status`
+
+```yaml
+status: stable        # draft | stable | deprecated
+```
+
+- `draft`: not yet reviewed; possibly incomplete.
+- `stable`: default; ready for consumption.
+- `deprecated`: kept for links and history; no longer current.
+
+Absent `status` ⇒ `stable`.
+
+### 5.5 Lifecycle: `stale_after`
+
+```yaml
+stale_after: 2026-09-23   # absolute date; content is stale on/after this day
 ```
 
-### 5.3 Link semantics
+Optional. An absolute date (`YYYY-MM-DD`). A concept is stale when
+`today >= stale_after`. An absolute date, not a relative TTL, keeps the
+staleness decision a plain date comparison with no reference to when the
+concept was read.
+
+---
+
+## 6. Cross-linking and paths
+
+### 6.1 Links between concepts
+
+Concepts MAY link to other concepts using standard markdown links. Two
+forms are supported:
+
+- **Absolute (bundle-relative):** begins with `/`, interpreted relative to
+  the bundle root. This is the **recommended** form because it is stable
+  when documents are moved within their subdirectory.
 
-A link from concept A to concept B asserts a *relationship*. The
-specific kind of relationship (parent/child, references, joins-with,
-depends-on, etc.) is conveyed by the surrounding prose, not by the link
-itself. Consumers that build a graph view typically treat all links as
-directed edges of an untyped relationship.
+  ```markdown
+  See the [customers table](/tables/customers.md) for the join key.
+  ```
 
-Consumers MUST tolerate broken links — a link whose target does not
-exist in the bundle is not malformed; it may simply represent
-not-yet-written knowledge.
+- **Relative:** a standard markdown relative path.
+
+  ```markdown
+  See the [neighboring concept](./other.md).
+  ```
+
+A link from concept A to concept B asserts a *relationship*. The specific
+kind (parent/child, references, joins-with, depends-on) is conveyed by the
+surrounding prose, not by the link itself. Consumers that build a graph
+view typically treat all links as directed edges of an untyped
+relationship.
+
+Consumers MUST tolerate broken links: a link whose target does not exist
+in the bundle is not malformed; it may simply represent not-yet-written
+knowledge.
+
+### 6.2 Path-valued fields
+
+Several fields name a path or URI: `resource`, `sources[].resource`,
+`computation`, `executor.resource`, and `attester.resource` (§10). A
+`sources[].resource` may instead be a scope descriptor (§5.1), in which
+case it is not a path. Each path-valued field accepts:
+
+- an absolute URL (for example `https://...`),
+- a bundle-relative path beginning with `/`, or
+- a relative path (for example `../computations/revenue.md`).
+
+### 6.3 The `references/` convention
+
+A `references/` subdirectory conventionally mirrors external material, run
+instructions, or code as first-class concepts within the bundle. Sources,
+executors, and attesters commonly point into it (for example
+`references/attesters/revenue.py`). It is a naming convention, not a
+requirement.
 
 ---
 
-## 6. Index Files
+## 7. Actor convention
 
-An `index.md` file MAY appear in any directory, including the bundle
-root. It enumerates the directory's contents to support **progressive
-disclosure** — letting a human or agent see what is available before
+Fields that record an identity (`generated.by`, `verified[].by`) use a
+single actor convention:
+
+- `<producer>/<version>` for agents and tools, for example
+  `reference_agent/gemini-2.5-pro`.
+- `human:<id>` for a person, for example `human:ahormati`.
+- `process:<id>` for an automated process, for example
+  `process:finance-nightly`.
+
+Consumers that classify trust (§5.3) key off the `human:` prefix, so
+producers MUST use it for hand-authored or human-confirmed content.
+
+---
+
+## 8. Index files
+
+An `index.md` file MAY appear in any directory, including the bundle root.
+It enumerates the directory's contents to support **progressive
+disclosure**: letting a human or agent see what is available before
 opening individual documents.
 
-Index files contain no frontmatter. The body uses one or more sections,
-each grouping concepts under a heading:
+Index files contain no frontmatter, with one exception: a bundle-root
+`index.md` MAY carry an `okf_version` key (§12). The body uses one or more
+sections, each grouping concepts under a heading:
 
 ```markdown
 # Section / Group Heading
@@ -304,7 +536,7 @@ MAY synthesize one on the fly when none is present.
 
 ---
 
-## 7. Log Files (optional)
+## 9. Log files
 
 A `log.md` file MAY appear at any level of the hierarchy to record the
 history of changes to that scope. The format is a flat list of
@@ -314,48 +546,217 @@ date-grouped entries, newest first:
 # Directory Update Log
 
 ## 2026-05-22
-* **Update**: Added new BigQuery table reference for [Customer Metrics](/tables/customer-metrics.md).
+* **Update**: Added a BigQuery table reference for [Customer Metrics](/tables/customer-metrics.md).
 * **Creation**: Established the [Dataplex Playbook](/playbooks/dataplex.md).
 
 ## 2026-05-15
 * **Initialization**: Created foundational directory structure.
-* **Update**: Added progressive-disclosure guidelines to the root [index](/index.md).
 ```
 
-Date headings MUST use ISO 8601 `YYYY-MM-DD` form. Log entries are
-prose; the leading bold word (`**Update**`, `**Creation**`,
-`**Deprecation**`, etc.) is a convention, not a requirement.
+Date headings MUST use ISO 8601 `YYYY-MM-DD` form. Log entries are prose;
+the leading bold word (`**Update**`, `**Creation**`, `**Deprecation**`) is
+a convention, not a requirement.
 
 ---
 
-## 8. Citations
+## 10. Attested computations concept
+
+An Attested Computation concept carries not just what a value *means* but a
+sanctioned way to *compute* it, so a consumer can confirm the agent ran the
+blessed computation instead of improvising its own. Provenance (§5.1)
+answers "where did this claim come from"; attestation answers "was this
+number produced the way we said it must be." OKF records the computation
+and the means to check it; it does not execute anything itself.
+
+### 10.1 A computation is its own concept
+
+A sanctioned computation is a standalone concept of
+`type: Attested Computation`. A concept that needs the value (a `Metric`, a
+`BigQuery Table`) links to it with a normal markdown link (§6). Three
+properties motivate the standalone concept:
+
+- **`runtime` defines what `parameters` mean.** A parameter is a SQL bind
+  variable, a dbt var, or a Python argument depending on the runtime.
+  Keeping `runtime` and `parameters` in one frontmatter makes the binding
+  semantics self-evident.
+- **One computation, many consumers.** The same computation can back a
+  metric, a dashboard concept, and a report; as a concept it is referenced
+  once and reused.
+- **Trust state is per computation.** `verified`, `stale_after`, and a
+  single `attester` describe one thing. Revenue, profit, and margin each
+  verify and attest independently, which is three concepts, not three
+  entries in one frontmatter.
+
+### 10.2 Contract fields
+
+The contract is the concept's top-level frontmatter. In addition to the
+provenance, trust, and lifecycle families (§5), an Attested Computation
+concept carries:
+
+- `runtime`: REQUIRED for this type. The single field that says how to run
+  the computation, and so how the executor and attester interpret it and
+  what `parameters` mean. Example values: `bigquery`, `postgres`, `dbt`,
+  `python`, `Looker`.
+- `parameters`: A list of the typed, named holes the agent may fill. Each
+  entry: `{ name, type, required }`. Binding semantics follow `runtime`.
+- `computation`: Optional. A path (§6.2) to a file holding the
+  computation, used instead of an inline body fence (see §10.3). Absent ⇒
+  the body `# Computation` fence is the computation.
+- `executor`: How the computation is run. `resource` names run
+  instructions or code; a runner (an agent, or deterministic consumer
+  code) follows it. `receipt` declares the fields a run must return, the
+  evidence the attester inspects (for example a BigQuery `job_id` and the
+  SQL the job actually executed).
+- `attester`: The deterministic check. `resource` names code (no LLM) that
+  takes a receipt and returns a verdict. It is meant to run consumer-side.
+
+What sits behind a `resource` (a Skill, a script, a container) is a
+packaging choice; OKF fixes the interface, not the packaging (§1).
 
-When a concept's body makes claims sourced from external material,
-those sources SHOULD be listed under a `# Citations` heading at the
-bottom of the document, numbered:
+```markdown
+---
+type: Attested Computation
+title: Revenue for fiscal year
+description: Recognized revenue for a fiscal year, per Finance's definition.
+status: stable
+runtime: bigquery
+parameters:
+  - { name: year, type: integer, required: true }
+executor:
+  resource: references/skills/run-on-bq.md
+  receipt: [job_id, executed_sql, result]
+attester:
+  resource: references/attesters/revenue.py
+generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T22:53:05Z }
+verified: { by: human:ahormati, at: 2026-06-25T09:00:00Z }
+stale_after: 2026-09-23
+sources:
+  - id: rev-policy
+    resource: https://wiki.acme/finance/revenue-recognition
+    title: Revenue recognition policy
+---
+
+# Computation
+
+    SELECT SUM(amount) AS revenue
+    FROM finance.recognized_revenue
+    WHERE fiscal_year = @year
+
+The computation binds only the declared `parameters`, per the recognition
+policy.[^rev-policy]
+
+[^rev-policy]: Revenue recognition policy
+```
+
+### 10.3 The computation
+
+Provide the computation in one of two ways:
+
+- **Inline:** a single fenced code block in the body under `# Computation`.
+  Best for a short computation reviewed alongside the contract.
+- **File:** set `computation` to a path (§6.2) and omit the body fence.
+  Best for a long or generated computation, or one already kept as a real
+  file shared with non-OKF tooling.
+
+```yaml
+runtime: bigquery
+computation: references/computations/lib/revenue.sql
+parameters:
+  - { name: year, type: integer, required: true }
+```
+
+The agent MAY only supply *values* for the declared `parameters`; it MUST
+NOT author or edit the computation. Binding `computation` with the
+parameter values into the executable artifact is the consumer's job, and
+the attester independently re-derives that same binding to compare against
+what actually ran. Because the comparison is on the expanded, compiled
+artifact the receipt carries (`executed_sql`, `compiled_sql`), a rewritten
+query, a swapped computation file, or a mutated dependency fails the check.
+A typed, parameter-only surface is what makes "did the sanctioned thing
+run" a mechanical comparison rather than a judgement call.
+
+### 10.4 Concepts that use a computation
+
+A document is rarely a single computation. An income-statement overview
+that discusses revenue, profit, and margin stays one readable concept and
+links to one Attested Computation per figure:
 
 ```markdown
-# Citations
+---
+type: Metric
+title: Revenue
+description: Recognized revenue for a fiscal year.
+tags: [finance, revenue]
+status: stable
+generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T22:53:05Z }
+---
 
-[1] [BigQuery public dataset announcement](https://cloud.google.com/blog/products/data-analytics/...)
-[2] [Internal data quality runbook](https://wiki.acme.internal/data/quality)
+# Definition
+
+Recognized revenue sums `amount` over rows booked to the fiscal year,
+computed by [the revenue computation](../computations/revenue.md).
 ```
 
-Citation links MAY be absolute URLs, bundle-relative paths, or paths
-into a `references/` subdirectory that mirrors external material as
-first-class OKF concepts.
+Because each computation is its own concept, revenue can be fresh while
+profit is past its `stale_after`, and each attests on its own run.
+Co-locating them is a directory choice (a `computations/` folder with an
+`index.md`), not a frontmatter one.
+
+### 10.5 How a consumer uses it (informative)
+
+This subsection is informative, not normative. The runtime artifacts below
+are **not** stored in the bundle.
+
+1. **Discover** via `type: Attested Computation`, a frontmatter signal
+   liftable into `index.md`; a consumer reaches one directly or by
+   following a link from a concept that uses it.
+2. **Load** the contract from frontmatter and the computation from the
+   body (or the file named by `computation`).
+3. **Parameterize**: the agent supplies values for the declared parameters.
+4. **Execute**: the executor runs the bound computation and returns a
+   receipt shaped by `executor.receipt`.
+5. **Attest**: the consumer runs the attester over the receipt. It
+   confirms provenance (the computation that ran equals `computation` bound
+   with the claimed parameters, not agent-authored SQL) and fidelity (the
+   displayed value matches the receipt's authoritative source, re-read by
+   job id rather than taken from the agent's text).
+6. **Gate**: refuse to display a failing attestation; warn or refuse when
+   `today >= stale_after`. On success, surface the verdict (for example a
+   link to the job log) so trust is visible.
+
+### 10.6 Verification versus attestation
+
+`verified` (§5.2) and attestation are distinct, and both exist:
+
+- `verified` confirms the *definition* still matches policy. It is
+  doc-level, slow, and recorded in the bundle.
+- Attestation confirms a single *run* produced the value the sanctioned
+  way. It is per-call, runtime, and not stored in the bundle.
+
+A concept with a stale definition can still attest cleanly, and a
+freshly-verified definition still requires attestation on each run, which
+is why both are needed.
 
 ---
 
-## 9. Conformance
+## 11. Conformance
 
-A bundle is **conformant** with OKF v0.1 if:
+A bundle is **conformant** with OKF v0.2 if:
 
 1. Every non-reserved `.md` file in the tree contains a parseable YAML
    frontmatter block.
 2. Every frontmatter block contains a non-empty `type` field.
-3. Every reserved filename (`index.md`, `log.md`) follows the structure
-   described in §6 and §7 respectively when present.
+3. Every reserved filename (`index.md`, `log.md`) follows the structure in
+   §8 and §9 respectively when present.
+
+When the trust, lifecycle, provenance, or computation families are
+present, producers SHOULD follow §5 through §10, and consumers:
+
+- MUST treat a bare `verified` mapping as a one-element list (§5.2).
+- MUST NOT reject a concept for missing any optional family (§5.3).
+- SHOULD derive trust tiers and staleness only from the fields specified
+  here, and SHOULD surface, not silently drop, a failing attestation
+  (§10.5).
 
 Consumers SHOULD treat all other constraints as soft guidance. In
 particular, consumers MUST NOT reject a bundle because of:
@@ -366,95 +767,246 @@ particular, consumers MUST NOT reject a bundle because of:
 - Broken cross-links.
 - Missing `index.md` files.
 
-This permissive consumption model is intentional: OKF is meant to
-remain useful as bundles grow, get refactored, and are partially
-generated by agents.
+---
+
+## 12. Versioning
+
+This document specifies OKF version **0.2**. Revisions are versioned as
+`<major>.<minor>`:
+
+- A **minor** version bump introduces backward-compatible additions (new
+  optional fields, new conventional section headings).
+- A **major** version bump may make breaking changes (renaming required
+  fields, changing reserved filenames).
+
+Bundles MAY declare the version they target with `okf_version: "0.2"` in a
+bundle-root `index.md` frontmatter block (the only place frontmatter is
+permitted in an `index.md`). Consumers that do not understand the declared
+version SHOULD attempt best-effort consumption rather than refusing the
+bundle.
+
+### Considered and deferred
+
+The following are intentionally left to a future revision:
+
+- The full runtime protocol: receipt and verdict wire formats, and the
+  attestation lifecycle around a run.
+- The attester ABI, portability, and sandboxing, likely bundled with
+  future work on serving and Skills.
+- Attestation caching.
+- Semantic-layer templates (Looker, dbt) where the attester comparison
+  shifts from SQL equality to model-and-binding equality.
 
 ---
 
-## 10. Relationship to other formats
+## 13. Changes from v0.1
+
+v0.2 supersedes OKF v0.1 and is a minor version bump under §12, except for
+two deliberate breaking changes called out below because they rename or
+retire v0.1 fields. A v0.1 bundle is consumable by a v0.2 consumer under
+the fallbacks noted here.
 
-OKF is intentionally close to several established patterns:
+### 13.1 Breaking changes
 
-- **LLM "wiki" repositories** that use markdown + frontmatter as
-  agent-readable knowledge bases.
-- **Personal knowledge tools** like Obsidian and Notion, which use
-  hierarchical markdown with cross-links.
-- **"Metadata as code"** approaches that store catalog metadata
-  alongside source code rather than in a separate registry.
+- **`timestamp` is superseded by `generated.at`.** A concept's last
+  content change is now recorded as `generated: { by, at }` (§5.2).
+  Consumers MAY fall back to a legacy `timestamp` when `generated` is
+  absent.
+- **The body `# Citations` list is superseded by `sources`.** Provenance
+  moves to frontmatter (§5.1). Consumers SHOULD read `sources` and MAY
+  still parse a legacy `# Citations` body list for v0.1 documents.
 
-OKF differs primarily in being **specified** — pinning down the small
-set of rules needed for interoperability without dictating tooling.
+### 13.2 Additive changes
+
+All of the following are additive: new optional keys, one new concept
+type, and one new conventional heading. Their absence yields a plain v0.1
+concept.
+
+- New frontmatter families: `sources` with its per-source credibility
+  signals (`author`, `usage_count`, `last_modified`) and the `usage_window`
+  sibling; `generated`, `verified`; `status`, `stale_after` (§5).
+- New concept type `Attested Computation` and its computation keys
+  `runtime`, `parameters`, `computation`, `executor`, `attester` (§10).
+- New conventional body heading `# Computation` (§4.2).
+- The actor convention for `generated.by` and `verified[].by` (§7).
+
+Everything else (bundle structure, reserved filenames, the required
+`type`, recommended `title`/`description`/`resource`/`tags`, cross-linking,
+index files, log files, permissive conformance) is carried forward
+unchanged.
 
 ---
 
-## 11. Versioning
+## Appendix A: Worked example, an income statement
 
-This document specifies OKF version **0.1**. Future revisions will be
-versioned in the form `<major>.<minor>`:
+One bundle exercising every family, shown as a v0.1 to v0.2 migration of an
+income statement with two figures, revenue and gross profit.
 
-- A **minor** version bump introduces backward-compatible additions
-  (new optional fields, new conventional section headings).
-- A **major** version bump may make breaking changes (renaming required
-  fields, changing reserved filenames).
+### v0.1 form
 
-Bundles MAY declare the OKF version they target by including
-`okf_version: "0.1"` in a bundle-root `index.md` frontmatter block (the
-only place frontmatter is permitted in an `index.md`). Consumers that
-do not understand the declared version SHOULD attempt best-effort
-consumption rather than refusing the bundle.
+A single doc: both figures in one concept, the SQL in prose an agent can
+read, ignore, or rewrite, citations a flat list, and the only timestamp is
+`timestamp`.
 
+```markdown
 ---
+type: Metric
+title: Income statement (fiscal year)
+description: Headline income-statement figures for a fiscal year.
+tags: [finance, income-statement]
+timestamp: '2026-05-28T22:53:05+00:00'
+---
+
+# Definition
+The income statement reports revenue and gross profit for a fiscal year.
+
+# Revenue
+Recognized revenue sums `amount` over rows booked to the fiscal year:
+
+    SELECT SUM(amount) AS revenue
+    FROM finance.recognized_revenue
+    WHERE fiscal_year = <year>
+
+# Gross profit
+Gross profit by segment, per the cost-allocation standard:
+
+    SELECT gross_profit FROM fct_income_statement
+    WHERE fiscal_year = <year> AND segment = <segment>
+
+# Citations
+- https://wiki.acme/finance/fpa-handbook
+- https://wiki.acme/finance/revenue-recognition
+- https://wiki.acme/finance/cost-allocation
+```
+
+### v0.2 form
 
-## Appendix A — Minimal example bundle
+The two figures split into attested computations linked from a narrative
+concept. Every family is populated, and the two computations sit in
+deliberately different states so one consumer reaches two verdicts.
 
 ```
-my_bundle/
-├── index.md
-├── datasets/
-│   ├── index.md
-│   └── sales.md
-└── tables/
-    ├── index.md
-    ├── orders.md
-    └── customers.md
+bundles/finance/
+  metrics/income-statement.md      type: Metric  (narrates, links both)
+  computations/revenue.md          type: Attested Computation  (runtime: bigquery)
+  computations/profit.md           type: Attested Computation  (runtime: dbt)
+  references/skills/run-on-bq.md, run-dbt.md
+  references/attesters/sql-equality.py, dbt-binding.py
 ```
 
-`datasets/sales.md`:
+`metrics/income-statement.md`, the readable doc; trust lives on what it
+links, not here:
 
 ```markdown
 ---
-type: BigQuery Dataset
-title: Sales
-description: All sales-related tables for the retail business.
-resource: https://console.cloud.google.com/bigquery?p=acme&d=sales
-tags: [sales]
-timestamp: 2026-05-28T00:00:00Z
+type: Metric
+title: Income statement (fiscal year)
+description: Headline income-statement figures for a fiscal year.
+tags: [finance, income-statement]
+status: stable
+generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-20T22:53:05Z }
+verified: { by: human:ahormati, at: 2026-06-25T09:00:00Z }
+stale_after: 2026-12-31
+sources:
+  - id: fpa-handbook
+    resource: https://wiki.acme/finance/fpa-handbook
+    title: FP&A reporting handbook
 ---
 
-The sales dataset contains transactional tables, including
-[orders](/tables/orders.md) and [customers](/tables/customers.md).
+# Definition
+The income statement reports [revenue](../computations/revenue.md) and
+[gross profit](../computations/profit.md) for a fiscal year, per the FP&A
+reporting handbook.[^fpa-handbook] Each figure is produced by a sanctioned,
+attestable computation; this concept only narrates them.
+
+[^fpa-handbook]: FP&A reporting handbook
 ```
 
-`tables/orders.md`:
+`computations/revenue.md`, BigQuery SQL, human-verified, fresh, and
+corroborated by a live dashboard source carrying credibility signals:
 
 ```markdown
 ---
-type: BigQuery Table
-title: Orders
-description: One row per completed customer order.
-resource: https://console.cloud.google.com/bigquery?p=acme&d=sales&t=orders
-tags: [sales, orders]
-timestamp: 2026-05-28T00:00:00Z
+type: Attested Computation
+title: Revenue for fiscal year
+description: Recognized revenue for a fiscal year, per Finance's definition.
+tags: [finance, revenue]
+status: stable
+runtime: bigquery
+parameters:
+  - { name: year, type: integer, required: true }
+executor:
+  resource: references/skills/run-on-bq.md
+  receipt: [job_id, executed_sql, result]
+attester:
+  resource: references/attesters/sql-equality.py
+generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-28T14:00:00Z }
+verified: { by: human:ahormati, at: 2026-06-25T09:00:00Z }
+stale_after: 2026-12-31
+sources:
+  - id: rev-policy
+    resource: https://wiki.acme/finance/revenue-recognition
+    title: Revenue recognition policy
+    author: team:finance-fpa
+    last_modified: 2026-04-02
+  - id: exec-rev-dash
+    resource: dashboards/exec-revenue
+    title: Executive revenue dashboard
+    author: team:finance-fpa
+    usage_count: 5000
+    last_modified: 2026-06-18
+usage_window: { from: 2026-06-01, to: 2026-06-30 }
 ---
 
-# Schema
+# Computation
+
+    SELECT SUM(amount) AS revenue
+    FROM finance.recognized_revenue
+    WHERE fiscal_year = @year
+
+Recognized revenue per the recognition policy,[^rev-policy] corroborated by
+the executive revenue dashboard.[^exec-rev-dash]
+
+[^rev-policy]: Revenue recognition policy
+[^exec-rev-dash]: Executive revenue dashboard
+```
+
+`computations/profit.md`, a dbt model, process-verified, and past its
+`stale_after`:
+
+```markdown
+---
+type: Attested Computation
+title: Gross profit for fiscal year
+description: Gross profit by segment for a fiscal year, per the cost-allocation standard.
+tags: [finance, profit]
+status: stable
+runtime: dbt
+parameters:
+  - { name: year, type: integer, required: true }
+  - { name: segment, type: string, required: true }
+executor:
+  resource: references/skills/run-dbt.md
+  receipt: [run_id, compiled_sql, result]
+attester:
+  resource: references/attesters/dbt-binding.py
+generated: { by: reference_agent/gemini-2.5-pro, at: 2026-06-14T14:00:00Z }
+verified: { by: process:finance-nightly, at: 2026-06-12T08:00:00Z }
+stale_after: 2026-06-15
+sources:
+  - id: cost-alloc
+    resource: https://wiki.acme/finance/cost-allocation
+    title: Cost allocation standard
+---
+
+# Computation
+
+    SELECT gross_profit
+    FROM {{ ref('fct_income_statement') }}
+    WHERE fiscal_year = {{ var('year') }}
+      AND segment = {{ var('segment') }}
 
-| Column        | Type      | Description                  |
-|---------------|-----------|------------------------------|
-| `order_id`    | STRING    | Unique order identifier.     |
-| `customer_id` | STRING    | FK to [customers](/tables/customers.md). |
-| `total_usd`   | NUMERIC   | Order total in USD.          |
+Gross profit by segment per the cost-allocation standard.[^cost-alloc]
 
-Part of the [sales dataset](/datasets/sales.md).
+[^cost-alloc]: Cost allocation standard
 ```