@plurnk/plurnk-service 0.43.0 → 0.45.0

package/dist/core/Engine.sql

@@ -0,0 +1,291 @@
+-- Engine SQL. SPEC §arch (architecture), §scheme (op dispatch + log).
+
+-- PREP: engine_loop_status
+SELECT status FROM loops WHERE id = $loop_id;
+
+-- PREP: engine_count_active_loops_for_run
+-- Wake-on-completion uses this to decide whether to open a new loop or
+-- let the existing one pick up the channel transition at the next turn
+-- boundary. Status 102 = "in progress" (any non-terminal state).
+SELECT COUNT(*) AS n FROM loops WHERE run_id = $run_id AND status = 102;
+
+-- PREP: engine_get_loop_flags
+-- Loads the loop's persisted flags (json). Default '{}'; YOLO listener and
+-- SchemeRegistry.resolveForLoop merge over DEFAULT_LOOP_FLAGS for missing
+-- fields. Migration 014.
+SELECT flags FROM loops WHERE id = $loop_id;
+
+-- PREP: engine_set_loop_flags
+-- Updates the loop's persisted flags (json). Called by loop.run RPC handler.
+UPDATE loops SET flags = $flags WHERE id = $loop_id;
+
+-- PREP: engine_get_loop_prompt
+-- Loop's prompt + sequence — runTurn reads it on turn 1 to foist a
+-- system-origin EDIT against plurnk:///prompt/<loop_id>/1 (§packet), at the
+-- turn's first action sequence. Prompts are first-class log entries
+-- (no synthetic / shim layer).
+SELECT prompt, sequence FROM loops WHERE id = $loop_id;
+
+-- PREP: engine_loop_set_status
+-- The universal terminal setter. terminal_message carries either the loop's deliverable
+-- (the SEND body) or the engine's abandonment reason (max_turns / budget_overflow /
+-- strike_threshold) — rides the §run-scheme delta.
+UPDATE loops SET status = $status, terminal_message = $message WHERE id = $loop_id;
+
+-- PREP: session_get_settings
+-- #231 — the session's client-chosen open-context bag ({ manifestItems?, mdDocs? }),
+-- read at turn-0 with precedence over env.
+SELECT settings FROM sessions WHERE id = $session_id;
+
+-- PREP: engine_target_diverged_this_turn
+-- #note10 — did this entry diverge on disk THIS turn? A source=file env-delta for the
+-- target, materialized into this run's log at the current turn, means the model's view
+-- predates the ambient change — a YOLO auto-accept of a same-turn EDIT would clobber it.
+SELECT 1 AS hit
+FROM log_entries
+WHERE run_id = $run_id AND turn_id = $turn_id
+  AND origin = 'plurnk' AND source = 'file' AND op = 'EDIT'
+  AND scheme IS $scheme AND pathname = $pathname
+LIMIT 1;
+
+-- PREP: engine_list_session_entry_tags
+-- #note13 — every (entry, tag) in the session, for the manifest catalog's tags field.
+SELECT et.entry_id, et.tag
+FROM entry_tags et
+JOIN entries e ON e.id = et.entry_id
+WHERE e.session_id = $session_id
+ORDER BY et.entry_id, et.tag;
+
+-- PREP: engine_next_turn_sequence
+SELECT COALESCE(MAX(sequence), 0) + 1 AS next FROM turns WHERE loop_id = $loop_id;
+
+-- PREP: engine_loop_usage
+-- Per-loop usage totals — SUM the loop's turns (§tokenomics stores usage per turn).
+-- Surfaced on loop.run + loop/terminated (#197).
+SELECT COALESCE(SUM(usage_prompt), 0)     AS prompt,
+       COALESCE(SUM(usage_completion), 0) AS completion,
+       COALESCE(SUM(usage_cost_pico), 0)  AS cost_pico
+FROM turns WHERE loop_id = $loop_id;
+
+-- PREP: engine_loop_turn_seqs
+-- Look up (loop_seq, turn_seq) for a given (loop_id, turn_id). Used by
+-- #writeLog when an op needs to address itself or its output by log
+-- coordinate (e.g. EXEC's stream entry at exec:///<loop_seq>/<turn_seq>/<sequence>/EXEC).
+SELECT l.sequence AS loop_seq, t.sequence AS turn_seq
+FROM loops l, turns t
+WHERE l.id = $loop_id AND t.id = $turn_id;
+
+-- PREP: engine_open_turn
+-- Turn-as-container model: insert a turn row at runTurn open with a
+-- placeholder packet and status=102 (in-progress). Pre-model writes
+-- (the user prompt; later, system signals/telemetry events) land into
+-- this row before the provider is called. The turn is then "closed"
+-- via engine_close_turn with the final packet + status + usage stats
+-- after dispatch completes.
+INSERT INTO turns (loop_id, sequence, status, packet)
+VALUES ($loop_id, $sequence, 102, '{}')
+RETURNING id;
+
+-- PREP: engine_close_turn
+-- Updates the turn with the response packet, terminal status, and
+-- provider usage stats once dispatch is complete. Paired with
+-- engine_open_turn at runTurn boundaries.
+UPDATE turns SET
+    status = $status,
+    packet = $packet,
+    usage_prompt = $usage_prompt,
+    usage_completion = $usage_completion,
+    usage_cached = $usage_cached,
+    usage_cost_pico = $usage_cost_pico,
+    finish_reason = $finish_reason,
+    model = $model
+WHERE id = $id;
+
+-- PREP: engine_list_session_entries
+-- Every entry of a session — all schemes, all channels — the source for
+-- plurnk:///manifest.json, the flat catalog of everything the session holds.
+-- Session-scoped (persists across runs); FOLD doesn't drop from the catalog.
+-- `seconds` is the live age of an active stream: now − the open subscription's
+-- opened_at (closed_at IS NULL). NULL for static entries. unixepoch parses the
+-- stored '...%fZ' timestamp directly; re-evaluated every render like tokens.
+SELECT e.id AS entry_id, e.scheme, e.pathname, ec.name AS channel, ec.content, ec.mimetype, ec.tokens, e.deep_hash,
+    CAST(unixepoch('now') - unixepoch(s.opened_at) AS INTEGER) AS seconds
+FROM entries e
+JOIN entry_channels ec ON ec.entry_id = e.id
+LEFT JOIN subscriptions s ON s.entry_id = e.id AND s.closed_at IS NULL
+-- entries are session-scoped, shared across runs — §machine-processes-one-filesystem
+WHERE e.scope = 'session' AND e.session_id = $session_id
+-- User Note 5 — mtime-ascending: dormant entries hold the stable prompt-cache prefix; churn clusters at the tail.
+ORDER BY e.updated_at ASC, e.id ASC, ec.name;
+
+-- PREP: engine_run_prior_turn_time
+-- §env-delta — timestamp of this run's most recent turn BEFORE the current one
+-- (the "since I last looked" boundary). NULL on the run's first turn → no deltas.
+SELECT MAX(t.timestamp) AS since
+FROM turns t JOIN loops l ON l.id = t.loop_id
+WHERE l.run_id = $run_id AND t.id != $turn_id;
+
+-- PREP: engine_pull_env_deltas
+-- §env-delta — other actors' resolved EDITs on shared entries since this run last
+-- looked. Real edits (origin model/client) AND the plurnk run's fs-sync fictions
+-- (origin=plurnk on the reserved 'plurnk' run); excludes this run's own rows and
+-- other runs' already-materialized deltas (origin=plurnk on a real run). plurnk:///
+-- entries (manifest/prompt/doc) never surface. This is the environment door (§actor-boundary-two-doors); the voice door is inject.
+SELECT le.run_id, le.scheme, le.pathname, le.rx, le.source
+FROM log_entries le
+JOIN runs r ON r.id = le.run_id
+WHERE r.session_id = $session_id
+  AND le.op = 'EDIT'
+  AND le.state = 'resolved'
+  AND le.status_rx IN (200, 201)
+  AND (le.scheme IS NULL OR le.scheme != 'plurnk')
+  AND le.run_id != $run_id
+  AND le.at > $since
+  AND (le.origin != 'plurnk'
+       OR le.run_id = (SELECT id FROM runs WHERE session_id = $session_id AND name = 'plurnk'))
+ORDER BY le.at;
+
+-- PREP: engine_insert_env_delta
+-- §env-delta — materialize a pulled cross-actor edit as a FOLDED delta (expanded=0)
+-- in this run's log. origin=plurnk; source carries the cause (sibling run id or
+-- 'file'); rx reuses the originating row's result span (§edit-result-render).
+INSERT INTO log_entries (
+    run_id, loop_id, turn_id, sequence, origin, source,
+    op, scheme, pathname, tx, mimetype_tx, rx, mimetype_rx, status_rx, expanded
+) VALUES (
+    $run_id, $loop_id, $turn_id, $sequence, 'plurnk', $source,
+    'EDIT', $scheme, $pathname, '', 'text/plain', $rx, 'application/json', 200, 0
+);
+
+-- PREP: engine_pull_loop_terminations
+-- §run-scheme — sibling runs' loops that reached a terminal status since this run last
+-- looked (the loop-termination ambient delta). Carries terminal_message — the SEND[200]
+-- deliverable or the abandonment reason. Excludes this run's own loops.
+SELECT l.run_id, r.name AS run_name, l.status, l.prompt, l.terminal_message
+FROM loops l
+JOIN runs r ON r.id = l.run_id
+WHERE r.session_id = $session_id
+  AND l.terminated_at IS NOT NULL
+  AND l.terminated_at > $since
+  AND l.run_id != $run_id
+ORDER BY l.terminated_at;
+
+-- PREP: engine_insert_loop_termination_delta
+-- §run-scheme — materialize a sibling's loop-termination as a FOLDED delta: a SEND
+-- from run:///<name> carrying the terminal status + message (the deliverable).
+-- origin=plurnk, source=the terminated run — uniform with the env-delta.
+INSERT INTO log_entries (
+    run_id, loop_id, turn_id, sequence, origin, source,
+    op, scheme, pathname, tx, mimetype_tx, rx, mimetype_rx, status_rx, expanded
+) VALUES (
+    $run_id, $loop_id, $turn_id, $sequence, 'plurnk', $source,
+    'SEND', 'run', $pathname, '', 'text/plain', $rx, 'text/markdown', $status, 0
+);
+
+-- PREP: engine_entry_tags
+SELECT tag FROM entry_tags WHERE entry_id = $entry_id ORDER BY tag;
+
+-- PREP: engine_render_telemetry_errors
+-- SPEC §telemetry: action-bound failures from the immediately previous turn
+-- are mirrored into the next packet's telemetry.errors[]. Forces the
+-- model to confront 4xx/5xx outcomes instead of letting them rot in
+-- log:///. "Previous turn" = sequence one below the currently-open one
+-- (turn-as-container model: the current turn exists with status=102
+-- when this query fires, so we explicitly look one back).
+SELECT
+    le.op, le.sequence, le.status_rx, le.rx, le.mimetype_rx,
+    le.scheme, le.pathname,
+    t.sequence AS turn_seq, l.sequence AS loop_seq
+FROM log_entries le
+JOIN turns t ON t.id = le.turn_id
+JOIN loops l ON l.id = le.loop_id
+WHERE le.loop_id = $loop_id
+  AND le.status_rx >= 400
+  AND t.sequence = $current_turn_seq - 1
+ORDER BY le.sequence;
+
+-- PREP: engine_grinder_prior_turn_logs
+-- §grinder pass 1 (prior-turn rollback): the immediately-prior turn's still-open
+-- log entries — the latest emissions that pushed the packet over. Folding them
+-- (collapse to coordinate, not deleting) lightens the render; bodies persist, re-OPENable.
+SELECT le.id, le.scheme
+FROM log_entries le
+WHERE le.loop_id = $loop_id AND le.expanded = 1
+  AND le.turn_id = (SELECT MAX(id) FROM turns WHERE loop_id = $loop_id AND id < $turn_id);
+
+-- PREP: engine_grinder_fold_prior_turn_logs
+-- §grinder pass 1: fold the prior turn's still-open logs in one set-op (same WHERE
+-- as engine_grinder_prior_turn_logs above). Rows + bodies stay, re-OPENable.
+UPDATE log_entries SET expanded = 0
+WHERE loop_id = $loop_id AND expanded = 1
+  AND turn_id = (SELECT MAX(id) FROM turns WHERE loop_id = $loop_id AND id < $turn_id);
+
+-- PREP: engine_fold_log_entry
+-- §prompt-fold (User Note 6): fold a single log row by id — collapse to its
+-- coordinate, body elided in the render, re-OPENable. Used for the foisted prompt
+-- EDIT, which duplicates packet.user.prompt: logged for forensics, born folded.
+UPDATE log_entries SET expanded = 0 WHERE id = $id;
+
+-- PREP: engine_render_log
+-- Render-time log assembly (SPEC §packet packet.system.log).
+-- Yields log_entries for the whole RUN — the conversation's working
+-- memory carries across loops within a session's run, not just the
+-- current loop. Coordinate is log:///<loop_seq>/<turn_seq>/<sequence>/<op>.
+-- Status 202 entries in state='proposed' are model-invisible until resolved.
+-- `expanded = 0` rows are FOLDED — listed but collapsed to their coordinate
+-- (FOLD); the renderer elides the body. §open-fold: folded rows stay listed, re-OPENable.
+SELECT
+    l.sequence  AS loop_seq,
+    t.sequence  AS turn_seq,
+    le.sequence,
+    -- le.origin is attribution, never a render filter; the run's actor — §actor-boundary-origin-not-filter §machine-processes-run-origin
+    le.origin,
+    le.op, le.suffix, le.signal,
+    le.scheme, le.username, le.password,
+    le.hostname, le.port, le.pathname,
+    le.params, le.fragment,
+    le.status_rx, le.rx, le.mimetype_rx,
+    le.tx, le.mimetype_tx,
+    le.state, le.outcome, le.expanded, le.source
+FROM log_entries le
+JOIN turns t ON t.id = le.turn_id
+JOIN loops l ON l.id = le.loop_id
+-- WHERE renders exactly one run's log — §actor-boundary-isolation §machine-processes-run-is-its-log
+-- the AND NOT clause keeps proposed (202) rows hidden until resolved — §proposal-proposed-hidden
+WHERE le.run_id = $run_id
+  AND NOT (le.status_rx = 202 AND le.state = 'proposed')
+ORDER BY l.sequence, t.sequence, le.sequence;
+
+-- PREP: engine_insert_log_entry
+-- Default state='resolved' covers the common path (non-proposing schemes
+-- return their final status immediately). Status 202 + state='proposed'
+-- triggers the proposal lifecycle (engine pauses dispatch; client resolves
+-- via loop/resolve RPC; entry transitions through engine_resolve_log_entry).
+INSERT INTO log_entries (
+    run_id, loop_id, turn_id, sequence, origin, source,
+    op, suffix, signal,
+    scheme, username, password, hostname, port,
+    pathname, params, fragment, lineMarker,
+    tx, mimetype_tx, rx, mimetype_rx, status_rx, tokens,
+    state, outcome, attrs
+) VALUES (
+    $run_id, $loop_id, $turn_id, $sequence, $origin, $source,
+    $op, $suffix, $signal,
+    $scheme, $username, $password, $hostname, $port,
+    $pathname, $params, $fragment, $lineMarker,
+    $tx, $mimetype_tx, $rx, $mimetype_rx, $status_rx, $tokens,
+    $state, $outcome, $attrs
+)
+RETURNING id;
+
+-- PREP: engine_resolve_log_entry
+-- Transitions a proposed log entry to its terminal state. Used by the
+-- proposal lifecycle (loop/resolve RPC, YOLO auto-accept, timeout, abort).
+-- Updates status_rx + rx + state + outcome atomically.
+UPDATE log_entries
+   SET state = $state,
+       outcome = $outcome,
+       status_rx = $status_rx,
+       rx = $rx
+ WHERE id = $id
+   AND state = 'proposed';

