@plurnk/plurnk-schemes 1.3.12 → 1.5.0

package/README.md

@@ -5,7 +5,7 @@ Framework + contract for `@plurnk/plurnk-schemes-*` URI handler packages. Consum
 ## Documentation
 
 - [`SPEC.md`](./SPEC.md) — author-facing contract.
-- Constellation: [plurnk-grammar](https://github.com/plurnk/plurnk-grammar), [plurnk-mimetypes](https://github.com/plurnk/plurnk-mimetypes), [plurnk-providers](https://github.com/plurnk/plurnk-providers), [plurnk-execs](https://github.com/plurnk/plurnk-execs).
+- Constellation: [plurnk-contracts](https://github.com/plurnk/plurnk-service/tree/main/plurnk-contracts), [plurnk-mimetypes](https://github.com/plurnk/plurnk-service/tree/main/plurnk-mimetypes), [plurnk-providers](https://github.com/plurnk/plurnk-service/tree/main/plurnk-providers), [plurnk-execs](https://github.com/plurnk/plurnk-service/tree/main/plurnk-execs).
 
 ## Write a scheme
 
@@ -25,19 +25,45 @@ Ship a scheme by publishing a package — **under any scope** (`@acme/whatever`;
 
 ```ts
 import type {
-  SchemeHandler, SchemeManifest, SchemeCtx, SchemeResult, ReadStatement,
+  RepresentationPreparationRequest, RepresentationPreparationResult,
+  SchemeHandler, SchemeManifest, SchemeCtx,
 } from "@plurnk/plurnk-schemes";
 
 export default class Foo implements SchemeHandler {
   static manifest: SchemeManifest = { /* step 3 */ };
 
-  async read(statement: ReadStatement, ctx: SchemeCtx): Promise<SchemeResult> {
-    /* … use ctx's stable domain capabilities (SPEC §3.bis) … */
+  async prepareRepresentation(
+    { target, pathname }: RepresentationPreparationRequest,
+    ctx: SchemeCtx,
+  ): Promise<RepresentationPreparationResult> {
+    const { content, mimetype } = await acquire(target);
+    const written = await ctx.entries.write(pathname, {
+      channels: { body: { content, mimetype } },
+      tags: [],
+    });
+    return written.status >= 400 ? written : { status: 200 };
   }
 }
 ```
 
-Implement only the op methods you support — `read` / `find` / `edit` / `copy` / `move` / `send` / … — all optional; the engine calls `handler[op.toLowerCase()](statement, ctx)` and returns **501** for any op you omit. `implements SchemeHandler` gives you compile-time signature checking. The statement + path types (`ReadStatement`, `SendStatement`, `UrlPath`, …) are **re-exported from this package**, so you depend on and peer (`^1`) **only `@plurnk/plurnk-schemes`** — grammar rides underneath.
+Core owns READ. A stored scheme needs no READ method; an acquisition scheme
+implements scope-blind `prepareRepresentation`, writes its complete channels,
+and lets core select the channel and apply operation-owned semantics. Exact
+READ, exact FIND, and COPY/MOVE source selection all reuse that acquisition;
+the producer receives none of their scopes, matchers, or channel choices.
+Implement only
+the remaining delegated methods you support—`find`, `editBatch`, `send`, and
+the other optional methods in `SchemeHandler`. COPY and MOVE are engine-owned
+compositions over `ctx.entries` and `editBatch`, so plugins do not override
+them or author COPY/MOVE effect envelopes. A regional `editBatch`
+returns `EditBatchResult` with its typed `EditBatchReceipt`; the engine validates
+and projects it.
+The optional synchronous `attributions(context)` hook may return no, one, or
+many opaque tags for each provider emission attempt ({§plugin-attribution}).
+`implements SchemeHandler` gives compile-time signature checking. The statement
+and path types (`FindStatement`, `SendStatement`, `UrlPath`, etc.) are re-exported
+from this package, so you depend on and peer (`^1`) only
+`@plurnk/plurnk-schemes`; grammar rides underneath.
 
 ### 3. Declare the manifest — including self-doc
 
@@ -52,11 +78,10 @@ static manifest: SchemeManifest = {
   channels: { body: "text/markdown" },
   defaultChannel: "body",
   category: "data",
-  scope: "workspace",
   writableBy: ["model", "client"],
   volatile: false,
   modelVisible: true,
-  glyph: "🦊",                          // display icon; omit → the name is shown
+  glyph: "🦊",                          // optional client-only display marker
   example: "READ(foo://thing/42)",      // terse hot-path one-liner, rendered every turn
   documentation,                        // deep doc from docs/foo.md, pulled at worker://plurnk/docs/foo.md
 };
@@ -64,11 +89,11 @@ static manifest: SchemeManifest = {
 
 - **`example`** — the scheme's terse **hot-path** one-liner, rendered in the live catalogue every turn (like an execs runtime's `example`). Keep it to one canonical usage line; depth goes in `documentation`. Omit → not advertised.
 - **`documentation`** — the **deep doc** (ops, channels, edge cases). The consumer materializes it as a pull-able `worker://plurnk/docs/<name>.md` entry the model READs on demand — off the hot path. Mirrors `ExecInfo.documentation`. **Convention:** keep it in a **`docs/<name>.md`** file (root) and load it at module init with the snippet above — `../` resolves the same from `src/` (test) and `dist/` (built); add `docs/**/*` to `files`. A missing file fails-hard at import.
-- **`glyph`** — a display icon (emoji / nerdfont). Omit it and the scheme `name` is rendered in its place.
+- **`glyph`** — optional opaque client display metadata. It is discoverable through the client capability wire and never rendered into model teaching; clients choose fallback, fonts, and theme.
 
 ### 4. Self-doc: terse pushes, depth pulls
 
-`example`/`glyph` render every turn — keep them terse. `documentation` is the deep prose; the consumer materializes it at `worker://plurnk/docs/<name>.md` for the model to READ on demand. Don't dump prose into `example` (it floods the hot path) — put it in `documentation`.
+`example` renders every turn — keep it terse. `documentation` is the deep prose; the consumer materializes it at `worker://plurnk/docs/<name>.md` for the model to READ on demand. Don't dump prose into `example` (it floods the hot path) — put it in `documentation`.
 
 That's the whole contract: declare, `implements SchemeHandler`, manifest with self-doc. Publish, install, discovered.
 
@@ -76,20 +101,21 @@ That's the whole contract: declare, `implements SchemeHandler`, manifest with se
 
 ### Types
 
-- Manifest/flags: `SchemeManifest` (incl. `example` / `documentation` / `glyph` self-doc), `SchemeFlagAffinity`, `WriterTier`, `LoopFlags`, `DEFAULT_LOOP_FLAGS`.
-- Behavior contract: `SchemeHandler` + optional `PacketSectionTransformer` (`PacketSection`); the re-exported scheme-facing grammar types (`PlurnkStatement` + per-op statements + `ParsedPath` / `LocalPath` / `UrlPath`).
-- Results: universal `SchemeResult` plus optional `EntryResult` / `ProposalResult` / `PassthroughResult` authoring shapes, `SchemeResultBase`, and `TelemetryEvent`.
+- Manifest/flags: `SchemeManifest` (including `example` / `documentation` self-doc and client-only `glyph`), `SchemeFlagAffinity`, and `WriterTier`; contracts-owned `LoopFlags` / `DEFAULT_LOOP_FLAGS` are re-exported.
+- Behavior contract: `SchemeHandler` + optional `PacketSectionTransformer` (`PacketSectionDraft`); the re-exported scheme-facing grammar types (`PlurnkStatement` + per-op statements + `ParsedPath` / `LocalPath` / `UrlPath`).
+- Results: universal `SchemeResult` plus RFC 9457 `ProblemDetails`, optional `EntryResult` / `ProposalResult` / `PassthroughResult` authoring shapes, `SchemeResultBase`, matcher navigation `MatchEvidence`, and target-shaped standard `EntryFindResult` pagination/count metadata.
 - Capability ctx: `SchemeCtx` and its entry, channel, tag, notification, projection, and subscription domains. Entry schemes can reuse typed standard operations with semantic commons/worker ownership.
 
 ### Helpers (`export default class`, static methods)
 
 - `SchemeResolver.forLoop(handlers, flags)` — active-scheme resolution under loop flags.
-- `MimetypeClassifier.isBinary` / `.isLineNavigable` / `.isJson` / `.normalizeAutoText` (+ `TEXT_PRIMITIVE_MIMETYPE` named export) — mimetype classification.
-- `Slicer.lines` / `.linesRaw` / `.jsonItems` / `.lineMarkerEdit` / `.jsonItemEdit` — `<L>` slicing + structural EDIT.
+- `MimetypeClassifier.isBinary` / `.isJson` / `.normalizeAutoText` (+ `TEXT_PRIMITIVE_MIMETYPE` named export) - registry-free mimetype taxonomy and scheme-local helpers. Configured consumers use `Mimetypes.classify()` for handler-aware binary decisions.
+- `Slicer.lines` / `.linesRaw` / `.textReplacement` / `.lineMarkerEdit` / `.lineMarkerEditBatch` - universal text-region projection and same-snapshot replacement; `Slicer.page` handles ordered results, and `.coversAvailable` derives complete coverage from their compact `RangeExtent`.
 - `PathMimetype.resolve(pathname, default, mimetypes)` — path-extension mimetype resolver.
-- `Matcher.matchAgainstContent(body, content, mimetype, mimetypes, baseLine?)` — body-matcher dispatch over `Mimetypes.query` (glob/regex/jsonpath/xpath).
-- `Results.error` / `.logCoordinate` / `.isEntry` / `.isProposal` / `.isPassthrough` / `.isErrorStatus` — result builders + guards.
-- `SchemeDiscovery.discover({ cwd? })` — scope-agnostic `node_modules` scan for `plurnk.kind:"scheme"` packages (trust-gated, fail-hard on prefix collision); returns descriptors for the consumer to register (SPEC §6).
+- `Matcher.matchAgainstContent(body, content, mimetype, mimetypes)` - boolean resource selection over `Mimetypes.query` (glob/regex/jsonpath/xpath), returning locator/exact-region `MatchEvidence`.
+- `Results.problem` / `.failure` / `.assert` / `.assertReadResult` / `.assertMatchEvidenceList` / `.attachInstance` / `.isEntry` / `.isProposal` / `.isPassthrough` / `.isErrorStatus` - RFC 9457 result builders, validators, durable-occurrence attachment, and guards.
+- `PacketSections.assertDrafts(value, subject?)` — validates the exact tokenless section-draft list returned by a packet transformer.
+- `SchemeDiscovery.discover({ cwd? })` — scope-agnostic `node_modules` scan for `plurnk.kind:"scheme"` packages (trust-gated, fail-hard on prefix collision); returns descriptors plus canonical static attribution lists for represented packages (SPEC §6, {§plugin-attribution}).
 
 `SchemeCtx` is the stable semantic API for trusted in-process schemes, not a
 sandbox. The consumer injects its implementation; database layout and private