Commit 2730691

the recorder (`_echoes_own_credential`). An own-credential answer is stored under a cache key that

folds in the org (or the connection, on an `own_account` endpoint), so another team never computes

the hash that would find it; only an endpoint-level `cache.sharing: public` declaration puts such an

answer on the public key.

masking uses, failing closed when they cannot be rendered). The same guard, the same

`origin_org_id` provenance and the same sharing rules apply to a metered call on an org

credential that rides treg's pay-per-use OAuth app (`billed_oauth`): the token is the team's.

**A hit on an own key is free**: nothing is reserved or settled (non-negotiable 1), the response

carries the same `X-Treg-Cache: hit` headers and the audit row `cached: true`, and `cache_price`

reports `free`. Own-key observations train the timer and the result state of THEIR key like any

other.

Storage and sharing are two dimensions, judged separately. The licence (`cache.mode`) says

whether bytes may be KEPT; `archive.sharing(entry, own_credential=…)` says whose question the

answer is — "the vendor allows storage" never implies "the answer does not depend on who asked".

| Who asked | `scope: any_account` | `scope: own_account` |

|---|---|---|

| treg's platform key | `public` | (never: own_account needs the caller's credential) |

| the org's own credential (API key or OAuth token, metered or not) | `org`, or `public` only where the ENDPOINT declares `cache.sharing: public` | `connection` |

Sharing is enforced by the KEY, not by a filter at read time: `scope_tags` folds `org:<id>` or

`conn:<id>:<sorted bound secret ids>` into `cache_key`, so a private history is under a hash

nobody else ever computes, its timer learns only from its own answers, and two Google accounts

in one team never see each other's sites (a reconnect is a new secret, hence a fresh history).

A caller consults its scopes most specific first — connection only; org then public (a

platform-key fetch may serve an own-key caller free); public only — and records under the first.

`ArchiveKey.scope` (`org` | `conn` | NULL = public, including every key from before the column)

lets the refresh worker skip private keys: treg's platform key cannot re-ask them. History from

before this rule (platform and billed-OAuth rows, all NULL-origin, all on public keys) is

therefore never served to an `own_account` caller and only ever served on `any_account`

endpoints, where it was a public question anyway. `cache_sharing` and, on a hit, `cache_scope`

are on `tool_called`.

`cache.sharing: public` is an ENDPOINT declaration (`_validate_cache` refuses it on a provider

header, refuses any value but `public`, and refuses it on an `own_account` endpoint): it says

this endpoint's answer is identical whoever asks — treg's own service OAuth reading public data

is the intended case — and it is judged per endpoint, never inherited from a provider's licence.

Nothing in the shipped catalog declares it yet.

Who an own-credential answer may serve is decided by the KEY it is recorded under ("Sharing").

`archive.cache_key(method, endpoint_id, upstream_url, body, headers, scope="")` → sha256 over the

canonical request: uppercased method, catalog endpoint id (a provider URL reshuffle starts a fresh

history), sorted query pairs, canonical-JSON body hash (raw hash for non-JSON), plus only `Accept`

and `Accept-Language` from the caller's headers, plus the sharing scope when the answer is not

public (`org:<id>` / `conn:<id>:<secret ids>`, see "Sharing"; a public key hashes as it always did). Auth/cookies/tracing/encodings never enter the key —

one team's fetch may warm another team's hit; an own-credential answer's reach is its KEY's

scope (`ArchiveKey.scope`, migration 0034, and the scope folded into the hash — see "Sharing"),

the snapshot's `origin_org_id` (same migration) is provenance, and `ArchiveKeyOrg` (same

migration) is the per-(org, key) "has paid for this question" mark that prices a repeat hit —

see "Pricing a hit".

fetched the answer; NULL = treg's platform key, every row before it - provenance), nullable

`ArchiveKey.scope` (`org` | `conn` for a key private to an org or a connection; NULL = public,

every key before it - the sharing scope is also folded into the key hash) and the

`ArchiveKeyOrg` table, unique on `(org_id, key_hash)`: which teams have paid for which archived

question, written by archive inside the metered settle transaction and read by lookup to price

a repeat hit. See [archive](archive.md#own-key-answers-2026-09-14),

[sharing](archive.md#sharing-whose-question-is-it-2026-09-15) and

[pricing a hit](archive.md#pricing-a-hit-2026-09-14).

# "org" | "conn" for a key private to an org or a connection; NULL = public (every key

# before this revision, whose hash carries no scope).

op.add_column("archivekey", sa.Column("scope", sa.String(), nullable=True))

op.drop_column("archivekey", "scope")

# Whose question this is (archive.sharing): the org's own credential - an API key or

# an OAuth token, metered or not - confines the answer to the org, or to the

# connection on an `own_account` endpoint, by keying it. The tags are the scopes this

# caller may READ, most specific first; the first is where its answer is recorded.

own_credential = mk is not None and mk.tier in ("tool", "credential")

cache_scopes = archive.scope_tags(

archive.sharing(catalog_store.load().by_id.get(mk.endpoint_id) if mk else None,

own_credential=own_credential),

caller.org_id, secrets) if mk is not None else [""]

if mk is not None:

cache_diagnostics["cache_sharing"] = archive.sharing(

catalog_store.load().by_id.get(mk.endpoint_id), own_credential=own_credential)

org_id=caller.org_id, price_repeat=mk.metered, scopes=cache_scopes)

# `own_credential` here means billed OAuth: the org's token, treg's bill.

origin_org_id=caller.org_id if own_credential else None,

scope=cache_scopes[0])

observation=body_observation, origin_org_id=caller.org_id,

scope=cache_scopes[0])