package/dist/core/ExecutorRegistry.d.ts

@@ -17,10 +17,12 @@ export interface RegistryEntry {
 }
 export default class ExecutorRegistry {
     #private;
-    constructor(byTag: ReadonlyMap<string, RegistryEntry>);
-    static build({ defaultRuntime, probeTimeoutMs, discoverFn, load }?: {
+    constructor(byTag: ReadonlyMap<string, RegistryEntry>, attributions?: readonly string[]);
+    attributions(): string[];
+    static build({ defaultRuntime, probeTimeoutMs, cwd, discoverFn, load }?: {
         defaultRuntime?: string | null;
         probeTimeoutMs?: number;
+        cwd?: string;
         discoverFn?: () => Promise<{
             registry: ReadonlyMap<string, {
                 runtime: string;

package/dist/core/ExecutorRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ExecutorRegistry.d.ts","sourceRoot":"","sources":["../../src/core/ExecutorRegistry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,mBAAmB,EAAoB,MAAM,sBAAsB,CAAC;AAI7H,MAAM,WAAW,QAAQ;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;IACtD,GAAG,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACzC,KAAK,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACtC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAAC;CACzC;AAED,MAAM,WAAW,aAAa;IAC1B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAGvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAGzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAWD,MAAM,CAAC,OAAO,OAAO,gBAAgB;;gBAGrB,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC;WAIxC,KAAK,CAAC,EAAE,cAAqB,EAAE,cAAqB,EAAE,UAAqB,EAAE,IAAuD,EAAE,GAAE;QACjJ,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC/B,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC;YAAE,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE;gBAAE,OAAO,EAAE,MAAM,CAAC;gBAAC,KAAK,EAAE,MAAM,CAAC;gBAAC,OAAO,CAAC,EAAE,MAAM,CAAC;gBAAC,aAAa,CAAC,EAAE,MAAM,CAAC;gBAAC,WAAW,EAAE,MAAM,CAAA;aAAE,CAAC,CAAC;YAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;SAAE,CAAC,CAAC;QACrL,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;KACxC,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAiElC,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAO7C,iBAAiB,IAAI,SAAS,MAAM,EAAE;CAKzC"}
+{"version":3,"file":"ExecutorRegistry.d.ts","sourceRoot":"","sources":["../../src/core/ExecutorRegistry.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,EAAE,mBAAmB,EAAoB,MAAM,sBAAsB,CAAC;AAK7H,MAAM,WAAW,QAAQ;IACrB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,IAAI,QAAQ,IAAI,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC;IACtD,GAAG,CAAC,IAAI,EAAE,QAAQ,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACzC,KAAK,IAAI,OAAO,CAAC,mBAAmB,CAAC,CAAC;IACtC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAAC;CACzC;AAED,MAAM,WAAW,aAAa;IAC1B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IAGvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAGzB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;CACvC;AAWD,MAAM,CAAC,OAAO,OAAO,gBAAgB;;gBAIrB,KAAK,EAAE,WAAW,CAAC,MAAM,EAAE,aAAa,CAAC,EAAE,YAAY,GAAE,SAAS,MAAM,EAAO;IAO3F,YAAY,IAAI,MAAM,EAAE;WAEX,KAAK,CAAC,EAAE,cAAqB,EAAE,cAAqB,EAAE,GAAG,EAAE,UAAU,EAAE,IAAuD,EAAE,GAAE;QAC3I,cAAc,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC/B,cAAc,CAAC,EAAE,MAAM,CAAC;QACxB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC;YAAE,QAAQ,EAAE,WAAW,CAAC,MAAM,EAAE;gBAAE,OAAO,EAAE,MAAM,CAAC;gBAAC,KAAK,EAAE,MAAM,CAAC;gBAAC,OAAO,CAAC,EAAE,MAAM,CAAC;gBAAC,aAAa,CAAC,EAAE,MAAM,CAAC;gBAAC,WAAW,EAAE,MAAM,CAAA;aAAE,CAAC,CAAC;YAAC,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;SAAE,CAAC,CAAC;QACrL,IAAI,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;KACxC,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAqElC,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,aAAa,GAAG,SAAS;IAO7C,iBAAiB,IAAI,SAAS,MAAM,EAAE;CAKzC"}

package/dist/core/ExecutorRegistry.js

@@ -7,6 +7,7 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
     return path;
 };
 import { discover } from "@plurnk/plurnk-execs";
+import PluginAttribution from "./plugin-attribution.js";
 // Boot-time runtime registry. Discovers installed @plurnk/plurnk-execs-*
 // siblings (plurnk.kind:"exec") and probes each runtime TAG independently —
 // one executor instance per tag (this.runtime = the tag), so a multi-tag
@@ -18,11 +19,16 @@ import { discover } from "@plurnk/plurnk-execs";
 // plurnk-service#181, #185.
 export default class ExecutorRegistry {
     #byTag;
-    constructor(byTag) {
+    #attributions; // #249 — declared attribution tags of discovered exec packages
+    constructor(byTag, attributions = []) {
         this.#byTag = byTag;
+        this.#attributions = attributions;
     }
-    static async build({ defaultRuntime = null, probeTimeoutMs = 3000, discoverFn = discover, load = (name) => import(__rewriteRelativeImportExtension(name)) } = {}) {
-        const { registry: discovered, skipped = [] } = await discoverFn();
+    // #249 — declared attribution tags of the discovered exec packages (opaque; the engine
+    // unions these across plugin families onto the generate() `attributions` wire).
+    attributions() { return [...this.#attributions]; }
+    static async build({ defaultRuntime = null, probeTimeoutMs = 3000, cwd, discoverFn, load = (name) => import(__rewriteRelativeImportExtension(name)) } = {}) {
+        const { registry: discovered, skipped = [] } = await (discoverFn ?? (() => discover({ cwd })))();
         // #229 trust gate: discover() skips untrusted third-party packages
         // (PLURNK_PLUGINS_TRUSTED_ONLY) and reports them here — note each, mirror
         // of SchemeRegistry's untrusted-scheme warning. Discovered, not loaded.
@@ -50,7 +56,11 @@ export default class ExecutorRegistry {
             });
         }
         ExecutorRegistry.#assertDefaultUsable(byTag, defaultRuntime);
-        return new ExecutorRegistry(byTag);
+        // #249 — collect attribution per DISTINCT package (a multi-tag package — -common's
+        // sh/perl/ruby — shares one manifest); fail-hard if any claims the reserved @plurnk/.
+        const packages = new Set([...discovered.values()].map((info) => info.packageName));
+        const attributions = [...packages].flatMap((pkg) => PluginAttribution.read(pkg));
+        return new ExecutorRegistry(byTag, attributions);
     }
     // A configured default runtime that can't run is an operator misconfig the
     // boot must surface, not hide behind a silent fallback.

package/dist/core/ExecutorRegistry.js.map

@@ -1 +1 @@
-{"version":3,"file":"ExecutorRegistry.js","sourceRoot":"","sources":["../../src/core/ExecutorRegistry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"ExecutorRegistry.js","sourceRoot":"","sources":["../../src/core/ExecutorRegistry.ts"],"names":[],"mappings":"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"}

package/dist/core/SchemeRegistry.d.ts

@@ -15,6 +15,7 @@ export default class SchemeRegistry {
     }>;
     transformSections(sections: PacketSection[]): Promise<PacketSection[]>;
     discoverExternal(cwd?: string): Promise<void>;
+    attributions(): string[];
     resolveForLoop(flags: LoopFlags): Set<string>;
 }
 //# sourceMappingURL=SchemeRegistry.d.ts.map

package/dist/core/SchemeRegistry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SchemeRegistry.d.ts","sourceRoot":"","sources":["../../src/core/SchemeRegistry.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAGtD,MAAM,CAAC,OAAO,OAAO,cAAc;;;IAkB/B,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAK7C,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAErC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAEjC,IAAI,IAAI,MAAM,EAAE;IAOhB,KAAK,IAAI,MAAM;IA0Bf,IAAI,IAAI,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAc1C,iBAAiB,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAiBtE,gBAAgB,CAAC,GAAG,GAAE,MAAsB,GAAG,OAAO,CAAC,IAAI,CAAC;IAelE,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG,GAAG,CAAC,MAAM,CAAC;CAGhD"}
+{"version":3,"file":"SchemeRegistry.d.ts","sourceRoot":"","sources":["../../src/core/SchemeRegistry.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAItD,MAAM,CAAC,OAAO,OAAO,cAAc;;;IAmB/B,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,IAAI;IAK7C,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAErC,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAI1B,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAEjC,IAAI,IAAI,MAAM,EAAE;IAWhB,KAAK,IAAI,MAAM;IAcf,IAAI,IAAI,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAc1C,iBAAiB,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,OAAO,CAAC,aAAa,EAAE,CAAC;IAiBtE,gBAAgB,CAAC,GAAG,GAAE,MAAsB,GAAG,OAAO,CAAC,IAAI,CAAC;IAgBlE,YAAY,IAAI,MAAM,EAAE;IAIxB,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG,GAAG,CAAC,MAAM,CAAC;CAGhD"}

package/dist/core/SchemeRegistry.js

@@ -16,12 +16,14 @@ import File from "../schemes/File.js";
 import Run from "../schemes/Run.js";
 import ResolveForLoop from "./resolveForLoop.js";
 import { SchemeDiscovery } from "@plurnk/plurnk-schemes";
+import PluginAttribution from "./plugin-attribution.js";
 export default class SchemeRegistry {
     // Heterogeneous handler store — in-tree schemes take PlurnkSchemeContext, external
     // siblings the DB-free SchemeCtx of the imported SchemeHandler; the common supertype
     // is `object`. Dispatch (Engine.#run) borrows SchemeHandler's op-key set, not its ctx.
     #handlers = new Map();
     #external = new Set();
+    #attributions = []; // #249 — declared attribution tags of discovered external schemes
     constructor() {
         this.register("plurnk", new Plurnk());
         this.register("log", new Log());
@@ -43,31 +45,26 @@ export default class SchemeRegistry {
     // DB-free SchemeCtx (caps), not the in-tree PlurnkSchemeContext.
     isExternal(name) { return this.#external.has(name); }
     list() { return [...this.#handlers.keys()].toSorted(); }
-    // Scheme-education catalogue, injected into the model's packet at packet-time
-    // (grammar 0.49+ teaches grammar/dialects only, not the scheme set — grammar#239).
-    // Each registered handler contributes its `static teach` (the semantics/when-to-use
-    // blurb) plus a one-line summary derived from `static manifest` (channels, default
-    // channel, who may write). Handlers with no `teach` are skipped. Insertion order.
+    // The scheme directory — the `schemes` packet section (below tools). grammar
+    // 0.49+ teaches grammar/dialects only, not the scheme set (grammar#239), so the
+    // service advertises what schemes exist at packet-time. Each handler that ships a
+    // `manifest.example` contributes ONE terse line — its canonical usage — plus a
+    // doc-link when it ships `manifest.documentation` (materialized at
+    // plurnk://docs/<name>.md by loop_run, READ on demand). The verbose semantics live
+    // in that pull doc, not here: terse pushes, depth pulls — exactly the exec tools
+    // sheet's shape (#collectTools). Insertion order; a scheme with no example
+    // (provisional, e.g. skill) is omitted. The doc's token cost rides its manifest entry.
     teach() {
-        const sections = ["## Schemes"];
+        const lines = [];
         for (const [name, handler] of this.#handlers) {
-            const cls = handler.constructor;
-            if (typeof cls.teach !== "string" || cls.teach.length === 0)
+            const manifest = handler.constructor.manifest;
+            const example = manifest?.example;
+            if (typeof example !== "string" || example.length === 0)
                 continue;
-            const manifest = cls.manifest ?? {};
-            const channelNames = Object.keys(manifest.channels ?? {});
-            const channels = channelNames.length > 0 ? channelNames.join(", ") : "none";
-            const defaultChannel = manifest.defaultChannel !== undefined && manifest.defaultChannel.length > 0 ? manifest.defaultChannel : "none";
-            const writableBy = (manifest.writableBy ?? []).join(", ") || "none";
-            // #note12 — the daughter's usage example (inline) + a doc-link to its fuller
-            // documentation when the manifest ships it (optional; in-tree schemes have none
-            // yet, so the link lights up the day plurnk-schemes adds `documentation`, exactly
-            // as execs do today). The doc's token cost rides the manifest entry it materializes.
-            const example = typeof manifest.example === "string" && manifest.example.length > 0 ? `\nExample: ${manifest.example}` : "";
-            const docLink = typeof manifest.documentation === "string" && manifest.documentation.length > 0 ? `\nDocs: plurnk://docs/${name}.md` : "";
-            sections.push(`### \`${name}:///\`\n${cls.teach}\nChannels: ${channels} (default: ${defaultChannel}). Writable by: ${writableBy}.${example}${docLink}`);
+            const docLink = typeof manifest?.documentation === "string" && manifest.documentation.length > 0 ? ` (docs: plurnk://docs/${name}.md)` : "";
+            lines.push(`* ${name}:/// ${example}${docLink}`);
         }
-        return sections.join("\n\n");
+        return lines.join("\n");
     }
     // #note12 — schemes that ship a `documentation` string, for materialization at
     // plurnk:///docs/<name>.md. Optional + currently none in-tree; future-proofs the link.
@@ -113,8 +110,12 @@ export default class SchemeRegistry {
             const mod = await import(__rewriteRelativeImportExtension(packageName));
             this.register(name, new mod.default());
             this.#external.add(name);
+            this.#attributions.push(...PluginAttribution.read(packageName)); // #249 — fail-hard if it claims @plurnk/
         }
     }
+    // #249 — declared attribution tags of the discovered external schemes (opaque; the
+    // engine unions these across plugin families onto the generate() `attributions` wire).
+    attributions() { return [...this.#attributions]; }
     // Active set under the given loop flags (SPEC §engine-rails). Delegates to
     // the in-tree ResolveForLoop utility.
     resolveForLoop(flags) {

package/dist/core/SchemeRegistry.js.map

@@ -1 +1 @@
-{"version":3,"file":"SchemeRegistry.js","sourceRoot":"","sources":["../../src/core/SchemeRegistry.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"SchemeRegistry.js","sourceRoot":"","sources":["../../src/core/SchemeRegistry.ts"],"names":[],"mappings":"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"}

package/dist/core/fork.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fork.d.ts","sourceRoot":"","sources":["../../src/core/fork.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,EAAE,EAAc,MAAM,SAAS,CAAC;AAE9C,MAAM,CAAC,OAAO,OAAO,IAAI;WACR,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CAsCjF"}
+{"version":3,"file":"fork.d.ts","sourceRoot":"","sources":["../../src/core/fork.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,EAAE,EAAc,MAAM,SAAS,CAAC;AAE9C,MAAM,CAAC,OAAO,OAAO,IAAI;WACR,IAAI,CAAC,EAAE,EAAE,EAAE,EAAE,WAAW,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;CA6CjF"}

package/dist/core/fork.js

@@ -31,7 +31,14 @@ export default class Fork {
         const turns = await db.fork_get_turns.all({ run_id: parentRunId });
         const turnMap = new Map();
         for (const { id, loop_id, ...rest } of turns) {
-            const nt = await db.fork_insert_turn.get({ ...rest, loop_id: loopMap.get(loop_id) });
+            // #254 — a fork inherits the parent's log for context but spends no new money:
+            // the copied turns are history, not fresh generations. Zero their usage so the
+            // cost-rollup triggers add nothing — the session total stays true lifetime spend
+            // (no double-count) and the branch's cost_pico accrues only what IT generates.
+            const nt = await db.fork_insert_turn.get({
+                ...rest, usage_prompt: 0, usage_completion: 0, usage_cached: 0, usage_cost_pico: 0,
+                loop_id: loopMap.get(loop_id),
+            });
             if (nt === undefined)
                 throw new Error("fork: turn insert returned no row");
             turnMap.set(id, nt.id);

package/dist/core/fork.js.map

@@ -1 +1 @@
-{"version":3,"file":"fork.js","sourceRoot":"","sources":["../../src/core/fork.ts"],"names":[],"mappings":"AAAA,4EAA4E;AAC5E,EAAE;AACF,iFAAiF;AACjF,+EAA+E;AAC/E,gFAAgF;AAChF,6EAA6E;AAC7E,oFAAoF;AACpF,2EAA2E;AAI3E,MAAM,CAAC,OAAO,OAAO,IAAI;IACrB,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,EAAM,EAAE,WAAmB,EAAE,IAAa;QACxD,MAAM,MAAM,GAAG,MAAO,EAAE,CAAC,YAA2B,CAAC,GAAG,CAAuD,EAAE,EAAE,EAAE,WAAW,EAAE,CAAC,CAAC;QACpI,IAAI,MAAM,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,aAAa,WAAW,YAAY,CAAC,CAAC;QAEhF,sFAAsF;QACtF,MAAM,MAAM,GAAG,MAAO,EAAE,CAAC,eAA8B,CAAC,GAAG,CAAiB;YACxE,UAAU,EAAE,MAAM,CAAC,UAAU,EAAE,IAAI,EAAE,IAAI,IAAI,GAAG,MAAM,CAAC,IAAI,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM;SACxH,CAAC,CAAC;QACH,IAAI,MAAM,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;QACrF,MAAM,WAAW,GAAG,MAAM,CAAC,EAAE,CAAC;QAE9B,8CAA8C;QAC9C,MAAM,KAAK,GAAG,MAAO,EAAE,CAAC,cAA6B,CAAC,GAAG,CAAkF,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;QACpK,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;QAC1C,KAAK,MAAM,CAAC,IAAI,KAAK,EAAE,CAAC;YACpB,MAAM,EAAE,GAAG,MAAO,EAAE,CAAC,gBAA+B,CAAC,GAAG,CAAiB,EAAE,MAAM,EAAE,WAAW,EAAE,QAAQ,EAAE,CAAC,CAAC,QAAQ,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC,KAAK,EAAE,CAAC,CAAC;YAC5K,IAAI,EAAE,KAAK,SAAS;gBAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;YAC3E,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;QAC7B,CAAC;QAED,gEAAgE;QAChE,MAAM,KAAK,GAAG,MAAO,EAAE,CAAC,cAA6B,CAAC,GAAG,CAAwD,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;QAC1I,MAAM,OAAO,GAAG,IAAI,GAAG,EAAkB,CAAC;QAC1C,KAAK,MAAM,EAAE,EAAE,EAAE,OAAO,EAAE,GAAG,IAAI,EAAE,IAAI,KAAK,EAAE,CAAC;YAC3C,MAAM,EAAE,GAAG,MAAO,EAAE,CAAC,gBAA+B,CAAC,GAAG,CAAiB,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;YACrH,IAAI,EAAE,KAAK,SAAS;gBAAE,MAAM,IAAI,KAAK,CAAC,mCAAmC,CAAC,CAAC;YAC3E,OAAO,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,CAAC,EAAE,CAAC,CAAC;QAC3B,CAAC;QAED,oEAAoE;QACpE,yCAAyC;QACzC,MAAM,OAAO,GAAG,MAAO,EAAE,CAAC,oBAAmC,CAAC,GAAG,CAA6D,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC;QACvJ,KAAK,MAAM,CAAC,IAAI,OAAO,EAAE,CAAC;YACtB,MAAO,EAAE,CAAC,qBAAoC,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;QACxJ,CAAC;QAED,OAAO,WAAW,CAAC;IACvB,CAAC;CACJ"}
+{"version":3,"file":"fork.js","sourceRoot":"","sources":["../../src/core/fork.ts"],"names":[],"mappings":"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"}

package/dist/core/fork.sql

@@ -0,0 +1,50 @@
+-- Fork a run: deep-copy its log into a NEW run in the SAME session (SPEC §machine-processes —
+-- branch the log, share the world). loops → turns → entries are copied with their
+-- fold-state (expanded) and attribution (origin/source) intact; only the run/loop/
+-- turn ids are remapped. Nothing of the world is copied (§machine-processes-fork-shares-the-world) — the session's entries and
+-- overlay are shared. The §env-delta reconciliation snapshot (run_watermarks) is NOT
+-- copied; the branch first-sights its world like any fresh run.
+
+-- PREP: fork_get_run
+SELECT session_id, name, origin FROM runs WHERE id = $id;
+
+-- PREP: fork_insert_run
+-- A new run in the parent's session; lineage recorded via parent_run_id (§lifecycle-terms).
+INSERT INTO runs (session_id, name, parent_run_id, origin)
+VALUES ($session_id, $name, $parent_run_id, $origin)
+RETURNING id;
+
+-- PREP: fork_get_loops
+SELECT id, sequence, status, prompt, flags
+FROM loops WHERE run_id = $run_id ORDER BY id;
+
+-- PREP: fork_insert_loop
+INSERT INTO loops (run_id, sequence, status, prompt, flags)
+VALUES ($run_id, $sequence, $status, $prompt, $flags)
+RETURNING id;
+
+-- PREP: fork_get_turns
+-- All turns across the run's loops, in order — loop_id is remapped by the caller.
+SELECT t.id, t.loop_id, t.sequence, t.timestamp, t.status,
+       t.usage_prompt, t.usage_completion, t.usage_cached, t.usage_cost_pico,
+       t.packet, t.finish_reason, t.model
+FROM turns t JOIN loops l ON l.id = t.loop_id
+WHERE l.run_id = $run_id ORDER BY t.id;
+
+-- PREP: fork_insert_turn
+INSERT INTO turns (loop_id, sequence, timestamp, status, usage_prompt, usage_completion, usage_cached, usage_cost_pico, packet, finish_reason, model)
+VALUES ($loop_id, $sequence, $timestamp, $status, $usage_prompt, $usage_completion, $usage_cached, $usage_cost_pico, $packet, $finish_reason, $model)
+RETURNING id;
+
+-- PREP: fork_get_log_entries
+-- Everything but the row id and run_id (run_id is the branch's; loop_id/turn_id are
+-- remapped by the caller). origin/source (attribution) and expanded (fold-state) ride along. §machine-processes-fork-copies-the-log
+SELECT loop_id, turn_id, sequence, at, origin, source, op, suffix, signal,
+       scheme, username, password, hostname, port, pathname, params, fragment,
+       lineMarker, tx, mimetype_tx, rx, mimetype_rx, status_rx, tokens,
+       state, outcome, attrs, expanded
+FROM log_entries WHERE run_id = $run_id ORDER BY id;
+
+-- PREP: fork_insert_log_entry
+INSERT INTO log_entries (run_id, loop_id, turn_id, sequence, at, origin, source, op, suffix, signal, scheme, username, password, hostname, port, pathname, params, fragment, lineMarker, tx, mimetype_tx, rx, mimetype_rx, status_rx, tokens, state, outcome, attrs, expanded)
+VALUES ($run_id, $loop_id, $turn_id, $sequence, $at, $origin, $source, $op, $suffix, $signal, $scheme, $username, $password, $hostname, $port, $pathname, $params, $fragment, $lineMarker, $tx, $mimetype_tx, $rx, $mimetype_rx, $status_rx, $tokens, $state, $outcome, $attrs, $expanded);

package/dist/core/plugin-attribution.d.ts

@@ -0,0 +1,5 @@
+export default class PluginAttribution {
+    static normalize(raw: unknown, packageName: string): string[];
+    static read(packageName: string): string[];
+}
+//# sourceMappingURL=plugin-attribution.d.ts.map

package/dist/core/plugin-attribution.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-attribution.d.ts","sourceRoot":"","sources":["../../src/core/plugin-attribution.ts"],"names":[],"mappings":"AAQA,MAAM,CAAC,OAAO,OAAO,iBAAiB;IAIlC,MAAM,CAAC,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE;IAkB7D,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,EAAE;CAS7C"}

package/dist/core/plugin-attribution.js

@@ -0,0 +1,39 @@
+// #249 — plugin attribution. A plugin declares an opaque tag in its package.json
+// (plurnk.attribution: string | string[]) that rides the generate() attributions wire.
+// @plurnk/ is reserved: only a @plurnk/-scoped package may declare a @plurnk/ tag.
+import { createRequire } from "node:module";
+const RESERVED_PREFIX = "@plurnk/";
+export default class PluginAttribution {
+    // Normalize a raw `plurnk.attribution` value to a tag list AND enforce the reservation.
+    // Pure (no I/O) so the contract is unit-testable. A plugin claiming the reserved
+    // namespace is a fail-hard contract violation, not a silently-dropped tag.
+    static normalize(raw, packageName) {
+        if (raw === undefined || raw === null)
+            return [];
+        const tags = Array.isArray(raw) ? raw : [raw];
+        const firstParty = packageName.startsWith(RESERVED_PREFIX);
+        const out = [];
+        for (const tag of tags) {
+            if (typeof tag !== "string" || tag.length === 0) {
+                throw new Error(`plugin '${packageName}': plurnk.attribution must be a non-empty string or string[]`);
+            }
+            if (tag.startsWith(RESERVED_PREFIX) && !firstParty) {
+                throw new Error(`plugin '${packageName}': '${RESERVED_PREFIX}' is reserved for ${RESERVED_PREFIX}-scoped packages — '${packageName}' cannot claim '${tag}'`);
+            }
+            out.push(tag);
+        }
+        return out;
+    }
+    // [] when the manifest can't be resolved (strict `exports` with no `./package.json`).
+    static read(packageName) {
+        let manifest;
+        try {
+            manifest = createRequire(import.meta.url)(`${packageName}/package.json`);
+        }
+        catch {
+            return [];
+        }
+        return PluginAttribution.normalize(manifest?.plurnk?.attribution, packageName);
+    }
+}
+//# sourceMappingURL=plugin-attribution.js.map