GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

Provenance/trust is out of scope in v0.1, but `timestamp` is already a trust seam for multi-party bundles

Open
#47 2 comments 1 reaction 0 assignees View on GitHub
Dominant language
TypeScript
Stars
9.2k
Forks
782
Avg merge
6h 36m
Merged PRs (30d)
85

Description

First, thanks for shipping this. The markdown-plus-frontmatter-as-a-graph shape is the right substrate for portable knowledge, and "the value of a knowledge format comes from how many parties speak it, not from who owns it" is exactly right.

I want to raise the one place the v0.1 boundary feels load-bearing rather than deferrable. The spec closes by stating it defines no provenance, signing, authentication, or trust infrastructure, and that these are out of scope. That is a reasonable line for v0.1, but there is a concrete seam worth naming now, because it shapes what an extension would later need to look like.

The seam is `timestamp`. It is defined as the ISO datetime of the last meaningful change, and it is producer-set. For a single trusted author that is fine. For a bundle assembled from multiple producers and consumed by an agent that did not author it, `timestamp` is the field that decides which version of a fact is current, and it is chosen by whoever wrote the file. A field meant to establish recency is set by the party who benefits from asserting it. The same is true implicitly of authorship: nothing binds a concept to who actually wrote it, so a consumer merging two bundles cannot distinguish an enriched concept from a poisoned one.

I am not proposing to put trust in the core format. The minimally-opinionated, producer/consumer-separated design is the right call and I would not change it. The question is narrower: would the maintainers be open to a reserved extension namespace and a small set of conventions for an optional provenance/trust layer, so the parties who need it can speak it interoperably instead of each inventing their own incompatible frontmatter keys?

The shape such an extension would need, sketched in OKF's own spirit (extension frontmatter keys plus an out-of-band proof, no platform, account, or SDK required to read or verify):

- authorship binding: a concept carries a verifiable claim of who authored it, that the author cannot later repudiate and an impostor cannot forge.
- tamper-evidence: a changed concept is detectable against what was signed, not against a self-set timestamp.
- attribution that survives transport: the binding rides with the concept into bundles its author never assembled.
- earned recency or standing: the "which is current" decision can be backed by something a consumer can check, rather than a producer-asserted field.

None of this requires changing the conformance rules or the core fields. It would live as optional reserved keys plus a documented proof format, the same way the spec already invites extensions and asks consumers to preserve unknown keys. The reason to reserve the namespace now, even before designing the mechanism, is that the format being good is what makes the gap urgent: a format that gets adopted gets bundles from strangers, and bundles from strangers is precisely the case the core format puts out of scope.

Happy to help draft a concrete extension proposal if there is appetite. Mostly I wanted to put the timestamp-as-trust-seam observation on the record while the format is young, since it is cheaper to reserve space for provenance now than to retrofit it after producers have each picked their own keys.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.