@inixiative/signet 0.11.0 → 0.12.0

package/README.md

@@ -6,7 +6,7 @@ A **Signet** is Kingdom's only grant for using an integration. It names the reso
 
 This package is the one implementation of that protocol, shared by Kingdom (which verifies) and Archive, Foundry and Oracle (which present):
 
-- `contracts`: the wire schemas: keys, lenses, proposals, pairing requests, delivered credentials, `describe` and `execute`, and the conversation frames.
+- `contracts`: the wire schemas: keys, grants (operation picks, lens layers, terms), proposals, pairing requests, delivered credentials, `describe` and `execute`, and the conversation frames.
 - `proof`: create and verify DPoP proofs (ES256, nonce-bound, access-token-bound).
 - `files`: private 0600 JSON files for keys and credentials.
 - `client`:
@@ -26,7 +26,7 @@ const paired = await pairInstallation({
   terms: {
     name: 'Laptop Archive', lifecycle: 'ongoing', expiresAt: null, maxRequests: null, maxConcurrent: 4,
     owner: { ownerModel: 'Organization', organization: 'inixiative' },
-    resources: [{ resourceKind: 'archiveLibrary', operations: ['sessions.write'] }],
+    resources: [{ resourceKind: 'archiveLibrary', operations: { picks: ['sessions.write'] } }],
   },
   onReview: ({ review }) => console.log(`Approve in Kingdom: ${review}`),
   confirmOwner: async ({ ownerName }) => confirm(`Pair with ${ownerName}?`),
@@ -50,7 +50,7 @@ import { awaitSignet, enrollSignet, generateSignetKey, requestSignet, saveCollec
 await writePrivateJson(keyFile, generateSignetKey());
 const { requestId, reviewCode } = await requestSignet(kingdom, keyFile, apiToken, {
   name: 'Research agent', integrationId, lifecycle: 'ongoing', expiresAt: null, maxRequests: null, maxConcurrent: 1,
-  resources: [{ resourceId, operations: ['documents.read'] }],
+  resources: [{ resourceModel: 'IntegrationResource', integrationResourceId, operations: { picks: ['documents.read'] } }],
 });
 const collected = await awaitSignet(kingdom, keyFile, requestId); // or, for a granted Signet:
 // const collected = await enrollSignet(kingdom, keyFile, apiToken, { signetId, expectedRevision, name: 'Research agent' });
@@ -59,21 +59,37 @@ const signet = await SignetClient.fromFile(credentialFile);
 await signet.describe();
 ```
 
+## Grants
+
+A Signet revision grants one row per resource (`grantResourceSchema`), false polymorphic on `resourceModel`:
+
+- **`IntegrationResource`**: `full`, or `operations` (the resolved leaves; absent when `full`), `lens` (json-rules layers) and `terms` (per kind). `full` reaches everything the resource offers, now and as its catalog grows, capped live by the integration's baseline. It is a different axis from `Integration.full` / `Token.full`, which let a delegate act with its owner's whole authority.
+- **`Project`**: a Kingdom project the Signet may be used in. Nothing else: no `full`, operations, lens or terms.
+
+**Operation picks.** A provider's catalog is a flat list of dotted leaf keys per resource kind (`commits.read`, `events.pull_request.review_requested`). A party asks with `operationPickSchema`: `{ full: true }` or `{ picks }`, each pick a leaf or a prefix ending `.*` (`commits.*`, `events.pull_request.*`). `resolveOperationPicks(leaves, pick)` resolves picks to leaves once, when the grant is saved (a pick that reaches nothing throws `OperationPickError`, code `unknown_operation_pick`), so a later catalog addition reaches only `full` rows. `operationTree(leaves)` derives the nested tree a grant UI offers, every node with the pick that takes it. `narrowsOperations(inner, outer)`: a full `outer` contains everything, and a full `inner` under an `outer` that is not full is never a narrowing. `permitsOperation(scope, operation)` answers one operation; `scopeRefusal(scope, catalog, refusal)` runs a per-operation refusal over every catalog operation a row reaches (all of them when full, so re-run it when the catalog grows).
+
+**Lens.** A grant's lens is a chain of json-rules layers over the integration's base lens for the resource's model, which Kingdom's catalog holds as code under `provider:kind`. A root `where` filters rows; picks and omits trim the shape; no lens means the base. A party writes one layer (`lensLayerSchema`, a json-rules narrowing without its parent); Kingdom stores it as a `StoredLens` record (`storedLensLayerSchema`) under the base, an approver's layer under the request's, so every layer ANDs and an approver can only narrow. This package depends on json-rules for types only, and checks only a layer's envelope: Kingdom validates (`validateNarrowing`), composes (`composeLens`) and applies (`projectRows`) the layers. The base's id is `baseLensId(provider, kind)`. The refusals below read a `GrantLens`: the grant's own layers plus `projectLens` of the composed chain (`projectionFilters`, `projectionShows`). A `where` runs over a row: `repositoryCallRow(input)` (`{ sha }`) for a repository call, `threadRow(threadId)` (`{ id }`) for a thread.
+
+**Terms** are neither operations nor lens: how a holder takes part (`grantTermsSchema`, strict per kind; `grantTermsFitKind(kind, terms)`). Today only `threads` has terms.
+
+What a party asks for (`signetResourceSchema` by id, `requestedResourceSchema` by id or by kind) carries picks, its own lens layer and terms (a request has no kind, so Kingdom checks `grantTermsFitKind` once it resolves the resource); what a holder reads (`signetGrantSchema`) is the stored row plus the resource's `kind`.
+
 ## Declared operations
 
-An integration whose operations Kingdom executes generically declares them here, one module per resource kind: `threads.ts` for a Foundry's `threads` resource, `archive.ts` for an Archive's `archiveLibrary`, `github.ts` for a GitHub `repository` (reads by object id; its lens pins a grant to commits, and a pinned grant reaches no tree or blob, since reading a commit never reached its tree). Each declares its operation enum, display names, the input each operation takes, its lens schema and the lens's narrowing. `declaredOperationSchema` and `operationInputSchemas` join them (operation names are unique across contracts), `operationInputKeys(operation)` gives the `access/execute` keys an operation takes besides `resourceId` and `limit`, and `operationInputFromAccess(operation, input)` picks and parses exactly those. Kingdom's catalog, its input check and its dispatch read these, so a new operation is added here first.
+An integration whose operations Kingdom executes generically declares them here, one module per resource kind: `threads.ts` for a Foundry's `threads` resource, `archive.ts` for an Archive's `archiveLibrary`, `github.ts` for a GitHub `repository` (reads by object id). Each declares its operation enum, display names and the input each operation takes. `declaredOperationSchema` and `operationInputSchemas` join them (operation names are unique across contracts), `operationInputKeys(operation)` gives the `access/execute` keys an operation takes besides `resourceId` and `limit`, and `operationInputFromAccess(operation, input)` picks and parses exactly those. Kingdom's catalog, its input check and its dispatch read these, so a new operation is added here first.
 
-- **Archive** (`archiveLibrary`): `documents.read`, `documents.search`, `sessions.write`, `sessions.delete`. The lens is `{ documentIds?, fields? }` (`{}` reaches every document) and `narrowsArchiveLens` narrows it. `archiveSourceOperations` (`sessions.write`, `sessions.delete`) are a paired local Archive acting on its own sessions: Kingdom binds them to its `sourceId`, so their grant takes no lens. `archiveLensRefusal(operation, lens)` says why a grant can't carry a lens (search needs content over every document).
+- **Archive** (`archiveLibrary`): `documents.read`, `documents.search`, `sessions.write`, `sessions.delete`. `archiveSourceOperations` (`sessions.write`, `sessions.delete`) are a paired local Archive acting on its own sessions: Kingdom binds them to its `sourceId`, so their grant takes no lens. `archiveLensRefusal(operation, lens)` says why a grant can't carry its lens (search needs content over every document: no `where`, `content` shown), and `archiveGrantRefusal(scope, lens)` checks a whole row.
+- **GitHub** (`repository`): `commits.read`, `trees.read`, `blobs.read`. A grant pins commits with a `where` over the call's `{ sha }`; reading a commit never reaches its tree, so `repositoryLensRefusal(operation, lens)` (and `repositoryGrantRefusal(scope, lens)` for a row) refuses trees and blobs under a pinned grant.
 
 ## Agent conversations
 
 A conversation wraps a host Foundry's main thread (Kingdom `docs/AGENT-CONVERSATIONS.md`, Foundry `docs/reference/CONVERSATIONS.md`). A member is a Signet on the host Foundry's one `threads` resource; Kingdom admits each call and relays it over the host's Installation socket, and stores no conversation or message.
 
-- **Lens.** `signetLensSchema` is a union of strict shapes, `archiveLensSchema | threadsLensSchema`, because a resource grant names its resource by id with no kind. `resourceLensSchema(kind)` gives the shape a kind takes; Kingdom checks every grant with it against the kind it stores. A threads lens is `{ threads, view: 'own' | 'thread', delivery: 'note' | 'turn', outbound: 'review' | 'auto' }`, the terms defaulting to the narrowest value. `threads` is a selector, a union on `form`: v1 builds `{ form: 'ids', ids }` (1–100 thread ids); `withMember` and `tag` are named for standing Signets and fail to parse everywhere until a release adds them, so a new form never widens access silently. `narrowsSignetLens` is the rule for approving someone else's request: a subset of ids, `own` < `thread`, `note` < `turn`, `review` < `auto`.
-- **Join requests** may name a resource by kind: `requestSignet` takes `{ resourceKind: 'threads', operations, lens }`, and Kingdom resolves it before review.
-- **Per-entry reads.** `installationInquiries`, `installationSignets`, the socket snapshot and `describe` read each entry on its own. An entry this package can't read is dropped and listed in `dropped`, and the rest is kept. Inside a Signet, resources are read one by one: a resource with a lens this package can't read (a selector form from a newer Kingdom, a lens that doesn't fit its resource's kind) is dropped, and the Signet stays, so an installation never loses a held Signet, or mistakes a member for revoked, over one resource. The snapshot carries `hostedSignets` (members of this Foundry's conversations) and `hostedSignetRequests` (join requests aimed at its integrations); held Signets carry their `resources`.
-- **Host.** `InstallationSocket` takes `threads`, one handler per operation (`thread.read`, `thread.prompt`, `thread.floor`, `prompt.resolve`, `thread.subscribe`), answering `threadResult(...)` or `threadRefused(code)`. A frame with an unknown selector is refused `unknown_selector` before any handler runs. `thread.subscribe` answers with the member's view and the `journalSeq` it was taken at, and the subscription starts there: `appendThread(subscriptionId, entry)` holds entries pushed meanwhile and never sends one twice. Each append carries a dense per-subscription `seq` (a filtered view skips journal entries, so `journalSeq` can't reveal loss); an entry that can't be sent still spends its `seq`, so Kingdom sees the gap and the member resyncs. A subscription ends on `thread.unsubscribe`, when Kingdom stops re-asserting its lease (`thread.lease`; dropped 90 s after the last one, so one late 45 s sweep is survived), or when the socket drops.
-- **Member.** An outside agent holds its live views with `SignetSocket`: it authenticates as its Signet's presentation (`authenticateSignet`, a proof bound to `POST /api/v1/access/signetSocket` with `ath`), renews it before the five-minute token expires (`renewPresentation`), and opens one `accessThread` stream per thread: a snapshot, then appends, with Kingdom's `seq`/`resync` rules. Frames are handled in order, one open is in flight per stream, and Kingdom's close carries the reason: after a revision the stream reopens under the new lens, while the host is offline it retries with backoff, when the presentation lapsed the socket re-presents and reopens, and on revocation or expiry it ends (`onClosed`). Posts are separate `execute` calls (`thread.prompt`), each admitted and metered. A Foundry holding a conversation Signet opens the same streams over its Installation socket (`threadStreams`, `openThread`).
+- **Terms.** A member's `threads` terms (`threadsTermsSchema`) are `{ view: 'own' | 'thread', delivery: 'note' | 'turn', outbound: 'review' | 'auto', floor: { mayTake } }`, each defaulting to its narrowest value (`threadsTerms(terms)` reads them so). Which threads a member reaches is the grant's lens (a `where` over the thread's `id`), which Kingdom applies at admission. `narrowsThreadsTerms` is the rule for approving someone else's request: `own` < `thread`, `note` < `turn`, `review` < `auto`, `floor.mayTake` only where asked. Kingdom relays the terms on every frame (`terms`).
+- **Join requests** may name a resource by kind: `requestSignet` takes `{ resourceKind: 'threads', operations, lens, terms }`, and Kingdom resolves it before review.
+- **Per-entry reads.** `installationInquiries`, `installationSignets`, the socket snapshot and `describe` read each entry on its own. An entry this package can't read is dropped and listed in `dropped`, and the rest is kept. Inside a Signet, resources are read one by one: a resource this package can't read (a term from a newer Kingdom, terms that don't fit its resource's kind) is dropped, and the Signet stays, so an installation never loses a held Signet, or mistakes a member for revoked, over one resource. The snapshot carries `hostedSignets` (members of this Foundry's conversations) and `hostedSignetRequests` (join requests aimed at its integrations); held Signets carry their `resources`.
+- **Host.** `InstallationSocket` takes `threads`, one handler per operation (`thread.read`, `thread.prompt`, `thread.floor`, `prompt.resolve`, `thread.subscribe`), answering `threadResult(...)` or `threadRefused(code)`. A frame this package can't read is refused `invalid_request` before any handler runs. `thread.subscribe` answers with the member's view and the `journalSeq` it was taken at, and the subscription starts there: `appendThread(subscriptionId, entry)` holds entries pushed meanwhile and never sends one twice. Each append carries a dense per-subscription `seq` (a filtered view skips journal entries, so `journalSeq` can't reveal loss); an entry that can't be sent still spends its `seq`, so Kingdom sees the gap and the member resyncs. A subscription ends on `thread.unsubscribe`, when Kingdom stops re-asserting its lease (`thread.lease`; dropped 90 s after the last one, so one late 45 s sweep is survived), or when the socket drops.
+- **Member.** An outside agent holds its live views with `SignetSocket`: it authenticates as its Signet's presentation (`authenticateSignet`, a proof bound to `POST /api/v1/access/signetSocket` with `ath`), renews it before the five-minute token expires (`renewPresentation`), and opens one `accessThread` stream per thread: a snapshot, then appends, with Kingdom's `seq`/`resync` rules. Frames are handled in order, one open is in flight per stream, and Kingdom's close carries the reason: after a revision the stream reopens under the new revision, while the host is offline it retries with backoff, when the presentation lapsed the socket re-presents and reopens, and on revocation or expiry it ends (`onClosed`). Posts are separate `execute` calls (`thread.prompt`), each admitted and metered. A Foundry holding a conversation Signet opens the same streams over its Installation socket (`threadStreams`, `openThread`).
 
 ```ts
 import { SignetClient, SignetSocket } from '@inixiative/signet';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inixiative/signet",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "Present Kingdom Signets: the wire contracts, DPoP proofs, device pairing and a renewing client shared by Kingdom, Archive, Foundry and Oracle.",
   "type": "module",
   "main": "src/index.ts",
@@ -35,7 +35,8 @@
   "devDependencies": {
     "@asteasolutions/zod-to-openapi": "^9.1.0",
     "@biomejs/biome": "2.5.2",
-    "@inixiative/config": "^0.5.170",
+    "@inixiative/config": "^0.5.174",
+    "@inixiative/json-rules": "^3.16.0",
     "@types/bun": "1.4.4",
     "lefthook": "2.1.9",
     "typescript": "6.0.3",
@@ -53,6 +54,7 @@
     "access": "public"
   },
   "peerDependencies": {
-    "zod": "^4.3.6"
+    "zod": "^4.3.6",
+    "@inixiative/json-rules": "^3.16.0"
   }
 }

package/src/archive.ts

@@ -1,10 +1,12 @@
 import { z } from 'zod';
+import { type GrantLens, projectionFilters, projectionShows } from './lens';
+import { type OperationScope, scopeRefusal } from './operations';
 
 /**
  * Archive libraries (Kingdom `docs/kingdom.md`, Archive `docs/KINGDOM.md`). A hosted Archive is an
  * integration with one `archiveLibrary` resource. Kingdom admits each call through a Signet and runs
- * it against that Archive with the integration's credential. The Archive server never sees the lens,
- * so Kingdom applies it.
+ * it against that Archive with the integration's credential. The Archive server never sees the lens
+ * (json-rules layers over the library's base lens), so Kingdom applies it.
  */
 export const archiveLibraryResourceKind = 'archiveLibrary';
 
@@ -13,20 +15,6 @@ export const archiveDocumentIdSchema = z.string().regex(/^[a-f0-9]{64}$/);
 export const archiveFieldSchema = z.enum(['id', 'title', 'content', 'tags', 'createdAt']);
 export type ArchiveField = z.infer<typeof archiveFieldSchema>;
 
-/** Which documents and fields of an `archiveLibrary` a grant reaches; `{}` reaches all of them. */
-export const archiveLensSchema = z.strictObject({
-  documentIds: z.array(archiveDocumentIdSchema).max(1000).optional(),
-  fields: z.array(archiveFieldSchema).max(6).optional(),
-});
-export type ArchiveLens = z.infer<typeof archiveLensSchema>;
-
-const subset = <T>(granted: T[] | undefined, requested: T[] | undefined) =>
-  !requested || (granted !== undefined && granted.every((item) => requested.includes(item)));
-
-/** `granted` reaches no document or field `requested` doesn't. */
-export const narrowsArchiveLens = (granted: ArchiveLens, requested: ArchiveLens): boolean =>
-  subset(granted.documentIds, requested.documentIds) && subset(granted.fields, requested.fields);
-
 /** The operations an `archiveLibrary` resource carries. */
 export const archiveOperationSchema = z.enum([
   'documents.read',
@@ -90,14 +78,20 @@ export const archiveInputSchemas = {
   'sessions.delete': z.strictObject({ documentId: archiveDocumentIdSchema }),
 } as const satisfies Record<ArchiveOperation, z.ZodObject>;
 
-/** Why a grant of `operation` can't carry `lens`, or null when it can. */
-export const archiveLensRefusal = (operation: ArchiveOperation, lens: ArchiveLens) => {
-  if (isArchiveSourceOperation(operation) && Object.keys(lens).length > 0)
-    return 'Writing or deleting sessions takes no lens';
+/** Why a grant of `operation` can't carry `lens`, or null when it can. No layers is the base. */
+export const archiveLensRefusal = (operation: ArchiveOperation, lens: GrantLens) => {
+  if (lens.layers.length === 0) return null;
+  if (isArchiveSourceOperation(operation)) return 'Writing or deleting sessions takes no lens';
   if (
     operation === 'documents.search' &&
-    (lens.documentIds || (lens.fields && !lens.fields.includes('content')))
+    (projectionFilters(lens.projection) || !projectionShows(lens.projection, 'content'))
   )
     return 'Search needs a lens that shows content and is not limited to chosen documents';
   return null;
 };
+
+/** `archiveLensRefusal` over every operation a grant row reaches, `full` meaning all of them. */
+export const archiveGrantRefusal = (scope: OperationScope, lens: GrantLens) =>
+  scopeRefusal(scope, archiveOperationSchema.options, (operation) =>
+    archiveLensRefusal(operation, lens),
+  );

package/src/client.ts

@@ -409,7 +409,7 @@ export const enrollSignet = async (
 
 /**
  * The Signets held by this installation's integrations, and those issued on them (`hostedSignets`).
- * Read per entry: a Signet whose lens this package can't read is dropped and listed in `dropped`.
+ * Read per entry: a Signet whose grants this package can't read is dropped and listed in `dropped`.
  */
 export const installationSignets = (
   url: string,
@@ -610,7 +610,7 @@ export class SignetClient {
       { signal, timeoutMs: options.timeoutMs },
     );
   }
-  /** Read per entry: a resource whose lens this package can't read is dropped, listed in `dropped`. */
+  /** Read per entry: a resource whose lens or terms this package can't read is dropped, listed in `dropped`. */
   async describe(options: SignetRequestOptions = {}) {
     return parseSignetDescription(
       await this.post('describe', { signetId: this.signetId }, undefined, options),

package/src/contracts.ts

@@ -3,41 +3,33 @@ import {
   archiveDocumentIdSchema,
   archiveFieldSchema,
   archiveInputSchemas,
-  archiveLensSchema,
-  archiveLibraryResourceKind,
   archiveOperationSchema,
-  narrowsArchiveLens,
 } from './archive';
+import { githubInputSchemas, githubOperationSchema, gitObjectIdSchema } from './github';
 import {
-  eventsInputSchemas,
-  eventsLensSchema,
-  eventsOperationSchema,
-  eventsResourceKind,
-  narrowsEventsLens,
-} from './events';
-import {
-  githubInputSchemas,
-  githubOperationSchema,
-  gitObjectIdSchema,
-  narrowsRepositoryLens,
-  repositoryLensSchema,
-  repositoryResourceKind,
-} from './github';
+  grantTermsFitKind,
+  grantTermsSchema,
+  requestedResourceSchema,
+  type SignetGrant,
+  signetGrantSchema,
+  signetResourceSchema,
+} from './grants';
+import { storedLensLayersSchema } from './lens';
 import {
   foundryIdSchema,
-  narrowsThreadsLens,
   threadFloorActionSchema,
   threadIdSchema,
   threadInputSchemas,
   threadOperationSchema,
-  threadsLensSchema,
-  threadsResourceKind,
   threadTextLimit,
 } from './threads';
 
 export * from './archive';
 export * from './events';
 export * from './github';
+export * from './grants';
+export * from './lens';
+export * from './operations';
 export * from './threads';
 
 const token43 = /^[A-Za-z0-9_-]{43}$/;
@@ -88,83 +80,12 @@ export const signetKeySchema = publicClientKeySchema.extend({
 export type PublicClientKey = z.infer<typeof publicClientKeySchema>;
 export type SignetKey = z.infer<typeof signetKeySchema>;
 
-/** Every other resource kind takes no lens. */
-export const emptyLensSchema = z.strictObject({});
-
-/**
- * A grant's lens. `signetResourceSchema` names a resource by id with no `kind`, so the contract can
- * only hold a union of the strict shapes; which shape a grant may carry depends on its resource's
- * kind, and Kingdom checks that with `resourceLensSchema` against the kind it stores (review R9).
- * `{}` parses as the empty Archive lens: "no lens", valid for every kind but `threads`.
- */
-export const signetLensSchema = z.union([
-  archiveLensSchema,
-  threadsLensSchema,
-  repositoryLensSchema,
-  eventsLensSchema,
-]);
-export type SignetLens = z.infer<typeof signetLensSchema>;
-
-/** The lens shape a resource of `kind` takes. */
-export const resourceLensSchema = (kind: string) =>
-  kind === archiveLibraryResourceKind
-    ? archiveLensSchema
-    : kind === threadsResourceKind
-      ? threadsLensSchema
-      : kind === repositoryResourceKind
-        ? repositoryLensSchema
-        : kind === eventsResourceKind
-          ? eventsLensSchema
-          : emptyLensSchema;
-
-/**
- * `granted` reaches nothing `requested` doesn't, for lenses of the same resource. Approving someone
- * else's request may only narrow; an owner revising their own grant may widen (review U3). A lens of
- * another shape than the request's is refused.
- */
-export const narrowsSignetLens = (granted: SignetLens, requested: SignetLens): boolean => {
-  if ('threads' in granted || 'threads' in requested)
-    return 'threads' in granted && 'threads' in requested && narrowsThreadsLens(granted, requested);
-  const isEvents = (lens: SignetLens) => 'where' in lens || 'select' in lens || 'name' in lens;
-  if (isEvents(granted) || isEvents(requested)) {
-    const eventsGranted = eventsLensSchema.safeParse(granted);
-    const eventsRequested = eventsLensSchema.safeParse(requested);
-    return (
-      eventsGranted.success &&
-      eventsRequested.success &&
-      narrowsEventsLens(eventsGranted.data, eventsRequested.data)
-    );
-  }
-  if ('commits' in granted || 'commits' in requested) {
-    const repositoryGranted = repositoryLensSchema.safeParse(granted);
-    const repositoryRequested = repositoryLensSchema.safeParse(requested);
-    return (
-      repositoryGranted.success &&
-      repositoryRequested.success &&
-      narrowsRepositoryLens(repositoryGranted.data, repositoryRequested.data)
-    );
-  }
-  const archiveGranted = archiveLensSchema.safeParse(granted);
-  const archiveRequested = archiveLensSchema.safeParse(requested);
-  return (
-    archiveGranted.success &&
-    archiveRequested.success &&
-    narrowsArchiveLens(archiveGranted.data, archiveRequested.data)
-  );
-};
-
-export const signetResourceSchema = z.strictObject({
-  resourceId: z.uuid(),
-  operations: z.array(z.string().min(1).max(80)).min(1).max(100),
-  lens: signetLensSchema.default({}),
-});
 export const signetRecipientSchema = z.discriminatedUnion('recipientModel', [
   z.strictObject({ recipientModel: z.literal('User'), userId: z.uuid() }),
   z.strictObject({ recipientModel: z.literal('Integration'), integrationId: z.uuid() }),
 ]);
 export const signetLifecycleSchema = z.enum(['request', 'task', 'ongoing']);
 export type SignetRecipient = z.infer<typeof signetRecipientSchema>;
-export type SignetResource = z.infer<typeof signetResourceSchema>;
 
 export const signetEnrollmentSchema = z.strictObject({
   signetId: z.uuid(),
@@ -206,18 +127,6 @@ const signetTerms = {
 /** A local Foundry, Archive or Oracle known to Kingdom by its key. */
 export const installationKindSchema = z.enum(['foundry', 'archive', 'oracle']);
 export type InstallationKind = z.infer<typeof installationKindSchema>;
-/**
- * A resource asked for by kind, and optionally name, when the asker does not know its id: an
- * Installation registering, or a party asking to join a Foundry's `threads` (one per Foundry, so the
- * integration id names it). Kingdom resolves it to the resource's id before anyone reviews it.
- */
-export const requestedResourceKindSchema = z.strictObject({
-  resourceKind: z.string().min(1).max(80),
-  resourceName: z.string().trim().min(1).max(120).optional(),
-  operations: z.array(z.string().min(1).max(80)).min(1).max(100),
-  lens: signetLensSchema.default({}),
-});
-export const requestedResourceSchema = z.union([signetResourceSchema, requestedResourceKindSchema]);
 /** What a party asks for on an integration: resources by id or by kind (review R8). */
 export const signetProposalSchema = z.strictObject({
   ...signetTerms,
@@ -260,7 +169,6 @@ export const signetRequestResponseSchema = z.object({
 export type SignetProposal = z.infer<typeof signetProposalSchema>;
 export type RegistrationTerms = z.infer<typeof registrationTermsSchema>;
 export type RequestedOwner = z.infer<typeof requestedOwnerSchema>;
-export type RequestedResource = z.input<typeof requestedResourceSchema>;
 export type RegistrationRequest = z.input<typeof registrationRequestSchema>;
 export type SignetRequest = z.infer<typeof signetRequestSchema>;
 export type SignetRequestResponse = z.infer<typeof signetRequestResponseSchema>;
@@ -330,18 +238,7 @@ export const installationInquiriesResponseSchema = z.object({
 });
 export const inquiryReferenceSchema = z.strictObject({ inquiryId: z.uuid() });
 
-/** One resource a Signet reaches, with its stored kind, so its lens can be checked against it. */
-export const signetGrantSchema = z.object({
-  resourceId: z.uuid(),
-  kind: z.string().min(1).max(80),
-  operations: z.array(z.string().min(1).max(80)),
-  lens: signetLensSchema,
-});
-export type SignetGrant = z.infer<typeof signetGrantSchema>;
 const grantsSchema = z.array(signetGrantSchema);
-/** Whether a grant's lens is the shape its resource's kind takes. */
-export const grantLensFitsKind = (grant: Pick<SignetGrant, 'kind' | 'lens'>) =>
-  resourceLensSchema(grant.kind).safeParse(grant.lens).success;
 
 /** Who a Signet is issued to. Recipients run broad (2026-10-18); Kingdom widens issuing in K0. */
 export const signetRecipientModelSchema = z.enum([
@@ -403,7 +300,8 @@ export const signetDescriptionResourceSchema = z.object({
   name: z.string(),
   kind: z.string(),
   integrationId: z.uuid(),
-  lens: signetLensSchema,
+  lens: storedLensLayersSchema.optional(),
+  terms: grantTermsSchema.optional(),
 });
 export const signetDescriptionSchema = z.object({
   signetId: z.uuid(),
@@ -498,14 +396,12 @@ export const declaredOperationSchema = z.enum([
   ...threadOperationSchema.options,
   ...archiveOperationSchema.options,
   ...githubOperationSchema.options,
-  ...eventsOperationSchema.options,
 ]);
 export type DeclaredOperation = z.infer<typeof declaredOperationSchema>;
 export const operationInputSchemas = {
   ...threadInputSchemas,
   ...archiveInputSchemas,
   ...githubInputSchemas,
-  ...eventsInputSchemas,
 } as const satisfies Record<DeclaredOperation, z.ZodObject>;
 export type OperationInput<O extends DeclaredOperation> = z.infer<
   (typeof operationInputSchemas)[O]
@@ -552,7 +448,7 @@ const entryId = (value: unknown) => {
 };
 /**
  * Parse each entry on its own and drop the ones that don't parse. A Kingdom ahead of this package
- * (a selector form it doesn't know, a new field shape) then costs only those entries: never the
+ * (a term it doesn't know, a new field shape) then costs only those entries: never the
  * Installation's other grants or its own held Signets. A missing list reads as empty, reported.
  */
 export function parseEntries<T>(
@@ -577,12 +473,14 @@ export function parseEntries<T>(
   });
 }
 
-const lensFits = (grant: Pick<SignetGrant, 'kind' | 'lens'>) =>
-  grantLensFitsKind(grant) ? null : `a ${grant.kind} resource carries a lens of another shape`;
+const termsFit = (grant: SignetGrant) =>
+  grant.resourceModel === 'Project' || grantTermsFitKind(grant.kind, grant.terms)
+    ? null
+    : `a ${grant.kind} resource carries terms of another kind`;
 
 /**
  * Signets read per entry, and their resources per entry inside them: a resource this package can't
- * read (a newer lens, a lens that doesn't fit its kind) is dropped and reported, and the Signet is
+ * read (a newer term, terms that don't fit its kind) is dropped and reported, and the Signet is
  * kept, so the Installation never loses a held Signet (or mistakes a member for revoked) over one
  * resource.
  */
@@ -602,7 +500,7 @@ function parseSignetsWithGrants<S extends z.ZodObject<{ resources: typeof grants
           entry.resources,
           signetGrantSchema,
           dropped,
-          lensFits,
+          termsFit,
         ),
       }) as z.infer<S>,
   );
@@ -654,7 +552,7 @@ export function parseInstallationSnapshot(value: unknown): InstallationSnapshot
 
 export type ParsedSignetDescription = SignetDescription & { dropped: DroppedEntry[] };
 
-/** `access/describe`, per entry: a resource whose lens doesn't parse, or doesn't fit its kind, is dropped. */
+/** `access/describe`, per entry: a resource whose lens or terms don't parse, or don't fit its kind, is dropped. */
 export function parseSignetDescription(value: unknown): ParsedSignetDescription {
   const dropped: DroppedEntry[] = [];
   const record = z
@@ -668,7 +566,10 @@ export function parseSignetDescription(value: unknown): ParsedSignetDescription
       operation.resources,
       signetDescriptionResourceSchema,
       dropped,
-      (resource) => (grantLensFitsKind(resource) ? null : 'lens does not fit the resource kind'),
+      (resource) =>
+        grantTermsFitKind(resource.kind, resource.terms)
+          ? null
+          : 'terms do not fit the resource kind',
     ),
   }));
   return { ...signetDescriptionSchema.parse({ ...record, operations }), dropped };

package/src/events.ts

@@ -2,14 +2,11 @@ import { z } from 'zod';
 
 /**
  * Integration events (Kingdom `docs/INTEGRATION-EVENTS.md`, Aron 2026-11-01). An integration that
- * receives its provider's events (a webhook endpoint, or a poll where the provider has none) has one
- * `events` resource: its feed. A Signet grant of `events.subscribe` on it is a **channel**: a
- * json-rules `where` over the event and an optional `select` of what the holder receives. The holder
- * reads its Signet to see the channels it has, and subscribes to any or all of them; Kingdom matches
- * each arriving event against the integration's channels the same way. Live only: a channel nobody
- * holds open drops the event.
+ * receives its provider's events (a webhook endpoint, or a poll where the provider has none) fans
+ * each one out to the Signet grants that reach it: the event kinds are operation leaves under
+ * `events.`, picked like any other, and the grant's lens layers filter and trim the event. Live
+ * only: a channel nobody holds open drops the event.
  */
-export const eventsResourceKind = 'events';
 
 /** A provider identity an event names: a login or handle, and the provider's id when it gives one. */
 export const eventPartySchema = z.strictObject({
@@ -49,7 +46,21 @@ export const integrationEventSchema = z.strictObject({
 });
 export type IntegrationEvent = z.infer<typeof integrationEventSchema>;
 
-/** The envelope fields a channel may `select`. */
+/**
+ * The integration itself as a model: account-level events that belong to no repository, channel or
+ * team (a person's mentions, review requests and assignments from GitHub's notifications, a Slack DM)
+ * hang off it. Each integration that receives events has one `account` resource.
+ */
+export const accountResourceKind = 'account';
+
+/**
+ * An event kind's operation leaf: `events.<provider event>.<action>`, mirroring the provider's own
+ * taxonomy (Aron, 2026-11-01). A grant picks it like any operation, a prefix (`events.pull_request.*`)
+ * or everything (`full`).
+ */
+export const eventOperationKey = (type: IntegrationEvent['type']) => `events.${type}`;
+
+/** The envelope's fields, for the base event lens a provider's catalog declares over the event model. */
 export const integrationEventFieldSchema = z.enum([
   'eventId',
   'integrationId',
@@ -68,71 +79,22 @@ export const integrationEventFieldSchema = z.enum([
 export type IntegrationEventField = z.infer<typeof integrationEventFieldSchema>;
 
 /**
- * A channel: `where` is a json-rules condition over the event (Kingdom validates it with
- * json-rules against `integrationEventSchema`'s fields; this package only carries it as JSON), a
- * positive condition, so a grant without one matches every event. `select` is the overlay
- * restricting what the holder receives; `eventId` and `type` are always sent. The `where` may test
- * fields the `select` leaves out. `name` is what the holder sees when it reads its channels.
+ * One append on a channel's stream. `eventId` and `type` ride outside the projected body, so the
+ * grant's lens trimming can never drop what a holder needs to dedupe and route; `event` is the
+ * envelope as the grant's lens layers project it (json-rules `projectRows`).
  */
-export const eventsLensSchema = z.strictObject({
-  name: z.string().min(1).max(80).optional(),
-  where: z.record(z.string(), z.unknown()).optional(),
-  select: z.array(integrationEventFieldSchema).min(1).max(20).optional(),
+export const accessEventsAppendSchema = z.strictObject({
+  eventId: integrationEventSchema.shape.eventId,
+  type: integrationEventSchema.shape.type,
+  event: z.record(z.string(), z.unknown()),
 });
-export type EventsLens = z.infer<typeof eventsLensSchema>;
-
-/** What a holder receives from a channel: the event, cut to the channel's `select`. */
-export const selectedEventSchema = integrationEventSchema
-  .partial()
-  .required({ eventId: true, type: true });
-export type SelectedEvent = z.infer<typeof selectedEventSchema>;
-
-/** The event as a channel's `select` lets it through; `eventId` and `type` always go. */
-export const selectEvent = (lens: EventsLens, event: IntegrationEvent): SelectedEvent => {
-  if (!lens.select) return event;
-  const fields = new Set<IntegrationEventField>([...lens.select, 'eventId', 'type']);
-  return Object.fromEntries(
-    Object.entries(event).filter(([key]) => fields.has(key as IntegrationEventField)),
-  ) as SelectedEvent;
-};
-
-const sameJson = (a: unknown, b: unknown) => JSON.stringify(a) === JSON.stringify(b);
-
-/**
- * `granted` reaches nothing `requested` doesn't. Conservative and structural, since this package
- * doesn't evaluate json-rules: the granted `where` is the requested one, or `{all: [...]}` holding
- * it (the requested condition plus more); the granted `select` is within the requested one.
- */
-export const narrowsEventsLens = (granted: EventsLens, requested: EventsLens) => {
-  const whereNarrows =
-    requested.where === undefined ||
-    sameJson(granted.where, requested.where) ||
-    (typeof granted.where === 'object' &&
-      granted.where !== null &&
-      !Array.isArray(granted.where) &&
-      Array.isArray((granted.where as { all?: unknown }).all) &&
-      (granted.where as { all: unknown[] }).all.some((part) => sameJson(part, requested.where)));
-  const selectNarrows =
-    !requested.select ||
-    (!!granted.select && granted.select.every((field) => requested.select?.includes(field)));
-  return whereNarrows && selectNarrows;
-};
-
-/** The operation an `events` resource carries: hold a channel open. It takes no input. */
-export const eventsOperationSchema = z.enum(['events.subscribe']);
-export type EventsOperation = z.infer<typeof eventsOperationSchema>;
-export const eventsOperationNames: Record<EventsOperation, string> = {
-  'events.subscribe': "Receive this integration's events as they happen, filtered by the channel",
-};
-export const eventsInputSchemas = {
-  'events.subscribe': z.strictObject({}),
-} as const satisfies Record<EventsOperation, z.ZodObject>;
+export type AccessEventsAppend = z.infer<typeof accessEventsAppendSchema>;
 
 /**
  * A channel's live stream is a Kingdom data stream, like a thread's (`accessThread`): its family is
  * the operationId of Kingdom's snapshot route `GET /api/v1/access/events/{resourceId}/{signetId}`,
  * and its name that route's channel key (path fields sorted). The snapshot is always empty: there is
- * no backlog. Each append's payload is one `SelectedEvent`.
+ * no backlog. Each append's payload is one `AccessEventsAppend`.
  */
 export const accessEventsStreamFamily = 'accessEvents';
 export const accessEventsStreamName = (stream: { signetId: string; resourceId: string }) =>

package/src/github.ts

@@ -1,31 +1,19 @@
 import { z } from 'zod';
+import { type GrantLens, projectionFilters } from './lens';
+import { type OperationScope, scopeRefusal } from './operations';
 
 /**
  * GitHub repositories (Kingdom `docs/OPERATOR-ACCESS.md` §9). A GitHub integration is one GitHub
  * account; each repository it reaches is a `repository` resource, named `owner/name`. Kingdom admits
  * each call through a Signet and reads the repository with the integration's credential, so the
- * lens is applied by Kingdom.
+ * lens is applied by Kingdom. A grant pins commits with a `where` over the call's `{ sha }`; reading a
+ * commit never reaches its tree, so a pinned grant reaches no tree or blob.
  */
 export const repositoryResourceKind = 'repository';
 
 /** A Git object id: an immutable commit, tree or blob SHA-1. */
 export const gitObjectIdSchema = z.string().regex(/^[a-f0-9]{40}$/);
 
-/**
- * Which commits of a `repository` a grant reaches; `{}` reaches the whole repository. A grant pinned
- * to commits reads only those commits: reading a commit never reaches its tree, so a pinned grant
- * reaches no tree or blob.
- */
-export const repositoryLensSchema = z.strictObject({
-  commits: z.array(gitObjectIdSchema).min(1).max(1000).optional(),
-});
-export type RepositoryLens = z.infer<typeof repositoryLensSchema>;
-
-/** `granted` reaches no commit `requested` doesn't. */
-export const narrowsRepositoryLens = (granted: RepositoryLens, requested: RepositoryLens) =>
-  !requested.commits ||
-  (granted.commits?.every((commit) => requested.commits?.includes(commit)) ?? false);
-
 /** The operations a `repository` resource carries. */
 export const githubOperationSchema = z.enum(['commits.read', 'trees.read', 'blobs.read']);
 export type GithubOperation = z.infer<typeof githubOperationSchema>;
@@ -47,18 +35,16 @@ export const githubInputSchemas = {
 } as const satisfies Record<GithubOperation, z.ZodObject>;
 
 /** Why a grant of `operation` can't carry `lens`, or null when it can. */
-export const repositoryLensRefusal = (operation: GithubOperation, lens: RepositoryLens) =>
-  lens.commits && operation !== 'commits.read'
+export const repositoryLensRefusal = (operation: GithubOperation, lens: GrantLens) =>
+  projectionFilters(lens.projection) && operation !== 'commits.read'
     ? 'A grant pinned to commits reads only those commits; trees and blobs need an unpinned grant'
     : null;
 
-/** Whether every lens a call is admitted under reaches `objectId` for `operation`. */
-export const lensesSelectObject = (
-  lenses: RepositoryLens[],
-  operation: GithubOperation,
-  objectId: string,
-) =>
-  lenses.every(
-    (lens) =>
-      !repositoryLensRefusal(operation, lens) && (!lens.commits || lens.commits.includes(objectId)),
+/** `repositoryLensRefusal` over every operation a grant row reaches, `full` meaning all of them. */
+export const repositoryGrantRefusal = (scope: OperationScope, lens: GrantLens) =>
+  scopeRefusal(scope, githubOperationSchema.options, (operation) =>
+    repositoryLensRefusal(operation, lens),
   );
+
+/** The row a repository grant's `where` is evaluated over: the call's object, as `sha`. */
+export const repositoryCallRow = (input: { objectId: string }) => ({ sha: input.objectId });

package/src/grants.ts

@@ -0,0 +1,127 @@
+import { z } from 'zod';
+import { lensLayerSchema, storedLensLayersSchema } from './lens';
+import { operationPickSchema, resolvedOperationsSchema } from './operations';
+import { threadsResourceKind, threadsTermsSchema } from './threads';
+
+/**
+ * What a Signet revision grants, one row per resource (Aron, 2026-11-01). False polymorphism on
+ * `resourceModel`: an `IntegrationResource` row carries its operations (`full`, or the leaves its
+ * picks resolved to), its lens layers and its per-kind terms; a `Project` row names a Kingdom project
+ * the Signet may be used in, and nothing else. Artifacts may join later.
+ */
+export const grantResourceModelSchema = z.enum(['IntegrationResource', 'Project']);
+export type GrantResourceModel = z.infer<typeof grantResourceModelSchema>;
+
+/**
+ * Per-kind terms that are neither operations nor lens: how a holder takes part. Strict per kind. A
+ * request names its resource by id with no kind, so Kingdom checks `grantTermsFitKind` once it has
+ * resolved the resource.
+ */
+export const grantTermsSchema = z.strictObject({ threads: threadsTermsSchema.optional() });
+export type GrantTerms = z.infer<typeof grantTermsSchema>;
+
+/** The resource kind each terms key belongs to. */
+const termsKinds = { threads: threadsResourceKind } as const satisfies Record<
+  keyof GrantTerms,
+  string
+>;
+/** Whether `terms` only carry keys that belong to a resource of `kind`. */
+export const grantTermsFitKind = (kind: string, terms: GrantTerms | undefined) =>
+  Object.entries(terms ?? {}).every(
+    ([key, value]) => value === undefined || termsKinds[key as keyof GrantTerms] === kind,
+  );
+
+/** A threads grant's terms, every one it leaves out at its narrowest. */
+export const threadsTerms = (terms: z.input<typeof grantTermsSchema> | undefined) =>
+  threadsTermsSchema.parse(terms?.threads ?? {});
+
+const integrationResourceShape = {
+  resourceModel: z.literal('IntegrationResource'),
+  integrationResourceId: z.uuid(),
+  /** Everything the resource offers, now and as its catalog grows, capped live by the baseline. */
+  full: z.boolean(),
+  /** The resolved leaves; absent when `full`. */
+  operations: resolvedOperationsSchema.optional(),
+  /** The layers under the base lens; absent means the base. */
+  lens: storedLensLayersSchema.optional(),
+  terms: grantTermsSchema.optional(),
+};
+const fullOrOperations = (
+  row: { full: boolean; operations?: string[] },
+  context: z.RefinementCtx,
+) => {
+  if (row.full && row.operations !== undefined)
+    context.addIssue({
+      code: 'custom',
+      path: ['operations'],
+      message: 'A full grant lists no operations',
+    });
+  if (!row.full && row.operations === undefined)
+    context.addIssue({
+      code: 'custom',
+      path: ['operations'],
+      message: 'A grant that is not full lists its operations',
+    });
+};
+
+export const integrationResourceGrantSchema = z
+  .strictObject(integrationResourceShape)
+  .superRefine(fullOrOperations);
+export const projectGrantSchema = z.strictObject({
+  resourceModel: z.literal('Project'),
+  projectId: z.uuid(),
+});
+/** One stored grant row, as Kingdom writes it on a revision. */
+export const grantResourceSchema = z.discriminatedUnion('resourceModel', [
+  integrationResourceGrantSchema,
+  projectGrantSchema,
+]);
+export type GrantResource = z.infer<typeof grantResourceSchema>;
+export type IntegrationResourceGrant = z.infer<typeof integrationResourceGrantSchema>;
+export type ProjectGrant = z.infer<typeof projectGrantSchema>;
+
+/**
+ * A grant as a holder reads it: the stored row, plus the resource's `kind` so its terms can be read.
+ * Read paths stay loose (a field a newer Kingdom adds is dropped, not fatal).
+ */
+export const signetGrantSchema = z.discriminatedUnion('resourceModel', [
+  z
+    .object({ ...integrationResourceShape, kind: z.string().min(1).max(80) })
+    .superRefine(fullOrOperations),
+  z.object(projectGrantSchema.shape),
+]);
+export type SignetGrant = z.infer<typeof signetGrantSchema>;
+
+/**
+ * What a party asks for on one resource: `full` or picks, its own lens layer (Kingdom assigns the
+ * layer its id and chains it under the base, or under the request when an approver writes it), and
+ * terms.
+ */
+const askedOperations = {
+  operations: operationPickSchema,
+  lens: lensLayerSchema.optional(),
+  terms: grantTermsSchema.optional(),
+};
+/** A resource asked for by id. */
+export const signetResourceSchema = z.discriminatedUnion('resourceModel', [
+  z.strictObject({
+    resourceModel: z.literal('IntegrationResource'),
+    integrationResourceId: z.uuid(),
+    ...askedOperations,
+  }),
+  projectGrantSchema,
+]);
+export type SignetResource = z.infer<typeof signetResourceSchema>;
+
+/**
+ * A resource asked for by kind, and optionally name, when the asker does not know its id: an
+ * Installation registering, or a party asking to join a Foundry's `threads` (one per Foundry, so the
+ * integration id names it). Kingdom resolves it to the resource's id before anyone reviews it.
+ */
+export const requestedResourceKindSchema = z.strictObject({
+  resourceKind: z.string().min(1).max(80),
+  resourceName: z.string().trim().min(1).max(120).optional(),
+  ...askedOperations,
+});
+export const requestedResourceSchema = z.union([signetResourceSchema, requestedResourceKindSchema]);
+export type RequestedResource = z.input<typeof requestedResourceSchema>;

package/src/installationSocket.ts

@@ -14,7 +14,7 @@ import {
   type ThreadRefusal,
   type ThreadRequestFrame,
   type ThreadSubscribeFrame,
-  type ThreadsLens,
+  type ThreadsTerms,
   threadAppendFrameSchema,
   threadLeaseFrameSchema,
   threadRefused,
@@ -37,7 +37,7 @@ export type ThreadSubscription = {
   threadId: string;
   acceptedRevision: number;
   member: ThreadSubscribeFrame['member'];
-  lens: ThreadsLens;
+  terms: ThreadsTerms;
 };
 /** `overflow`: too many entries arrived while the snapshot was taken; the subscribe is refused and retried. */
 export type ThreadSubscriptionEnd = 'unsubscribed' | 'lease' | 'disconnected' | 'overflow';
@@ -106,18 +106,6 @@ const maxHeldEntries = 1_000;
 /** WebSocket.OPEN, read from the spec rather than whichever WebSocket class was passed. */
 const OPEN = 1;
 
-/** An unknown selector form (or a `within`, which no v1 form fills) is refused as `unknown_selector`. */
-const unknownSelector = (frame: Record<string, unknown>) => {
-  const threads = z
-    .object({ threads: z.object({ form: z.string(), within: z.unknown().optional() }).loose() })
-    .loose()
-    .safeParse(frame.lens);
-  return (
-    threads.success &&
-    (threads.data.threads.form !== 'ids' || threads.data.threads.within !== undefined)
-  );
-};
-
 /**
  * Kingdom's live line to an Installation. It proves the installation's key, then receives a
  * snapshot of its inquiries and Signets on connect and again whenever one changes. While the
@@ -349,11 +337,7 @@ export class InstallationSocket {
     const frame = threadRequestFrameSchema.safeParse(raw);
     if (!frame.success) {
       this.options.onError?.(frame.error);
-      return this.refuse(
-        socket,
-        requestId.data,
-        unknownSelector(raw) ? 'unknown_selector' : 'invalid_request',
-      );
+      return this.refuse(socket, requestId.data, 'invalid_request');
     }
     const host = this.options.threads;
     if (!host) return this.refuse(socket, requestId.data, 'failed', 'This host serves no threads');
@@ -401,11 +385,7 @@ export class InstallationSocket {
     const parsed = threadSubscribeFrameSchema.safeParse(raw);
     if (!parsed.success) {
       this.options.onError?.(parsed.error);
-      return this.refuse(
-        socket,
-        requestId.data,
-        unknownSelector(raw) ? 'unknown_selector' : 'invalid_request',
-      );
+      return this.refuse(socket, requestId.data, 'invalid_request');
     }
     const host = this.options.threads;
     if (!host) return this.refuse(socket, requestId.data, 'failed', 'This host serves no threads');
@@ -416,7 +396,7 @@ export class InstallationSocket {
       threadId: frame.threadId,
       acceptedRevision: frame.acceptedRevision,
       member: frame.member,
-      lens: frame.lens,
+      terms: frame.terms,
       leaseUntil: Date.now() + this.leaseMs(),
       sentSeq: null,
       seq: 0,

package/src/lens.ts

@@ -0,0 +1,54 @@
+import type { LensNarrowing, PathProjection, StoredLens } from '@inixiative/json-rules';
+import { z } from 'zod';
+
+/**
+ * A grant's lens is a chain of json-rules layers over the integration's base lens for the resource's
+ * model (Aron, 2026-11-01: "root `where` filters; otherwise a narrowing of shape (pick/omit)… No
+ * lens means the default"). The base lives in Kingdom's catalog, as code, under the id
+ * `provider:kind`; a grant row stores only the layers under it, as json-rules `StoredLens` records,
+ * the request's first and an approver's after it. Every layer ANDs with the ones above it, so an
+ * approver can only narrow. This package carries the layers; Kingdom validates, composes
+ * (`composeLens`) and applies them (`projectRows`).
+ */
+
+/** One layer as a party writes it: a json-rules narrowing without its parent. */
+export type LensLayer = Omit<LensNarrowing, 'parent'>;
+/** One stored layer: its id and the ids it composes under, the base first. Never a base itself. */
+export type StoredLensLayer = Pick<StoredLens, 'id' | 'parents'> & LensLayer;
+
+const narrowingPart = {
+  root: z.record(z.string(), z.unknown()).optional(),
+  mapDefaults: z.record(z.string(), z.unknown()).optional(),
+};
+const layerId = z.string().min(1).max(200);
+
+/**
+ * A layer's envelope only: what is inside `root` and `mapDefaults` is json-rules', unchecked here.
+ * Kingdom runs `validateNarrowing` (or `composeLens`) on it before reading it as a `LensLayer`.
+ */
+export const lensLayerSchema = z.strictObject(narrowingPart);
+export const storedLensLayerSchema = z.strictObject({
+  id: layerId,
+  parents: z.array(layerId).min(1).max(20),
+  ...narrowingPart,
+});
+export const storedLensLayersSchema = z.array(storedLensLayerSchema).max(20);
+
+/** The id of an integration's base lens for a resource kind's model, in Kingdom's catalog. */
+export const baseLensId = (provider: string, kind: string) => `${provider}:${kind}`;
+
+/**
+ * A grant's lens as the refusals read it: its own layers (empty = the base) and json-rules'
+ * `projectLens` of the composed chain, which Kingdom computes after validating the layers.
+ */
+export type GrantLens = { layers: readonly LensLayer[]; projection: PathProjection };
+
+/** Whether the composed lens filters rows anywhere: a `where` on the anchor or along a relation. */
+export const projectionFilters = (projection: PathProjection) =>
+  Object.values(projection).some((visit) => visit.whereClauses.length > 0);
+
+/** Whether the composed lens shows `field` of its anchor model (the visit keyed by the model alone). */
+export const projectionShows = (projection: PathProjection, field: string) =>
+  Object.entries(projection).some(
+    ([path, visit]) => !path.includes('.') && Object.hasOwn(visit.fields, field),
+  );

package/src/operations.ts

@@ -0,0 +1,144 @@
+import { z } from 'zod';
+
+/**
+ * Operation picks (Aron, 2026-11-01: "any model whole, or whatever group of operations whole, or
+ * to any degree of specificity"). A provider's catalog is a flat list of
+ * dotted leaf keys per resource kind (`commits.read`, `events.pull_request.review_requested`); the
+ * nesting is carried by the dots and derived, never stored. A grant asks for `full` (everything the
+ * resource has now and later, capped live by the integration's baseline) or picks at any node: a
+ * leaf, or a prefix ending `.*` that takes every leaf under it. Picks resolve to leaves once, when
+ * the grant is saved, so a later catalog addition reaches only `full` rows.
+ */
+const segment = '[A-Za-z0-9_-]+';
+export const operationKeySchema = z
+  .string()
+  .max(80)
+  .regex(new RegExp(`^${segment}(?:\\.${segment})*$`));
+/** A leaf key, or a prefix ending `.*`. */
+export const operationPickKeySchema = z
+  .string()
+  .max(82)
+  .regex(new RegExp(`^${segment}(?:\\.${segment})*(?:\\.\\*)?$`));
+
+export const operationPickSchema = z.union([
+  z.strictObject({ full: z.literal(true) }),
+  z.strictObject({ picks: z.array(operationPickKeySchema).min(1).max(100) }),
+]);
+export type OperationPick = z.infer<typeof operationPickSchema>;
+
+/** Resolved leaves, as a grant row stores them. Picks of nested events may run past a hundred. */
+export const resolvedOperationsSchema = z
+  .array(operationKeySchema)
+  .min(1)
+  .max(1000)
+  .refine((operations) => new Set(operations).size === operations.length, {
+    message: 'Each operation is listed once',
+  });
+
+/**
+ * What a row reaches: `full`, or the leaves its picks resolved to. Not the same axis as
+ * `Integration.full` / `Token.full`, which make a delegate act with its owner's whole authority.
+ */
+export type OperationScope = { full: true } | { full: false; operations: string[] };
+
+export class OperationPickError extends Error {
+  readonly code = 'unknown_operation_pick';
+  constructor(readonly pick: string) {
+    super(`No operation matches the pick '${pick}'`);
+    this.name = 'OperationPickError';
+  }
+}
+
+const prefixOf = (pick: string) => (pick.endsWith('.*') ? pick.slice(0, -1) : null);
+
+/**
+ * The leaves `picks` reach among `leaves` (a resource kind's catalog keys), in catalog order. A
+ * pick that reaches nothing throws `OperationPickError`, so a typo never saves an empty grant.
+ */
+export const resolveOperationPicks = (
+  leaves: readonly string[],
+  pick: OperationPick,
+): OperationScope => {
+  if ('full' in pick) return { full: true };
+  const chosen = new Set<string>();
+  for (const key of pick.picks) {
+    const prefix = prefixOf(key);
+    const reached = prefix
+      ? leaves.filter((leaf) => leaf.startsWith(prefix))
+      : leaves.filter((leaf) => leaf === key);
+    if (reached.length === 0) throw new OperationPickError(key);
+    for (const leaf of reached) chosen.add(leaf);
+  }
+  return { full: false, operations: leaves.filter((leaf) => chosen.has(leaf)) };
+};
+
+/**
+ * One node of a resource kind's operation tree. `key` is its dotted path, `pick` the pick that
+ * takes it (the key for a leaf, `key.*` for a group), and a key that is both a leaf and a prefix is
+ * a leaf with children (its own pick then takes only the leaf).
+ */
+export type OperationNode = {
+  key: string;
+  segment: string;
+  leaf: boolean;
+  pick: string;
+  /** `key.*`, whenever the node has children (a leaf that is also a prefix included). */
+  groupPick?: string;
+  children: OperationNode[];
+};
+
+/** The tree the dotted keys describe, in catalog order: what a grant UI offers to pick from. */
+export const operationTree = (leaves: readonly string[]): OperationNode[] => {
+  const roots: OperationNode[] = [];
+  for (const leaf of leaves) {
+    let level = roots;
+    const parts = leaf.split('.');
+    parts.forEach((part, depth) => {
+      const key = parts.slice(0, depth + 1).join('.');
+      let node = level.find((candidate) => candidate.key === key);
+      if (!node) {
+        node = { key, segment: part, leaf: false, pick: `${key}.*`, children: [] };
+        level.push(node);
+      }
+      if (depth < parts.length - 1) node.groupPick = `${key}.*`;
+      if (depth === parts.length - 1) {
+        node.leaf = true;
+        node.pick = key;
+      }
+      level = node.children;
+    });
+  }
+  return roots;
+};
+
+/**
+ * `inner` reaches no operation `outer` doesn't. A full `outer` contains everything; a full `inner`
+ * under an `outer` that is not full is never a narrowing, even when `outer` lists every leaf today,
+ * because `full` keeps growing with the catalog.
+ */
+export const narrowsOperations = (inner: OperationScope, outer: OperationScope): boolean => {
+  if (outer.full) return true;
+  if (inner.full) return false;
+  return inner.operations.every((operation) => permitsOperation(outer, operation));
+};
+
+/** Whether `scope` reaches `operation`. */
+export const permitsOperation = (scope: OperationScope, operation: string) =>
+  scope.full || scope.operations.includes(operation);
+
+/**
+ * The first refusal among the catalog operations `scope` reaches, or null. A full scope is checked
+ * against the whole catalog, so run it again whenever the catalog grows.
+ */
+export const scopeRefusal = <O extends string>(
+  scope: OperationScope,
+  catalog: readonly O[],
+  refusal: (operation: O) => string | null,
+) => {
+  for (const operation of catalog) {
+    if (!permitsOperation(scope, operation)) continue;
+    const reason = refusal(operation);
+    if (reason) return reason;
+  }
+  return null;
+};

package/src/threads.ts

@@ -16,32 +16,6 @@ export const threadsResourceKind = 'threads';
 export const foundryIdSchema = z.string().regex(/^[A-Za-z0-9_-]{1,128}$/);
 export const threadIdSchema = foundryIdSchema;
 
-/**
- * Selector forms that are named for standing Signets (design §9) but not built. Each fails to parse
- * on every party until a release adds it to `threadSelectorSchema`, so a new form only takes effect
- * once every side has upgraded and never widens access silently.
- *
- * - `{ form: 'withMember' }`: threads opened with the grant's recipient;
- * - `{ form: 'tag', tag }`: threads carrying a tag.
- */
-export const unbuiltThreadSelectorForms = ['withMember', 'tag'] as const;
-
-/**
- * `ids` takes `within` only once a non-`ids` form exists: `within` will hold exactly one such form
- * (never a selector, so it can't nest), set only by approving a request for a selector form narrowed
- * to `ids` (the grant is then `ids ∩ within`), and approval may never drop or widen it. Until then
- * the strict object refuses `within` like any unknown key: structural, and representable in Kingdom's
- * OpenAPI (a `z.never()` placeholder is not).
- */
-export const idsThreadSelectorSchema = z.strictObject({
-  form: z.literal('ids'),
-  ids: z.array(threadIdSchema).min(1).max(100),
-});
-
-/** Which threads a grant reaches. A discriminated union on `form`; v1 builds only `ids`. */
-export const threadSelectorSchema = z.discriminatedUnion('form', [idsThreadSelectorSchema]);
-export type ThreadSelector = z.infer<typeof threadSelectorSchema>;
-
 /** `own`: the member's posts and the sends addressed to it. `thread`: the main thread's messages. */
 export const threadViewSchema = z.enum(['own', 'thread']);
 /** `note`: rides the owner's next turn. `turn`: queued as a turn of its own. */
@@ -57,38 +31,20 @@ export const threadOutboundSchema = z.enum(['review', 'auto']);
 export const threadFloorTermsSchema = z.strictObject({ mayTake: z.boolean().default(false) });
 
 /**
- * A member's terms on a `threads` resource. Every term but the selector defaults to its narrowest
- * value, so a lens that omits one can only be more careful. `threads` has no default: `{}` is never a
- * valid threads lens, which is why a grant's preset must fill it (review R9).
+ * A member's terms on a `threads` resource: how it takes part, not which threads it reaches (that
+ * is the grant's lens, a json-rules filter Kingdom applies at admission). Every term defaults to its
+ * narrowest value, so terms that omit one can only be more careful.
  */
-export const threadsLensSchema = z.strictObject({
-  threads: threadSelectorSchema,
+export const threadsTermsSchema = z.strictObject({
   view: threadViewSchema.default('own'),
   delivery: threadDeliverySchema.default('note'),
   outbound: threadOutboundSchema.default('review'),
   floor: threadFloorTermsSchema.default({ mayTake: false }),
 });
-export type ThreadsLens = z.infer<typeof threadsLensSchema>;
-
-/** Is `threadId` inside the selector? For `ids`, Kingdom answers this at admission. */
-export const selectsThread = (selector: ThreadSelector, threadId: string): boolean => {
-  switch (selector.form) {
-    case 'ids':
-      return selector.ids.includes(threadId);
-  }
-};
+export type ThreadsTerms = z.infer<typeof threadsTermsSchema>;
 
-/** `granted` reaches no thread `requested` doesn't: per form, as the design's narrowing rules say. */
-export const narrowsThreadSelector = (
-  granted: ThreadSelector,
-  requested: ThreadSelector,
-): boolean => {
-  switch (requested.form) {
-    case 'ids':
-      // When `within` exists, it must also be kept as asked: never dropped, never added.
-      return granted.form === 'ids' && granted.ids.every((id) => requested.ids.includes(id));
-  }
-};
+/** The row a threads grant's `where` is evaluated over at admission: the thread, by `id`. */
+export const threadRow = (threadId: string) => ({ id: threadIdSchema.parse(threadId) });
 
 const order = <T extends string>(values: readonly T[]) => {
   const rank = (value: T) => values.indexOf(value);
@@ -100,10 +56,10 @@ const narrowsOutbound = order(threadOutboundSchema.options);
 
 /**
  * Approving a request may only narrow (`own` < `thread`, `note` < `turn`, `review` < `auto`, and
- * `floor.mayTake` only where it was asked for).
+ * `floor.mayTake` only where it was asked for). Terms don't compose like lens layers, so approval
+ * checks them here.
  */
-export const narrowsThreadsLens = (granted: ThreadsLens, requested: ThreadsLens): boolean =>
-  narrowsThreadSelector(granted.threads, requested.threads) &&
+export const narrowsThreadsTerms = (granted: ThreadsTerms, requested: ThreadsTerms): boolean =>
   narrowsView(granted.view, requested.view) &&
   narrowsDelivery(granted.delivery, requested.delivery) &&
   narrowsOutbound(granted.outbound, requested.outbound) &&
@@ -130,7 +86,7 @@ export const threadOperationNames: Record<ThreadOperation, string> = {
  * `local` is a member on the host's own machine (its own Codex, a local Herald), joined in-process
  * with no Signet; `signet` is one that reaches the host through Kingdom.
  * Read paths (entries, views) use plain objects, so a host that adds a field never costs an older
- * member its entries; lenses and request frames stay strict.
+ * member its entries; terms and request frames stay strict.
  */
 export const conversationMemberSchema = z.object({
   kind: z.enum(['owner', 'local', 'signet']),
@@ -263,14 +219,13 @@ export type ThreadResult<O extends keyof typeof threadResultSchemas> = z.infer<
 >;
 
 /**
- * Why the host refused. The first six are the design's refusals, which Kingdom records as
+ * Why the host refused. The first five are the design's refusals, which Kingdom records as
  * `AccessExecution.status = 'denied'` with this `errorCode` (§5.4). `invalid_request` is a frame the
  * host could not read for any other reason, and `failed` an error inside the host; Kingdom records
  * both as `failed`.
  */
 export const threadRefusalSchema = z.enum([
   'unknown_thread',
-  'unknown_selector',
   'thread_closed',
   'floor_denied',
   'not_invited',
@@ -281,7 +236,6 @@ export const threadRefusalSchema = z.enum([
 export type ThreadRefusal = z.infer<typeof threadRefusalSchema>;
 export const threadDeniedRefusals = [
   'unknown_thread',
-  'unknown_selector',
   'thread_closed',
   'floor_denied',
   'not_invited',
@@ -298,10 +252,11 @@ const relayed = {
   /** The `AccessExecution` id: one per admitted call, and the id the answer carries back. */
   requestId: z.uuid(),
   signetId: z.uuid(),
-  /** The Signet revision Kingdom admitted the call under; the lens is that revision's. */
+  /** The Signet revision Kingdom admitted the call under; the terms are that revision's. */
   acceptedRevision: z.number().int().min(1),
   member: threadMemberSchema,
-  lens: threadsLensSchema,
+  /** The member's terms, as Kingdom admitted the call under them. */
+  terms: threadsTermsSchema,
 };
 const requestFrame = <O extends ThreadOperation>(operation: O) =>
   z.strictObject({
@@ -453,7 +408,7 @@ export const accessThreadCloseReasonSchema = z.enum([
   /** The member closed it. */
   'left',
   'revoked',
-  /** Any revision closes the stream; the member reopens under the new lens. */
+  /** Any revision closes the stream; the member reopens under the new revision. */
   'revised',
   'enrollmentRevoked',
   'expired',