Skip to content

feat: administer explicit experience sharing grants - #9

Merged
fabbrik merged 5 commits into
mainfrom
feat/3-1-sharing-grants
Sep 22, 2026
Merged

fabbrik merged 5 commits into
mainfrom
feat/3-1-sharing-grants

Conversation

@fabbrik

@fabbrik fabbrik commented Sep 22, 2026

Copy link
Copy Markdown
Owner

Summary

Story 3.1, first of Epic 3. Scope stops being all-or-nothing, without weakening it.

  • Administrator authority is explicit. A GrantAdministration the host constructs — never derived from an AuthorizationContext, a role string, or the requesting scope. Missing it is a typed Denied before any connection opens.
  • A grant names one record and one recipient scope, keeps the same tenant, application and project, carries a reason and an expiry, and is rejected if it is a no-op or crosses a boundary. The owner scope is copied from the record by INSERT ... SELECT, so a caller cannot assert who owns what.
  • Grant and audit event commit together, and the event insert's rowcount is asserted, so a grant can never commit unaudited. GetHistoryAsync exposes the trail through the port.
  • At most one active grant per recipient (unique partial index), so revoking the grant you know about genuinely ends that recipient's access.
  • Reads widen in SQL only. Get, text search and vector search match exact scope or an active grant — correlated on both halves, expiry evaluated with clock_timestamp() so a caller-held transaction cannot keep an expired grant alive. Writes, lifecycle commits, history and enumeration stay owner-only.
  • Borrowed experience is visible. The read that applied the predicate marks the record shared; Core and the injection provider keep strict scope equality for anything unmarked, the host's risk policy can deny on that flag alone, and the Historical Reference block tells the model the lesson came from another scope.
  • Degrades instead of breaking. A database without 0005, or a role with SELECT only on the records table, falls back to exact-scope reads and notifies the host — degrading only ever narrows a read.

Review

Three reviewers raised 31 findings; 28 fixed, 3 deferred with named owners. Blind Hunter could not construct a case where the predicate admits a record the grant does not name. The serious ones: grants initially broke un-migrated and least-privilege deployments; relaxing the Core and MAF scope guards had weakened defence in depth (fixed by the marker above); an audit event could silently not be written; and revoking one of several overlapping grants did not end access.

Not in this PR

Tamper-evident grant state (a direct UPDATE can still clear a revocation) is assigned to 3.2, which owns the same question for lifecycle events. Grant purge, a lifetime ceiling and read auditing are assigned to 4.5 and to a new story 3.5.

Test plan

  • dotnet build --configuration Release: 0 warnings, 0 errors
  • dotnet test --configuration Release: 746 of 746 pass (Postgres 165, Core 394, MAF 90, Vectors 45)
  • Container tests per edge-case row, including create and revoke atomicity, expiry at the database clock, a tampered grant's owner scope still denied, the degraded-deployment path, and that a grant confers no write, no history and no enumeration
  • CI green

🤖 Generated with Claude Code

fabbrik and others added 5 commits September 18, 2026 21:17
Add ExperienceFinalizationService: one call that loads a completed captured
run, evaluates its own closed verification round, checks host authorization and
the host's storage decision, reflects, creates the record as Candidate, and
commits its initial lifecycle event to Validated or Quarantined. Record,
reflection and event IDs derive from the run, so a retry re-derives them and
converges instead of duplicating.

Required checks can now name the evaluator kind that may satisfy them, and Core
and Storage.Postgres each expose a service-registration extension. The MAF
adapter finalizes a fully captured run through the host's resolver.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Add IExperienceCandidateSource with a PostgreSQL implementation: scope, status
and confidence filtering plus a full-text match over a generated tsvector
column added by migration 0003. Core's ExperienceRetrievalService applies
expiry and environment eligibility, then ranks candidates on relevance,
confidence, recency, status and environment compatibility with configurable
validated weights, exposing every normalized component and effective weight.

Retrieval is bounded by a timeout that returns an empty result with a timeout
signal rather than throwing, caller cancellation stays distinct, and a capped
candidate pool is reported through Truncated.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Add IExperienceEmbeddingIndex and a domain-typed embedding generator port,
with a new AgentExperience.Storage.Postgres.Vectors package implementing them
over plain Npgsql and Pgvector. Embeddings are derived data: indexing runs
after the canonical commit, embeds only the sanitized retrieval summary of an
eligible record, and writes conditionally on the record's exact revision, so a
stale write is rejected and a deleted record is never recreated.

Retrieval gains a vector channel merged with the text channel under the same
eligibility, timeout and ceiling. A model or dimension mismatch, an
unavailable provider, or a vector-channel failure produces an explicit
flagged text-only result rather than an incompatible comparison.

The vectors package owns and applies its own schema, so a text-only
deployment never runs CREATE EXTENSION vector.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Add ExperienceContextProvider, a simple-tier AIContextProvider the host adds
to ChatClientAgentOptions.AIContextProviders. It retrieves ranked experience
before an invocation, re-checks every candidate against the same eligibility
rules retrieval applies, asks the host's injection decision, and injects a
delimited Historical Reference carrying source, confidence, applicability and
an evidence summary -- never raw payload content, never a cut record.

Limits drop whole records and record every omission. Retrieval that is empty,
times out or fails leaves the agent running normally. Labeling marks the
content untrusted; the authorization boundary is what denies an unauthorized
tool call, and a test proves it does when the model obeys injected text.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
Add IExperienceGrantStore and migration 0005: an administrator, with authority
the host supplies explicitly, grants one record to a recipient scope with a
reason and an expiry. The grant row and its audit event commit together, and a
unique partial index allows at most one active grant per recipient, so revoking
the grant an administrator knows about ends that recipient's access.

Reads widen in SQL only: get, text search and vector search match their exact
scope or an active grant, evaluated against the database clock. Writes,
lifecycle commits, history and enumeration stay owner-only. The read that
applied the predicate marks a record as shared, so Core and the injection
provider keep strict scope equality for everything else, the host's risk
policy can deny borrowed experience, and the model is told the lesson came
from another scope.

Deployments without the grants table, or with SELECT only on the record table,
degrade to exact-scope reads rather than failing.

Co-Authored-By: Claude Opus 5 (1M context) <[email protected]>
@fabbrik
fabbrik merged commit 62a327f into main Sep 22, 2026
1 check passed
@fabbrik
fabbrik deleted the feat/3-1-sharing-grants branch September 22, 2026 21:37
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant