@plurnk/plurnk-schemes 1.3.12 → 1.5.0

package/SPEC.md

@@ -2,7 +2,7 @@
 
 Contract for `@plurnk/plurnk-schemes-*` sibling packages. Audience: implementer of a URI scheme handler. Consumer: [plurnk-service](https://github.com/plurnk/plurnk-service) (SPEC.md §3).
 
-## §1 Manifest {§manifest}
+## §manifest §1 Manifest
 
 ```json
 {
@@ -16,13 +16,12 @@ Class-level manifest (static field on the default export):
 ```ts
 import type { SchemeManifest } from "@plurnk/plurnk-schemes";
 
-class Known {
+class Notes {
     static manifest: SchemeManifest = {
-        name: "known",
+        name: "notes",
         channels: { body: "text/markdown", preview: "text/markdown" },
         defaultChannel: "body",
         category: "data",
-        scope: "workspace",
         writableBy: ["model", "client"],
         volatile: false,
         modelVisible: true,
@@ -35,47 +34,67 @@ class Known {
 |---|---|
 | `name` | Matches `package.json#plurnk.name`. Addressing/routing identity (the URI prefix). |
 | `channels` | `Record<channelName, mimetype>`. Channel names lowercase. Empty = dynamic per-call. |
-| `defaultChannel` | Channel name targeted when path has no `#fragment`. Empty when channels is empty. |
-| `category` | `"data"` (entry-bearing) \| `"logging"` (`log://` rows) \| `"control"` (addresses sister processes/runs, owns no entries — e.g. `worker://`). |
-| `scope` | `"workspace"` \| `"worker"` (grammar 0.67 `default_scope`; `worker` = per-worker scratch backing `worker://`). |
-| `writableBy` | Subset of `["model", "client", "system", "plugin"]`. Consumer returns 403 for outside-set writes. |
+| `defaultChannel` | Channel targeted when path has no `#fragment`. Dynamic-channel schemes may name it without fixing a mimetype; empty means no default. |
+| `category` | `"data"` (entry-bearing) \| `"logging"` (`log://` rows) \| `"control"` (addresses sister workers, owns no entries — e.g. `worker://`). |
+| `writableBy` | Subset of `["model", "client", "plurnk", "plugin"]`; empty declares an immutable scheme. Consumer returns 403 for outside-set writes. |
 | `volatile` | Boolean. |
 | `modelVisible` | Boolean. |
-| `folderScopes?` | `true` declares that a trailing slash on READ is a collection scope. Absent/false means `/` is ordinary resource syntax. Matcher bodies and explicit globs remain queries independently. |
-| `flags?` | Optional `SchemeFlagAffinity`. |
+| `folderScopes?` | `true` declares that a trailing slash on FIND is a collection scope. Absent/false means `/` is ordinary resource syntax. |
+| `flags?` | Optional exact `SchemeFlagAffinity`; see {§manifest-flag-affinity}. |
 | `example?` | The scheme's terse **hot-path** one-liner (e.g. `"READ(foo://thing/42)"`) — renders in the live catalogue every turn, so keep it to one canonical usage line. Omit → not advertised. Depth goes in `documentation`. |
-| `documentation?` | The **deep doc** (semantics / channels / edge cases). Consumer materializes it as a pull-able `worker://plurnk/docs/<name>.md` entry READ on demand; never hits the hot path. Mirrors `ExecInfo.documentation` (schemes#25). |
-| `glyph?` | Display icon (emoji / nerdfont). Omit → consumer renders the `name` (`glyph ?? name`). |
-| `foldedByDefault?` | Entries land FOLDED, off the ranked manifest surface (READable via address, not poured into the ranked view). For executor-output streams (`<tag>://`) — containment one level up (schemes#20/service#240). Absent/false → ranked/first-class. |
-| `storedScheme?` | Value persisted to `entries.scheme`, which may differ from the addressing `name`. Resolution: `storedScheme === undefined ? name : storedScheme`. Absent → defaults to `name` (additive; existing manifests unchanged). Explicit `null` → persists BARE (e.g. File: bare paths, `entries.scheme` NULL, routing name `"file"`). |
+| `documentation?` | The **deep doc** (semantics / channels / edge cases). Consumer materializes it as a pull-able `worker://plurnk/docs/<name>.md` entry READ on demand; never hits the hot path. Mirrors `ExecInfo.documentation`. |
+| §manifest-client-display `glyph?` | Non-empty opaque client presentation glyph. It is projected through {§client-display-capabilities}; omission delegates identity fallback to the client. It never enters model teaching. |
+| `foldedByDefault?` | Entries land FOLDED, off the ranked manifest surface (READable via address, not poured into the ranked view). For executor-output streams (`<tag>://`) — containment one level up. Absent/false → ranked/first-class. |
+| `storedScheme?` | Value persisted to `entries.scheme`, which may differ from the addressing `name`. Absent defaults to `name`. It must be a non-null string because every persisted identity component is non-null. |
 
-**Self-doc split (terse pushes, depth pulls).** {§manifest-self-doc} `example` + `glyph` are the hot-path listing rendered every turn — keep them terse. `documentation` is the deep prose (every op, channel, status code, gotcha); the consumer materializes it as a pull-able **`worker://plurnk/docs/<name>.md`** entry the model READs on demand, off the hot path. Both live on the manifest; the consumer decides what's pushed vs pulled.
+The manifest is closed: unknown top-level fields fail admission. Entry
+visibility is not manifest metadata; the consumer resolves it through the
+entry owner's identity.
+
+§manifest-flag-affinity `flags` is a closed environmental-authority declaration.
+Unknown flag fields fail manifest admission; absent fields are false. Only registered
+schemes enter affinity evaluation; an unknown name remains the consumer's
+registration failure.
+
+| Field                  | Scheme is inactive when          | Declared requirement                    |
+| ---------------------- | -------------------------------- | --------------------------------------- |
+| `excludedInAsk`        | `mode === "ask"`                 | Act-mode operation authority            |
+| `requiresWeb`          | `noWeb === true`                 | Web access                              |
+| `requiresInteraction`  | `noInteraction === true`         | Interactive access                      |
+
+Proposal behavior is not scheme affinity. A handler proposes by returning 202;
+the consumer's proposal lifecycle decides whether a client, loop auto,
+`noProposals`, or a timeout resolves it.
+
+§manifest-self-doc **Self-doc split (terse pushes, depth pulls).** `example` is the hot-path listing rendered every turn — keep it terse. `documentation` is the deep prose (every op, channel, status code, gotcha); the consumer materializes it as a pull-able **`worker://plurnk/docs/<name>.md`** entry the model READs on demand, off the hot path. Both live on the manifest; the consumer decides what's pushed vs pulled. `glyph` is client display metadata under {§manifest-client-display}, not self-documentation.
 
 **Authoring convention — `docs/<name>.md`.** The contract field stays a plain `string`, but a sibling SHOULD keep the deep doc in a **`docs/<name>.md`** file at the package root rather than inline, and load it into the manifest at module init — e.g. `documentation: await readFile(new URL("../docs/<name>.md", import.meta.url), "utf-8")` (top-level await; `../` resolves identically from `src/` in test and `dist/` once built). Ship it by adding `docs/**/*` to `files`. This keeps prose out of the handler source and gives editors real Markdown; the contract and the consumer's `worker://plurnk/docs/<name>.md` materialization are unchanged. A missing file fails-hard at import (no silent empty doc).
 
 ## §2 Interface
 
 Sister scheme handlers implement op methods consumed by plurnk-service via
-dispatch. An absent method returns **501**, except FIND on an entry-bearing
-`category: "data"` scheme: the consumer supplies its standard stored-entry
-FIND automatically. The op-dispatch surface is the exported
-**`SchemeHandler`** interface — every method optional, each
-`(statement, ctx) => Promise<SchemeResult>`, the per-op statement type from
-grammar:
+dispatch. The consumer owns READ for every `category: "data"` scheme and owns
+exact-target FIND over its canonical representation; no handler method can
+replace either projection. Other absent operation methods return **501**. The
+exported **`SchemeHandler`** interface gives operation methods their grammar
+statement and `ctx`, while representation preparation receives a deliberately
+narrower request. `editBatch` returns the typed `EditBatchResult`
+specialization:
 
 ```ts
-import type { SchemeHandler } from "@plurnk/plurnk-schemes";
+import type { EditBatchResult, SchemeHandler } from "@plurnk/plurnk-schemes";
 
 export interface SchemeHandler {
+    ready?(): Promise<void>;
     close?(): Promise<void>;
+    resolveEntryAddress?(target: ParsedPath, ctx: SchemeCtx): Promise<EntryAddress | SchemeResult | null>;
+    prepareRepresentation?(
+        request: RepresentationPreparationRequest,
+        ctx: SchemeCtx,
+    ): Promise<RepresentationPreparationResult>;
     prepareFind?(statement: FindStatement, ctx: SchemeCtx): Promise<SchemeResult>;
-    read?(statement: ReadStatement, ctx: SchemeCtx): Promise<SchemeResult>;
     find?(statement: FindStatement, ctx: SchemeCtx): Promise<SchemeResult>;
-    open?(statement: OpenStatement, ctx: SchemeCtx): Promise<SchemeResult>;
-    fold?(statement: FoldStatement, ctx: SchemeCtx): Promise<SchemeResult>;
-    editBatch?(statements: readonly EditStatement[], ctx: SchemeCtx): Promise<SchemeResult>;
-    copy?(statement: CopyStatement, ctx: SchemeCtx): Promise<SchemeResult>;
-    move?(statement: MoveStatement, ctx: SchemeCtx): Promise<SchemeResult>;
+    editBatch?(statements: readonly EditStatement[], ctx: SchemeCtx): Promise<EditBatchResult>;
     send?(statement: SendStatement, ctx: SchemeCtx): Promise<SchemeResult>;
     exec?(statement: ExecStatement, ctx: SchemeCtx): Promise<SchemeResult>;
     work?(statement: WorkStatement, ctx: SchemeCtx): Promise<SchemeResult>;
@@ -86,56 +105,270 @@ export interface SchemeHandler {
 }
 ```
 
-`prepareFind?` is not a second query implementation. It is the optional
-discovery/materialization seam invoked before the consumer's standard FIND
-when a data scheme has no custom `find()`. Stored schemes omit it. Acquisition
-schemes use it to make an exact requested resource into an ordinary entry,
-then receive the same catalog, matcher, span, weight, pagination, and status
-semantics as every other entry-bearing scheme. A custom `find()` replaces the
-whole operation only where the scheme owns genuinely different candidate
-semantics.
+§read-preparation `prepareRepresentation?` is the optional, operation-neutral
+acquisition seam for one exact resource. Core first resolves its canonical
+pathname and owner, binds `ctx.entries`/channels/subscriptions to that owner,
+and removes the channel fragment. The request is exactly
+`{ target, pathname }`: READ coordinates, FIND matchers, the selected channel,
+and operation intent are structurally unavailable.
+
+A stored scheme omits the hook. An acquired scheme writes its complete channel
+topology through `ctx.entries` and returns `200` readiness. A live scheme first
+seeds those same canonical channels, opens a subscription, and may return `102`
+only while production remains live. Other statuses are exact terminal results.
+Per-channel producer status belongs durably on that channel as
+`producerResult`; no transient preparation result may carry content, channel
+selection, or channel outcomes. After `200`, core alone selects the authored
+channel, applies tag/binary/text rules (including markerless `<1,16>`), and
+composes that channel's producer evidence. Cold and warm reads therefore have
+identical semantics.
+
+Exact FIND uses the same `prepareRepresentation?` seam and then the standard
+entry query; the queried default channel's durable producer result composes
+with that exact query just as it does with exact READ. `prepareFind?` is only
+the optional broad-scope discovery seam
+used before standard entry selection when no custom broad `find()` exists. A
+custom `find()` may own genuinely different candidate enumeration, but never
+exact-resource materialization or READ coordinates. Every standard query uses
+the same canonical identity as `ctx.entries`; URL authority cannot disappear
+between preparation and lookup.
+
+An exact COPY/MOVE source also resolves and prepares through this seam before
+core selects its canonical stored channel. COPY/MOVE retain their own source
+scope algebra: an absent source scope means the complete channel and an explicit
+scope preserves raw source separators. Neither distinction is exposed to the
+producer. A live `102` leaves the composition unapplied; a ready representation
+is selected from the same channels used by READ and exact FIND. A selected
+channel's producer failure aborts before destination mutation; successful
+non-`200` content remains eligible for transfer.
+
+§entry-address-resolution `resolveEntryAddress?` gives a client observation the
+same address law as model-facing operations without creating a second CRUD
+protocol. Core removes the channel fragment and target-slot pathname aliases
+{§path-parentheses} before invocation; query and other identity components
+remain exact. The hook returns the canonical stored `pathname` and a semantic
+owner:
+
+| Return                                  | Meaning                                           |
+|-----------------------------------------|---------------------------------------------------|
+| `{ pathname, owner: "commons" }`        | Resolve in the shared workspace namespace        |
+| `{ pathname, owner: "worker" }`         | Resolve in the calling worker's namespace         |
+| Non-success `SchemeResult`              | Preserve an expected address refusal exactly      |
+| `null`                                  | The selector names no client-visible entry        |
+| Hook absent                             | Use the standard pathname and `commons` ownership |
+
+The consumer supplies the observing worker through `SchemeCtx`, lowers the
+semantic owner to its private storage identity, and performs the read. A plugin
+never receives or returns database owner IDs. Schemes implement the hook only
+when their standard operation path has scheme-specific canonicalization or
+caller ownership; the hook must apply that same rule rather than inventing a
+client-only address vocabulary.
+
+A sibling does `export default class X implements SchemeHandler` (with `static manifest: SchemeManifest`) and gets compile-time signature checking. Every registered handler exposes either that static manifest or an instance `manifest` for dynamically derived identities; `Manifest.of` validates the complete resolved declaration and its registration name before the handler becomes dispatchable. The interface is the handler-delegable subset of grammar's operation union. `LOOK`/`BUFF` are client-facing operations, while OPEN/FOLD are core-owned log curation; none is dispatchable to a plugin scheme. **The statement + path types (`ReadStatement`, `SendStatement`, `UrlPath`, …) are re-exported from this barrel**, so a sibling depends on and peers (`^1`) ONLY `@plurnk/plurnk-schemes` — grammar rides underneath as the framework's transitive dep (§3).
+
+§handler-lifecycle A registered handler object is a process-lived shared
+instance and may receive overlapping operation calls. Retained handler state is
+ordinary; handlers must make concurrent access and semantic isolation explicit.
+
+| Concern            | Contract |
+| ------------------ | -------- |
+| Readiness          | `ready?()` runs after registration and before capability advertisement. It establishes that advertised resources are usable. |
+| Hook cardinality   | The consumer invokes each hook once per unique handler object identity, even when multiple registered names share that object. |
+| Operation context  | `SchemeCtx` and capabilities extracted from it remain operation-owned under {§scheme-ctx-lifetime}; only the `StreamSubscription` returned by `subscriptions.open` is retainable. |
+| Retained state     | Tenant- or address-selectable state keys every semantic isolation coordinate. A global pool is valid only when it carries no cross-tenant session state. |
+| Live ownership     | An address-selectable live resource has one unambiguous owner. Conflicting acquisition fails explicitly; it never overwrites the existing owner. |
+| Shutdown           | After in-flight scheme work drains and before backing stores close, `close?()` releases partially or fully initialized handler resources. The consumer attempts and awaits every unique handler close, then aggregates every failure. |
+
+Handlers without initialization or retained resources omit the corresponding
+hook.
 
-A sibling does `export default class X implements SchemeHandler` (with `static manifest: SchemeManifest`) and gets compile-time signature checking. The op set is exactly grammar's `PlurnkStatement` dispatch union and moves with the framework's grammar bump (0.74.57 added `work?`/`fork?`; `LOOK`/`BUFF` are grammar `ClientStatement` ops, client-facing and never dispatched to a scheme, so they're intentionally absent here). **The statement + path types (`ReadStatement`, `SendStatement`, `UrlPath`, …) are re-exported from this barrel**, so a sibling depends on and peers (`^1`) ONLY `@plurnk/plurnk-schemes` — grammar rides underneath as the framework's transitive dep (§3).
+The entry CRUD primitives (`readEntry`/`writeEntry`/`deleteEntry`) are not handler operations; schemes use `ctx.entries`. Proposal application is the optional `applyResolution` handler hook described in §3.bis.
 
-`close?()` is the process-lifecycle hook for pooled resources such as browser processes, sockets, and client connections. The consumer calls it once per unique handler instance after in-flight scheme work drains and before backing stores close. Stateless handlers omit it.
+OPEN and FOLD are not handler methods. They curate visibility and tags on the
+core-owned log; an entry scheme has no visibility state and receives 501.
 
-The entry CRUD primitives (`readEntry`/`writeEntry`/`deleteEntry`) are not handler operations; schemes use `ctx.entries`. Proposal application is the optional `applyResolution` handler hook described in §3.bis.
+§scheme-edit-batch-receipt **Regional mutation receipts.** COPY and MOVE are not
+handler methods. The engine composes their source and
+destination resource selections over `ctx.entries` and uses `editBatch` for a
+scoped destination or source mutation. This keeps channel selection, snapshot
+ordering, cross-scheme failures, and proposal sequencing uniform for every data
+scheme. Scheme hooks return their ordinary mutation result and, for a regional
+`editBatch`, an `EditBatchResult` carrying its aggregate `EditBatchReceipt`:
+
+```ts
+type EditReceiptUnit = "lines" | "codePoints";
+
+interface EditEffectReceipt {
+    readonly requested: string;
+    readonly source: string;
+    readonly result: string;
+    readonly removed: number;
+    readonly inserted: number;
+    readonly context: string;
+}
+
+interface AppliedEditBatchReceipt {
+    readonly revision: string;
+    readonly unit: EditReceiptUnit;
+    readonly before: number;
+    readonly after: number;
+    readonly effects: readonly EditEffectReceipt[];
+}
+
+interface ReviewerReplacementEditBatchReceipt {
+    readonly revision: string;
+    readonly unit: EditReceiptUnit;
+    readonly before: number;
+    readonly after: number;
+    readonly disposition: "reviewer-replaced";
+    readonly superseded: readonly string[];
+    readonly replacement: EditEffectReceipt;
+}
+
+type EditBatchReceipt =
+    | AppliedEditBatchReceipt
+    | ReviewerReplacementEditBatchReceipt;
+
+interface EditBatchResult extends SchemeResult {
+    readonly editReceipt?: EditBatchReceipt | null;
+}
+```
+
+| Batch outcome                        | Authored correlation                              | Landed effects                                                        |
+| ------------------------------------ | ------------------------------------------------- | --------------------------------------------------------------------- |
+| Applied as proposed                  | `effects[N]` describes authored EDIT `N`          | One truthful effect per authored EDIT                                 |
+| Resolver replaced the proposed body  | `superseded[N]` retains authored marker `N`       | One `replacement` effect describes the bytes that actually landed     |
+
+The replacement form is not a heuristic attribution. An arbitrary resolver
+body supersedes every authored EDIT because its correspondence to those edits
+cannot be known. The consumer projects the replacement once on the durable
+proposal-owning row and projects each authored marker's superseded disposition
+on its own row.
+
+The engine validates that receipt and owns the ordered COPY/MOVE resource
+effects shown to consumers; plugins do not invent a second effect envelope.
 
 ## §3 Helpers exported by this repo
 
 ### Types
 
-- Manifest/flags: `SchemeManifest`, `SchemeFlagAffinity`, `WriterTier`, `LoopFlags`, `DEFAULT_LOOP_FLAGS`.
-- Optional `PacketSectionTransformer` — a scheme MAY implement `transformSections(sections: PacketSection[]) → PacketSection[] | Promise<…>` to reshape the packet's section list (add/remove/reorder) before the engine measures it; called duck-typed in registration order. `PacketSection` = `{ name; slot: "system"|"user"; header: string|null; content; tokens }`. Contract declares the shape; service conforms (the in-process plugin-packet-control / fork-avoidance seam — schemes#24).
-- Behavior contract: `SchemeHandler` (§2). Scheme-facing grammar types re-exported here so siblings pin only this package: `PlurnkStatement` + the per-op statement types (`ReadStatement`, `FindStatement`, `OpenStatement`, `FoldStatement`, `EditStatement`, `CopyStatement`, `MoveStatement`, `SendStatement`, `ExecStatement`, `WorkStatement`, `ForkStatement`, `KillStatement`, `PlanStatement`) and path types (`ParsedPath` = `LocalPath` | `UrlPath` | `RegexPath`).
+- Manifest/flags: `SchemeManifest`, `SchemeFlagAffinity`, and `WriterTier`; contracts-owned `LoopFlags` and `DEFAULT_LOOP_FLAGS` are re-exported for compatibility.
+- Mutation receipts: `EditBatchResult`, `EditBatchReceipt`, `EditReceipt`, `EditEffectReceipt`, and `EditReceiptUnit`.
+- §scheme-packet-transform **Packet-section transformation.** A scheme may implement `transformSections(sections: PacketSectionDraft[]) → PacketSectionDraft[] | Promise<…>` to add, remove, or reorder sections before core measures the packet. The exact draft shape is `{ name; slot: "system"|"user"; header: string|null; content }`; no token measurement exists at this boundary. Core invokes implementations in registration order and applies `PacketSections.assertDrafts` to the initial list and every returned list. Names are non-empty and unique within the packet.
+- Behavior contract: `SchemeHandler` (§2). Scheme-facing grammar types re-exported here so siblings pin only this package: `PlurnkStatement` + the per-op statement types (`ReadStatement`, `FindStatement`, `OpenStatement`, `FoldStatement`, `EditStatement`, `CopyStatement`, `MoveStatement`, `SendStatement`, `ExecStatement`, `WorkStatement`, `ForkStatement`, `KillStatement`, `PlanStatement`) and path types (`ParsedPath` = `LocalPath` | `UrlPath`).
+- Target syntax: contracts-owned `PathSyntax` is re-exported for the shared exact-versus-path-glob classifier {§path-glob}.
 - Discovery: `SchemeDiscovery` (behavior class) with `SchemeInfo` / `SchemeDiscoveryResult` / `DiscoverOptions` (§6).
-- Executor-scheme (RFC schemes#20 — "an executor is a scheme"): `OutputScheme.manifestFromRuntime(decl)` derives a read-only-output `SchemeManifest` from an executor's `RuntimeDecl` (zero scheme-authoring); `DefaultRead.read(content, mimetype, statement, mimetypes)` → `ReadResolution` is the free `<L>`/matcher read over produced output (reuses `Slicer`/`Matcher`); `Summarize.summarize(content, mimetype)` → `OrientIndex` is the structural-only EXEC-receipt index (no content — universal-receipt containment). A per-tag executor-scheme supplies its manifest via instance `get manifest()` (§2 `SchemeHandler.manifest?`).
-- Results: `SchemeResult` is the universal `{ status, ...schemeMetadata }` contract. `EntryResult`, `ProposalResult`, and `PassthroughResult` are optional conventional shapes, not engine routing discriminators. Their `error` is a grammar `TelemetryEvent`, present iff `status >= 400`. Guards inspect those optional shapes; proposal routing itself is engine-owned and follows status plus operation semantics.
-- Capability ctx (see §3.bis): `SchemeCtx` and its domain capabilities. Entry authors additionally receive `EntryOperationCaps`, semantic `EntryOwner`, and typed standard-operation results. `editBatch` receives every same-turn EDIT for one canonical resource and channel; it validates against one snapshot and commits one revision or none. There is no sequential single-EDIT fallback.
+- §executor-scheme-output Executor-scheme ("an executor is a scheme"): `OutputScheme.manifestFromRuntime(decl)` derives a read-only-output `SchemeManifest` from an executor's `RuntimeDecl` (zero scheme-authoring). Executor output is a canonical entry and therefore inherits core's exact READ projection under {§read-preparation}; no executor-specific READ helper exists. `Summarize.summarize(content, mimetype)` -> `OrientIndex` is the structural-only EXEC-receipt index (no content - universal-receipt containment). A per-tag executor-scheme supplies its manifest via instance `get manifest()` (§2 `SchemeHandler.manifest?`).
+- Results: `SchemeResult` is the universal operation-result contract. Statuses below 400 carry no `problem`; statuses 400–599 require RFC 9457 `ProblemDetails`, and the legacy `error` member is forbidden. `EntryResult`, `ProposalResult`, and `PassthroughResult` are optional conventional shapes, not engine routing discriminators. Guards inspect those optional shapes; proposal routing itself is engine-owned and follows status plus operation semantics.
+- Standard `EntryFindResult` exposes only its paged `results`, complete `matchingPathCount` / `matchLocationCount`, content weights, and typed range. Resource-mode rows are `EntryCatalogItem` or `EntryCatalogScope`; exact matcher mode returns flat `MatchEvidence` locations. Pagination is the materialization bound; no hidden `matches`, `pathnames`, or overflow-only result collection exists.
+- Capability ctx (see §3.bis): `SchemeCtx`, `StreamSubscription`, and the domain capabilities. Entry authors additionally receive `EntryOperationCaps`, semantic `EntryOwner`/`EntryAddress`, and typed standard-operation results. `editBatch` receives every same-turn EDIT for one canonical resource and channel; it validates against one snapshot and commits one revision or none. There is no sequential single-EDIT fallback.
 
 Behavior ships as `export default class` (one class per file, static methods) — the ecosystem class paradigm. Type-only modules, the barrel, and the frozen `DEFAULT_LOOP_FLAGS` constant are the only non-class files.
 
+### §network-address Network address identity
+
+`NetworkAddress.from(target)` is the single non-secret normalization path for
+HTTP and WebSocket targets. It returns the exact addressed `scheme`, the
+canonical entry `pathname`, a fragmentless and credential-free transport
+`url`, and whether userinfo was present so the handler can reject it.
+
+| Component        | Entry identity                                      | Transport URL | Plurnk channel |
+|------------------|-----------------------------------------------------|---------------|----------------|
+| Scheme           | Exact `http`, `https`, `ws`, or `wss`               | Yes           | No             |
+| Host             | Canonical WHATWG hostname                            | Yes           | No             |
+| Port             | Non-default port                                     | Yes           | No             |
+| Path             | Canonical pathname                                   | Yes           | No             |
+| Query            | Serialized order, duplicates, and explicit empty `?` | Yes           | No             |
+| Fragment         | No                                                   | No            | Yes            |
+| Userinfo/headers | No                                                   | No            | No             |
+
+The canonical storage form is
+`/<host>[:<port>]<path>[?<query>]`, keyed together with workspace, owner, and
+the exact addressed scheme. `NetworkAddress.render(scheme, pathname)` is its
+model-facing inverse: it applies the Plurnk lexical target spelling
+{§path-parentheses} after reconstructing the exact address. Transport URLs and
+storage identity never carry that syntax layer. Routing aliases select a
+handler; they do not collapse resource identity.
+
 ### Active-scheme resolution — `SchemeResolver`
 
 - `SchemeResolver.forLoop(handlers: ReadonlyMap<string, object>, flags: LoopFlags): Set<string>` — applies `manifest.flags` affinity to each handler and returns names of schemes active under the loop's flags.
 
-### Mimetype classification — `MimetypeClassifier` {§mimetype-classifier}
+### §mimetype-classifier Mimetype classification — `MimetypeClassifier`
 
-- `MimetypeClassifier.isBinary(mimetype)` — enforces 415 boundary on binary entries. Delegates to `classifyMimetype` from @plurnk/plurnk-mimetypes (the framework owns the text/binary taxonomy — mimetypes#43; the former local allowlists were absorbed upstream verbatim and retired).
-- `MimetypeClassifier.isJson(mimetype)` — `application/json` plus `+json` variants. Used by `<L>` dispatch. Scheme semantics — stays local, not delegated.
-- `MimetypeClassifier.isLineNavigable(mimetype)` — render-layer decides whether to prefix lines with `N:\t`. Delegates to `classifyMimetype`.
+- `MimetypeClassifier.isBinary(mimetype)` — pure taxonomy for a registry-free boundary. Delegates to `classifyMimetype` from `@plurnk/plurnk-mimetypes`; a consumer with a configured `Mimetypes` service uses `Mimetypes.classify()` so installed handler declarations remain authoritative ({§mimetype-classification}).
+- `MimetypeClassifier.isHtml(mimetype)` — recognizes the normalized web-projection family: `text/html` and `application/xhtml+xml`.
+- `MimetypeClassifier.isJson(mimetype)` - `application/json` plus `+json` variants, used only by result summarization.
 - `MimetypeClassifier.normalizeAutoText(mimetype)` — `text/plain` / null / undefined → `TEXT_PRIMITIVE_MIMETYPE` (`text/markdown`).
 - `TEXT_PRIMITIVE_MIMETYPE` — `"text/markdown"` (named export from the same module).
 
-### `<L>` slicing — `Slicer`
+### §scheme-projection Projection capability
+
+Acquisition schemes delegate model-facing projection to the consumer's one
+configured mimetype family. They neither instantiate readers nor widen durable
+entry channels beyond Unicode text.
+
+| Surface                           | Contract                                                                                              |
+| --------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `readable(content, mimetype)`     | Project an acquired Unicode representation.                                                           |
+| `readableBytes(chunks, mimetype)` | Project one async byte source under the mimetype family's bounded-input policy.                       |
+| `identity(mimetype)`              | Return the opaque identity of configured projection behavior for cache and materialization freshness. |
+| `isBinary(mimetype)`              | Classify through the configured registry; installed handler declarations remain authoritative.        |
+| `ProjectedText`                   | Derived Unicode plus its output mimetype, source mimetype, and opaque projection identity.            |
+
+A returned object is present even when its `content` is `""`; only `null`
+denotes absence. Consumers must not infer projection presence from content
+length. A thrown projection call is an execution failure whose cause
+propagates; it must never be converted to `null`.
+`ProjectionInputLimitError` is the projection boundary's exported name for the
+configured mimetype family's typed bounded-input failure.
 
-- `Slicer.lines(content, marker)` — line-navigable slice. Returns `{ status, text?, startLine?, error? }`.
-- `Slicer.linesRaw(content, marker)` — same shape; no `N:\t` prefix.
-- `Slicer.jsonItems(content, marker)` — JSON-source item slice. Returns `{ status, body?, error? }`.
-- `Slicer.lineMarkerEdit(content, marker, body)` — line-navigable EDIT.
-- `Slicer.jsonItemEdit(content, marker, body)` — structural JSON EDIT.
+### §slicer-text-algebra Text-region slicing and replacement - `Slicer`
 
-### Path-extension mimetype — `PathMimetype`
+`Slicer` owns one text algebra for every textual mimetype:
+
+| Scope | Meaning |
+|---|---|
+| `<N>` | whole physical line `N` |
+| `<N,M>` | inclusive whole physical lines `N..M` |
+| `<SL,SC,EL,EC>` | exact exclusive-end region using 1-based Unicode code-point columns |
+| `<0>` / `<-1>` | mutation anchors before the first / after the final line |
+
+As an unadvertised ingestion tolerance, `Slicer` accepts
+`<startLine,startColumn,endLine>` and immediately lowers it to the complete
+four-coordinate region ending after the final code point of `endLine`.
+Successful results carry schemes-owned, boundary-validated normalization
+evidence containing both the authored and canonical coordinates. Producers do
+not emit or proactively teach the tolerated form.
+
+A harmless end-column overshoot clamps to the line's end rather than erroring
+— the model asked for "through the end" and the line is shorter than it
+guessed. Start-column overshoot and out-of-range lines remain 416 errors.
+
+- `Slicer.lines(content, marker)` returns the selected text, source
+  `startLine`, and complete resolved `region`; `Slicer.linesRaw` preserves
+  original newline separators for COPY/MOVE source transfer.
+- `Slicer.textReplacement(content, marker, body)` lowers a line shorthand or
+  exact region to one `{start,end,body}` replacement against the source
+  snapshot.
+- `Slicer.lineMarkerEdit` applies one replacement.
+- `Slicer.lineMarkerEditBatch` validates all replacements against one snapshot,
+  rejects overlaps, and applies all or none.
+- `Slicer.page(items, marker, options?)` is the separate ordered-result
+  pagination helper; it accepts only one or two integer positions and can name
+  an operation-owned range unit. `allowEmpty` preserves an otherwise valid
+  positive request when an upstream filter yields no items.
+- `Slicer.coversAvailable(range)` derives whether a successful range selected
+  the complete available extent; that fact is never serialized separately.
+
+A successful line or pagination selection carries the contracts-owned
+`RangeExtent` {§range-extent}; a 416 carries the same extent without
+`returned`. Exact regions use `region` instead. An exact-region failure,
+including a failed tolerated three-coordinate scope, carries
+`requestedCoordinates` exactly as authored; an invalid-arity text scope does
+likewise. Both carry `columnKind: "unicodeCodePoints"`.
+
+### §path-extension-mimetype Path-extension mimetype — `PathMimetype`
 
 - `PathMimetype.resolve(pathname, defaultMimetype, mimetypes)` — pathname extension → `Mimetypes.detect({ ext })`; falls back to `defaultMimetype` when no extension. text/plain auto-normalizes to text/markdown.
 
@@ -143,19 +376,34 @@ Behavior ships as `export default class` (one class per file, static methods)
 
 - `Results.isEntry` / `Results.isProposal` / `Results.isPassthrough` — guards for the optional conventional result shapes.
 - `Results.isErrorStatus(status)` — `status >= 400`.
-- `Results.error(scheme, kind, message?, position?)` — build a scheme-sourced `TelemetryEvent` (`source: "scheme:<name>"`).
-- `Results.logCoordinate(coordinate, op?)` — build a `LogCoordinate` position.
-
-### Matcher dispatch — `Matcher` {§matcher-dispatch}
-
-- `Matcher.matchAgainstContent(body, content, mimetype, mimetypes, baseLine?)` — body-matcher adapter over `Mimetypes.query` (glob/regex/jsonpath/xpath, all served by the framework). Maps framework errors:
-  - `UnsupportedDialectError` → status 415
-  - `InvalidExpressionError` → status 400
-  - `QueryParseFailureError` → status 203 (soft fallback: raw content as text/markdown with `reason`)
-  - Empty match array → status 204
-  - Matches → status 200, body rendered as lean `<source-line>:\t<value>` lines (one match per line, the `N:\t` convention READ emits). Value bare for a single-line string, JSON-encoded otherwise so the one-match-per-line invariant holds (preserves `<L><K>` pick-Kth composition). The resolved query path (`matching`) is dropped — the structured `{matched, matching}` wrapper was a model-legibility barrier (schemes#12).
-
-### §3.bis Capability ctx — the stable trusted-extension surface {§capability-ctx}
+- `Results.problem(owner, code, status, detail, extensions?)` — build and validate RFC 9457 Problem Details with a stable `https://problems.plurnk.dev/<owner>/<code>` type.
+- `Results.failure(owner, code, status, detail, fields?, extensions?)` — build and validate a failed operation result.
+- `Results.assert(result)` — validate the complete success/failure discrimination and reject malformed plugin output.
+- `Results.assertMatchEvidence(evidence)` / `assertMatchEvidenceList(evidence)` - enforce the exact `{ locator?, region? }` shape and shared `TextRegion` contract.
+- `Results.assertReadResult(result)` - validate the universal operation result plus any `region` and `matches` it exposes.
+- `Results.attachInstance(result, uri)` — attach the durable occurrence URI to a failed result.
+
+A handler owns its failure classification and explanation. The daemon owns the
+durable `instance`, because only it knows the committed log coordinate. A
+malformed handler result is a plugin contract violation and fails hard; the
+consumer does not invent a fallback error or reinterpret arbitrary fields.
+The same discrimination applies to every `SchemeCtx` capability result:
+entries, channels, and tags never return a bare failure status.
+
+### Matcher dispatch - `Matcher` {§matcher-dispatch}
+
+- `Matcher.matchAgainstContent(body, content, mimetype, mimetypes)` is the body-matcher adapter over `Mimetypes.query` (glob/regex/jsonpath/xpath).
+- A match returns status 200 and `matches: MatchEvidence[]`.
+  `MatchEvidence` is `{locator?, region?}`. `locator` preserves a structural locator;
+  `region` is a complete four-coordinate `TextRegion` only when the finding has
+  an honest exact or nearest-enclosing mapping into the text the model can READ.
+  Each item must contain at least one of `locator` or `region`; other fields violate
+  the shared evidence contract.
+- The matcher is a boolean resource selector. It does not replace content with matched values or choose a retrieval window. FIND owns selection and pagination; exact READ owns text projection.
+- Empty results return 204 with `matches: []`; `UnsupportedDialectError` maps to 415; `InvalidExpressionError` maps to 400; `QueryParseFailureError` maps to 203 with raw content, text/markdown, and `reason`.
+- A multi-resource matcher omits candidates that return 415 when at least one candidate supports the dialect. If no candidate supports it, the matcher returns the first exact 415 Problem. An unreadable binary marker therefore cannot poison a repository-wide text search or masquerade as a match.
+
+### §capability-ctx §3.bis Capability ctx — the stable trusted-extension surface
 
 Scheme plugins are trusted in-process Node.js code. `SchemeCtx` is not a
 sandbox or a security boundary; an installed plugin already has the process's
@@ -169,18 +417,37 @@ its implementation.
 - `entries` — direct storage over the scheme's own namespace
   (`read`/`write`/`delete`) plus `operations`, the standard PLURNK
   `READ`/`EDIT`/`FIND`/`SEND` implementation for entry-bearing schemes.
+  A write may omit channel state to select the `static` default; a successful
+  storage read always returns each channel's persisted lifecycle state.
   Standard operations are bound to the handler's manifest. Their optional
   owner is semantic: `"commons"` (default) or the current `"worker"`; database
   owner IDs are not part of the plugin contract. A handler may implement its
-  own op method instead. In particular, a handler with `find()` owns FIND and
-  fan-out; one without it receives the standard stored-entry behavior.
+  own op method instead. In particular, a handler with `find()` owns FIND; one
+  without it receives the standard stored-entry behavior.
 - `channels` — content writes + state (`append`/`replace`/`setState`).
 - `tags` — entry tags (`add`/`remove`/`list`).
-- `notify` — between-turn client signal (`streamEvent`, metadata-only); not model-facing. (No `wakeWorker`: the run-wake carries subscription-close context that only exists at stream completion, so it lives on `subscriptions.close`. Only streaming schemes wake a worker, always via close.)
-- `projection` — `readable(content, mimetype)` asks the consumer's configured mimetype family for the model-facing text projection. Acquisition schemes own bytes/DOM; they do not instantiate or second-guess the reader family. `null` means no readable projection.
-- `subscriptions` — streaming lifecycle: `open(pathname, handle)` atomically binds durable subscription identity to the consumer's process-local live-handle registry, returns a worker+teardown-composed `AbortSignal`, and takes a force-cancel `SubscriptionHandle`; routed cancellation both invokes the handle and aborts that signal. `notifyChunk(channel, chunk, mimetype?)` is **fused** (append + stream/event in one call), with an optional per-call `mimetype` that retypes the channel to the content's actual type (passed statelessly per chunk; the impl writes only on change; the manifest channel mimetype is the pre-fetch seed default — plurnk-service#226). `close("done" | "error" | "cancelled", outcome?)` composites channel state, durable status (200/500/499), live-handle unregister, and run wake. Designed against Exec (two-channel, cancel-tested).
-
-There is **no `visibility` capability**: entry-level SHOW/HIDE was removed in plurnk-service's index/visibility teardown — SHOW/HIDE now collapse/expand `log://` rows, a log-side concern with no entry-visibility for a scheme to set (plurnk-service#180).
+- `notify` — between-turn client signal (`streamEvent`, metadata-only); not model-facing. (No `wakeWorker`: the worker wake carries subscription-close context that only exists at stream completion, so it lives on `subscriptions.close`. Only streaming schemes wake a worker, always via close.)
+- `projection` — the text and bounded-byte projection capability in {§scheme-projection}. Acquisition schemes own source representations; they do not instantiate or second-guess the reader family. `null` means no readable projection.
+- §scheme-subscriptions `subscriptions` — one streaming lifecycle:
+
+| Surface                           | Lifetime   | Contract                                                                                                   |
+| --------------------------------- | ---------- | ---------------------------------------------------------------------------------------------------------- |
+| `open(pathname, handle)`          | Operation  | Bind durable and live identity, return the exact object, and route cancellation through its signal/handle. |
+| Returned `StreamSubscription`     | Retainable | `AbortSignal` plus fused chunk publication and terminal settlement; the only retainable capability.        |
+| `subscriptions.notifyChunk/close` | Operation  | Forward to the exact returned object; own no second state or persistence path.                             |
+
+`notifyChunk` appends and emits one stream event. Its optional stateless
+`mimetype` retypes the channel only when the stored type differs.
+`close(result, summary?, channelStates?)` validates and persists the exact
+universal `SchemeResult`, settles channel state (exact named overrides, then the
+result-status default), unregisters the live handle, and wakes the worker.
+`summary` is presentation only; it never replaces or reconstructs the result.
+An override names an existing channel and is exactly `closed` or `errored`;
+invalid overrides fail before any channel state is changed. This permits one
+multi-channel producer to preserve successful evidence beside an independently
+failed representation without inventing another settlement path.
+
+There is **no `visibility` capability**: entry-level SHOW/HIDE was removed in the index/visibility teardown — SHOW/HIDE now collapse/expand `log://` rows, a log-side concern with no entry-visibility for a scheme to set.
 
 The consumer passes exactly this public context to every handler. Bundled
 adapters that also implement daemon-owned lifecycle behavior receive those
@@ -188,7 +455,22 @@ collaborators separately at construction or binding time; consumers must not
 decorate `SchemeCtx` with database handles, registries, tokenizers, notifier
 callbacks, or other private service state.
 
-**Proposals are not a capability.** A side-effecting scheme proposes by *returning* a `ProposalResult` (status 202); the engine owns the resolution lifecycle. On acceptance it calls the handler's optional `applyResolution({ attrs, body }, ctx)` hook. `attrs` is the payload returned by the proposing operation and `body` is the resolver-approved body, when present. The hook returns `{ status, outcome?, body? }`: a status below 400 completes the accept; a failure rejects it with the returned outcome.
+§scheme-ctx-lifetime `SchemeCtx` belongs to one operation call. A handler may
+use it for the duration of that call, including asynchronous work awaited by
+the call, but must not retain the context or any other extracted capability
+after the handler returns. A streaming handler may retain only the exact
+`StreamSubscription` returned by `subscriptions.open`; its bound methods carry
+that subscription's identity without retaining the general context. Other
+retained handler-owned resources follow {§handler-lifecycle}.
+
+**Proposals are not a capability.** A side-effecting scheme proposes by *returning* a `ProposalResult` (status 202); the engine owns the resolution lifecycle. On acceptance it calls the handler's optional `applyResolution({ attrs, body }, ctx)` hook. `attrs` is the payload returned by the proposing operation and `body` is the resolver-approved body, when present. The hook returns a `ProposalApplyResult`: a status below 400 completes the accept; a failure preserves the applying scheme's Problem Details as the proposal's final result.
+
+§scheme-edit-proposal-receipt An accepted EDIT proposal may return its final
+aggregate `editReceipt` alongside its per-row model-facing `result`. A resolver
+replacement must use the reviewer-replaced form from
+{§scheme-edit-batch-receipt}. Core consumes that aggregate as transient batch
+coordination and COPY/MOVE composition input; it persists only per-row receipts
+or ordered resource effects.
 
 ## §4 What's NOT in this repo
 
@@ -199,12 +481,12 @@ Raw CRUD methods are not a parallel handler protocol. For `data` schemes whose
 handlers omit resource-specific storage hooks, engine-owned COPY/MOVE/KILL
 orchestration uses the manifest-bound `ctx.entries` implementation.
 
-## §5 Trusted extension contract {§trusted-extension}
+## §trusted-extension §5 Trusted extension contract
 
 Installed schemes may legitimately own network connections, subprocesses,
-caches, pools, or other host resources. Use `close()` to release resources
-owned by the handler. These powers are why installation is a trust decision and
-why contained interoperability belongs in MCP rather than an in-process plugin.
+caches, pools, or other host resources under {§handler-lifecycle}. These powers
+are why installation is a trust decision and why contained interoperability
+belongs in MCP rather than an in-process plugin.
 
 The supported compatibility boundary is `@plurnk/plurnk-schemes`. Plugins
 should not import private service modules, depend on database layout, or call
@@ -212,13 +494,13 @@ prepared statements directly: those are unstable implementation details, not
 additional plugin capabilities. Use `SchemeCtx` or propose a new semantic
 capability when the public surface cannot express a coherent extension.
 
-## §6 Discovery & registration (third-party)
+## §scheme-discovery §6 Discovery & registration (third-party)
 
 A scheme handler is discovered and registered with **zero first-party involvement** — install it, it lights up. The contract:
 
-- **Declare** `plurnk.kind: "scheme"` in `package.json` — or, for a package owning multiple capability families, an array that **includes** `"scheme"` (`kind: ["exec", "scheme"]`, #483); every family scanner accepts a package whose kind is or includes its own, string form as the single-kind sugar. Then name the scheme(s) it owns, in one of two forms: `plurnk.schemes: [{ name, export }, …]` (canonical — one entry per scheme, `export` naming the handler-class export) or `plurnk.name: "<scheme>"` (sugar for exactly one scheme, the `default` export). One package may own several names; each name has exactly one owner (#473). This mirrors execs' `plurnk.runtimes: [{ name, glyph, example }]` — `plurnk.kind` plus a plural family-noun array of named capabilities is the shared manifest covenant across families; `export` is schemes' family-specific field (a scheme instantiates a class per name, where an executor dispatches tags through one).
-- **`SchemeDiscovery` owns the scan (this package).** `SchemeDiscovery.discover({ cwd? })` walks *all* of `node_modules` — scoped (`@acme/foo`) and unscoped — and returns `{ schemes: {name, packageName, exportName?, attribution?}[], skipped }` for every package declaring `plurnk.kind === "scheme"`. Scope-agnostic, so a third party under their own scope is found with no first-party allow-list (plurnk-service#227); two names claiming one prefix fail-hard (across packages or within one), as does a malformed `plurnk.schemes` (locality of error, not a silent skip). It returns **descriptors, not handlers** — contract-only, it never imports a scheme package; the consumer imports each `packageName` and registers `new mod[exportName ?? "default"]()`, applying in-tree precedence. The scan primitives — package enumeration, the `PLURNK_PLUGINS_TRUSTED_ONLY` trust gate, the deployment-root `node_modules` walk — are one implementation in `@plurnk/plurnk-meta`, shared by all four family-head scanners; `SchemeDiscovery` adds only the scheme-descriptor shape on top.
-- **`attribution` rides the descriptor verbatim.** A package may declare `plurnk.attribution` (a credit string, or an array of them); the scan passes it through untouched as `SchemeInfo.attribution` (`string | string[] | undefined`) — anything that isn't a string or string-array is dropped. The framework neither validates nor normalizes it: the `@plurnk`-tags-only-from-`@plurnk`-packages reservation policy is the **consumer's** to enforce on the surfaced credit (plurnk-service#26).
+- **Declare** the exact string `plurnk.kind: "scheme"` in `package.json` ({§plugin-family-kind}). Then name the scheme(s) it owns in one of two forms: `plurnk.schemes: [{ name, export }, …]` (canonical — one entry per scheme, `export` naming the handler-class export) or `plurnk.name: "<scheme>"` (one-scheme shorthand for the `default` export). One package may own several names inside this family; each name has exactly one owner.
+- **`SchemeDiscovery` owns the scan (this package).** `SchemeDiscovery.discover({ cwd? })` walks *all* of `node_modules` — scoped (`@acme/foo`) and unscoped — and returns `{ schemes: {name, packageName, exportName?, attribution?}[], packageAttributions, skipped }` for every package declaring `plurnk.kind === "scheme"`. Scope-agnostic, so a third party under their own scope is found with no first-party allow-list; two names claiming one prefix fail-hard (across packages or within one), as does a malformed `plurnk.schemes` (locality of error, not a silent skip). It returns **descriptors, not handlers** — contract-only, it never imports a scheme package; the consumer imports each `packageName` and registers `new mod[exportName ?? "default"]()`, applying in-tree precedence. The scan primitives — package enumeration, the `PLURNK_PLUGINS_TRUSTED_ONLY` trust gate, the deployment-root `node_modules` walk — are one implementation in `@plurnk/plurnk-meta`, shared by all four family-head scanners; `SchemeDiscovery` adds only the scheme-descriptor shape on top.
+- **Attribution is package-authored.** `packageAttributions` carries one canonical validated static tag list per admitted package. `SchemeInfo.attribution` remains the published per-scheme projection when a declaration exists; a loaded handler may additionally implement the shared runtime hook ({§plugin-attribution}). Neither the descriptor nor the consumer owns another policy.
 - **The framework stays contract-only.** `@plurnk/plurnk-schemes` does not depend on scheme plugins. The daemon declares its bundled plugins as direct dependencies, and additional plugins are installed at the application root. Plugins declare the framework as a peer dependency using the repository's normal same-minor compatibility range; the framework itself is ignored by discovery because it has no `plurnk.kind`.
 - **The default bundle is the daemon's own `dependencies`**, not an aggregator package (the `-all` metapackages are retired). Installing `plurnk-core` surfaces the first-party schemes; any other leaf — first-party or third-party — is added by installing it, and scope-agnostic discovery lights it up identically. No bundle is ever a gate.
-- **Trust.** An operator can require host-level trust before a discovered plugin registers (`PLURNK_PLUGINS_TRUSTED_ONLY`, plurnk-service#229) — the scope-agnostic scan widens reach, the trust gate bounds it.
+- **Trust.** The scanner enforces the shared predicate before attribution or scheme-field validation and returns withheld package names in `skipped`; the host owns presentation ({§plugin-trust-boundary}).