GoogleCloudPlatform / GoogleCloudPlatform/knowledge-catalog

Producer report: access is the axis this tracker keeps circling — field notes from a wiki memory that enforces per-fragment read sets

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

Description

Thanks for keeping the spec deliberately small — and to everyone in #148 /
#151 / #158 / #159: reading those threads reshaped this issue the same way
they reshaped #182. I'll keep the lifecycle part short (it's in good hands)
and spend the space on an axis this tracker keeps circling without naming.

For context: I build [mwe-mcp](https://github.com/Fr4nZ82/mwe-mcp), an
open-source (AGPL, Rust) memory engine that serves persistent Markdown
wikis to AI agents over MCP. It has run in production since spring as a
multi-user memory: several people share one deployment, and every fact
carries its own read set — which is why I have field data on this axis at
its most demanding. The wikis are already markdown + YAML frontmatter, so
OKF is a near neighbor; I'm evaluating a conformant exporter.

## On lifecycle — brief, mostly a +1

Our facts carry both validity bounds, and production agrees with #182's
case for the opening bound (facts routinely land before they take effect).
One consumption-side datum I don't see stated in the threads yet: **expiry
should down-rank, not hide**. In our recall pipeline a fact whose window
has closed is still retrievable — "what was true in April?" stays
answerable — it just loses rank against live facts. If `validity` lands in
a proposal doc, one sentence of consumer guidance to that effect would
prevent the natural-but-wrong reading (expired ⇒ filter out). Deletion is
a separate, deliberate act.

Also a +1, with field data, to the finding on #148 that a superseded
concept must stay in the bundle: our superseded facts stay, window closed
— it's what makes dated queries answerable at all.

## The access axis

OKF v0.1 has a coherent implicit access model: **whoever holds the bundle
reads all of it**, and access control happens outside the format, by
controlling distribution. For many producers that is enough, and I'm not
here to argue it away. But look at what this tracker is already asking
for, separately:

- #77 wants an ignorefile — *things in the bundle an agent must not read*.
- #90 / #191 found that erasing a concept can itself disclose it, and
propose an erasure conformance profile.
- #58 asks for a trust & safety section.
- #96 / #189 introduce `audience` — as an advisory *routing* hint (what a
concept is *for*), which is a different thing, and the distinction is
exactly my point below.

Each of these is a fragment of the same underlying question: **who may
read what, and what must a conformant consumer do about it.** Goal 3
(exchange across organizations) makes it concrete: the moment a bundle
crosses a boundary and not everything should travel, producers today fork
the bundle per recipient — per-audience projections that the spec has no
name for. And #77 shows the single-holder case wants it too.

Three things we learned enforcing read sets in production:

1. **Access is per-fragment, not per-bundle — and not even per-concept.**
A single concept page routinely holds facts with different read sets
(the same person-page carries facts one reader may see and another must
not). Concept-level metadata was our first design too; it did not
survive contact with real use.

2. **We therefore never serve a page as one artifact.** Every read is a
per-reader *projection*: the same corpus, rendered with redaction for
that reader. The corpus is governed; the exchanged artifact is a
projection of it. This is the fork-per-recipient pattern from goal-3
exchange, made systematic.

3. **Access must never be advisory.** An access rule that travels as a
hint a consumer may ignore is worse than no rule: the producer believes
something is protected, and nothing enforces it. This is why
#96/#189's `audience` (routing orientation, fine as advisory) and
access must stay two words: confusing them puts real protection in the
advisory bucket.

What this could mean for OKF, in increasing order of ambition:

- **(a) Nothing normative.** Producers exchange per-recipient projections;
the spec stays silent. Works today, costs nothing — but two producers
will invent incompatible conventions, which is exactly the collision the
lifecycle threads exist to prevent, and #77/#90 keep arriving anyway.
- **(b) An optional concept-level `access:` key** (producer-defined
vocabulary, like `type`), plus one honesty rule in SPEC voice: *a
consumer that cannot enforce `access` MUST NOT re-serve or re-export the
concept.* That mirrors the honesty-rules pattern of #159, gives #77 its
ignore semantics as a special case, and keeps the key out of the
advisory bucket by construction.
- **(c) Fragment-level access grammar.** I'd argue **against** this ever
entering OKF: it's where engines like ours live, and the spec's
minimalism is right to refuse it. (b) is the sweet spot — enough shared
vocabulary that projections interoperate, no machinery.

## What I'm offering

1. Field data from a production instance that enforces per-fragment read
sets, to cross-check any proposal against — one more production
perspective alongside the lifecycle instances already in the threads.
2. A proposal doc in the #159 pattern (`okf/proposals/access.md`) if the
maintainers prefer that surface to an issue thread.
3. The exporter as an independent producer implementation once it lands —
emitting per-recipient projections, which is the (a) pattern whether or
not (b) happens.

Say where, and I'll write it up.

Contributor guide

Open the contributing guide

Research direction

Read the referenced discussions, especially #77, #90, #96, #159, and #189, to understand the existing access, erasure, audience, and proposal patterns. Review the suggested okf/proposals/access.md surface and clarify with maintainers whether they want a normative access key, producer projections only, or no specification change; done requires an agreed direction and proposal scope.

Written by the indexing model from the issue text.

Assessment

Tech stack
markdown, rust, yaml
Domain
documentation, security
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
25/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.