GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog
Producer report: six lifecycle keys in a live OKF exporter, and where each one should land
- Dominant language
- TypeScript
- Stars
- 9.2k
- Forks
- 782
- Avg merge
- 6h 36m
- Merged PRs (30d)
- 85
Description
Thanks for publishing OKF openly, and for the maintenance-signal threads (#158, #151, #148, and PR #159). Reading them changed what this issue is. We set out to propose a lifecycle vocabulary, found that most of it already has a home, and would rather file a producer report: what six optional frontmatter keys look like in an exporter that ships them today, and where we think each one belongs among the threads already open.
For context, we build *remember* at Lexenne. Our wiki compiler emits conformant OKF v0.1 bundles, and six optional keys ride along under the existing §4.1 extension allowance ("Producers MAY include any additional keys. Consumers SHOULD preserve unknown keys when round-tripping..."). All six ship with test coverage, and we can bring a sample bundle built from our own public docs.
| Key | What the producer promises by writing it | Where we think it belongs |
|---|---|---|
| `provenance` | how the item came to exist: `observed` / `asserted` / `inferred` | no home yet, and it needs a new name |
| `trust_tier` | the producer's own vetting level, as an ordered vocabulary | #151 / #159, as the `reliability` object's `confidence` band |
| `valid_from` | opening bound of the window over which the item is asserted to hold | #159, beside `validity.valid_until` |
| `invalid_at` | closing bound of the same window | #159, same object |
| `supersedes` | the prior concept this one replaces | #148, per @K4uP's split and @inkxel carrying it there |
| `contested_by` | a concept that disputes this one, kept rather than silently dropped | #148, same typed edge |
Taking the routing one at a time.
**The cross-concept edge (#148 / #158).** @K4uP drew the line on #158: #151 owns the intra-concept question (competing claims about the same fact, graded by reliability), and #158/#148 own the cross-concept one (a typed `supersedes` / `contradicts` edge where one whole concept obsoletes another). @inkxel then carried the edge to #148. That split holds against our data, and our two edge keys are that edge. One thing from running it: the edge only pays for itself if the contested concept stays in the bundle. Drop it and a reader coming back weeks later cannot tell a question that was settled from one that was never asked. @ajdelaguila's `supersedes:` shape (Data Olympus, on #148) is close enough to ours that converging on one spelling is clearly better than shipping two.
**Reliability (#151 / #159).** `trust_tier` is our version of the graded axis. #159 already names it `confidence`, inside a `reliability` object with a maturity ladder and four honesty rules, which is further along than what we have. We would drop `trust_tier` and adopt that name.
**Validity (#159 / #97).** #159's object carries `validity.valid_until`. We carry both bounds. The opening bound earns its place when a fact is written before it takes effect: a policy dated forward, a price filed in advance. A consumer reading the bundle today needs to know the item is not live yet. Note the two clocks, because they are easy to collapse. #97's `timestamp` records when the record was written (transaction time). A validity window describes the interval over which the item is asserted to hold in the world (valid time). They are complementary, so deferring freshness to #97 does not crowd out a validity window living on the reliability object.
**Provenance (#140).** This is the key with no home, and it should not keep this name. @K4uP has already noted that "provenance" carries about three meanings across these threads. #140 uses it in the cryptographic sense: a signed manifest, SHA-256 per file, an Ed25519 envelope - proof that a bundle came from who it claims and has not been altered. Ours answers a different question: how a given item came to exist as an epistemic class. `observed` (a system saw it), `asserted` (a person or agent stated it), `inferred` (derived from other items). Integrity and epistemic origin compose without conflict, and a bundle can carry both. We would take `epistemic_origin`, or whatever a registry lands on, and leave `provenance` to #140.
That leaves the routing question itself. #158 proposes an `EXTENSIONS.md` registry for exactly this collision problem. PR #159 has already demonstrated the other pattern: a self-contained proposal doc (`okf/proposals/reliability.md`) written in SPEC voice, core spec untouched. Both look reasonable from where we sit and we have no preference between them. Whether the maintainers do is the thing we would like to know, because we would rather fold six definitions into whichever surface holds the integration view than open a seventh.
Concretely, what we are offering:
1. The epistemic-origin definition as the one new key, wherever it should live.
2. `supersedes` / `contested_by` folded into #148's typed-link convention, under whatever names #148 settles on.
3. `valid_from` and the transaction-time / valid-time note contributed to #159.
4. A fourth production instance to cross-check the surface against, alongside Throughline, signed-okf, and @K4uP's multi-version corpus.
Say where, and we will write it up.
Contributed under Apache 2.0, from the team building *remember* at Lexenne.
Contributor guide
Research direction
Start by reading the existing maintenance threads, especially #148, #151, #158, and #159, then compare the proposed registry in EXTENSIONS.md with okf/proposals/reliability.md. The contributor should confirm where the six keys belong, settle the new epistemic-origin name, and write the agreed definitions and integration guidance with the sample bundle and existing producer coverage.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100