code2okf 0.1.0__py3-none-any.whl

code2okf/SPEC.md

@@ -0,0 +1,1006 @@
+# Open Knowledge Format (OKF)
+
+**Version 0.2**
+
+OKF is an open, human- and agent-friendly format for representing
+*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.
+
+The format is intentionally minimal: a directory of markdown files with
+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
+
+The space of knowledge representation for AI agents is evolving quickly,
+and many incompatible conventions are emerging. OKF takes the position
+that knowledge is best represented in commonly accessible, established
+formats that are:
+
+- **Readable** by humans without tooling.
+- **Parseable** by agents without bespoke SDKs.
+- **Diffable** in version control.
+- **Portable** across tools, organizations, and time.
+
+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 **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 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, 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** (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.
+- **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.
+- **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
+
+A bundle is a directory tree of markdown files. The directory structure
+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>/
+      ...
+```
+
+A bundle MAY be distributed as:
+
+- 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.
+
+### 3.1 Reserved filenames
+
+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 §8.       |
+| `log.md`   | Update history. See §9.          |
+
+All other `.md` files are concept documents.
+
+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
+
+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.
+2. A **markdown body**, containing free-form content.
+
+### 4.1 Frontmatter
+
+```yaml
+---
+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
+# ... 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 it
+  for routing, filtering, and presentation. Example values:
+  `BigQuery Table`, `BigQuery Dataset`, `API Endpoint`, `Metric`,
+  `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.
+
+`type` is the only always-required key; a concept carrying just `type` is
+fully conformant (§11).
+
+**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
+  `index.md` generators, search snippets, and previews.
+- `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.
+
+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 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.
+
+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.  |
+| `# 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
+
+```markdown
+---
+type: BigQuery Table
+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]
+generated: { by: reference_agent/gemini-2.5-pro, at: 2026-05-28T14:30:00Z }
+---
+
+# Schema
+
+| Column        | Type      | Description                              |
+|---------------|-----------|------------------------------------------|
+| `order_id`    | STRING    | Globally unique order identifier.        |
+| `customer_id` | STRING    | Foreign key into [customers](/tables/customers.md). |
+| `total_usd`   | NUMERIC   | Order total in US dollars.               |
+| `placed_at`   | TIMESTAMP | When the customer submitted the order.   |
+
+# Joins
+
+Joined with [customers](/tables/customers.md) on `customer_id`.
+```
+
+### 4.4 Example: a concept not bound to a resource
+
+```markdown
+---
+type: Playbook
+title: "Incident response: data freshness alert"
+description: Steps to triage a freshness alert on the orders pipeline.
+tags: [oncall, incident]
+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).
+
+# Steps
+
+1. Check the [ingestion job dashboard](https://example.com/dash).
+2. ...
+```
+
+---
+
+## 5. Provenance, trust, and lifecycle
+
+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).
+
+Every timestamp-valued key in OKF is an ISO 8601 datetime with an explicit
+UTC offset, for example `2026-06-30T14:00:00Z`.
+
+### 5.1 Provenance: `sources`
+
+`sources` records the materials a concept derives from, external or
+internal to the bundle.
+
+```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-30T00:00:00Z
+usage_window: { from: 2026-06-01T00:00:00Z, to: 2026-06-30T00:00:00Z }
+```
+
+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. 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 }` datetime 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
+The `events_` table is sharded daily as `events_YYYYMMDD`.[^ga4-schema]
+
+[^ga4-schema]: GA4 BigQuery Export schema
+```
+
+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 Trust: `generated` and `verified`
+
+`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.
+
+```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-23T00:00:00Z   # content is stale on/after this instant
+```
+
+Optional. An absolute instant. A concept is stale when
+`now >= stale_after`. An absolute instant, not a relative TTL, keeps the
+staleness decision a plain 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.
+
+  ```markdown
+  See the [customers table](/tables/customers.md) for the join key.
+  ```
+
+- **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.
+
+---
+
+## 7. Actor convention
+
+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, 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
+
+* [Title 1](relative-url-1) - short description of item 1
+* [Title 2](relative-url-2) - short description of item 2
+
+# Another Section
+
+* [Subdirectory](subdir/) - short description of the subdirectory
+```
+
+Entries SHOULD include the description from the linked concept's
+frontmatter. Producers MAY generate `index.md` automatically; consumers
+MAY synthesize one on the fly when none is present.
+
+---
+
+## 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
+date-grouped entries, newest first:
+
+```markdown
+# Directory Update Log
+
+## 2026-05-22
+* **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.
+```
+
+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.
+
+---
+
+## 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).
+
+```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-23T00:00:00Z
+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
+---
+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 }
+---
+
+# Definition
+
+Recognized revenue sums `amount` over rows booked to the fiscal year,
+computed by [the revenue computation](../computations/revenue.md).
+```
+
+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
+   `now >= 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.
+
+---
+
+## 11. Conformance
+
+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 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:
+
+- Missing optional frontmatter fields.
+- Unknown `type` values.
+- Unknown additional frontmatter keys.
+- Broken cross-links.
+- Missing `index.md` files.
+
+---
+
+## 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.
+
+---
+
+## 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.
+
+### 13.1 Breaking changes
+
+- **`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.
+
+### 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.
+
+---
+
+## Appendix A: Worked example, an income statement
+
+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.
+
+### v0.1 form
+
+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
+
+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.
+
+```
+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
+```
+
+`metrics/income-statement.md`, the readable doc; trust lives on what it
+links, not here:
+
+```markdown
+---
+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-31T00:00:00Z
+sources:
+  - id: fpa-handbook
+    resource: https://wiki.acme/finance/fpa-handbook
+    title: FP&A reporting handbook
+---
+
+# 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
+```
+
+`computations/revenue.md`, BigQuery SQL, human-verified, fresh, and
+corroborated by a live dashboard source carrying credibility signals:
+
+```markdown
+---
+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-31T00:00:00Z
+sources:
+  - id: rev-policy
+    resource: https://wiki.acme/finance/revenue-recognition
+    title: Revenue recognition policy
+    author: team:finance-fpa
+    last_modified: 2026-04-02T00:00:00Z
+  - id: exec-rev-dash
+    resource: dashboards/exec-revenue
+    title: Executive revenue dashboard
+    author: team:finance-fpa
+    usage_count: 5000
+    last_modified: 2026-06-18T00:00:00Z
+usage_window: { from: 2026-06-01T00:00:00Z, to: 2026-06-30T00:00:00Z }
+---
+
+# 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-15T00:00:00Z
+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') }}
+
+Gross profit by segment per the cost-allocation standard.[^cost-alloc]
+
+[^cost-alloc]: Cost allocation standard
+```