@plurnk/plurnk-meta 1.21.1 → 1.23.0

package/README.md

@@ -1,6 +1,6 @@
 # @plurnk/plurnk-meta
 
-The plurnk metaproject layer, published — what the family shares that no single member owns.
+What plurnk's packages share that no single package owns: plugin discovery and trust, and the teaching material the service gives models.
 
 **Membership primitives** (`import Meta from "@plurnk/plurnk-meta"`): the shared implementation of exact family identity, trust, attribution normalization, enumeration, and root resolution consumed by the four family-owned scanners (schemes, mimetypes, providers, execs). [SPEC.md](./SPEC.md) owns the complete contract ({§plugin-discovery}).
 
@@ -14,6 +14,4 @@ The plurnk metaproject layer, published — what the family shares that no singl
 
 **The teaching corpus**: authored policy, an optional Recap, the Plurnk skill entry, and built-in scheme references resolved from this installed package. Meta owns the source bytes and membership; core owns admission, resource composition, and projection. See [`CORPUS.md`](./CORPUS.md) and {§teaching-corpus}.
 
-[`DOGFOOD.md`](./DOGFOOD.md) defines the whole-product, outside-client acceptance gate for daily-driver and release readiness.
-
 Third-party plugin authors: your package is discovered under any scope through one string `plurnk.kind`, enumerated by these primitives, and gated before import by the operator's trust knob — no registration with us required. An admitted package may declare always-on `plurnk.attribution` tags and its loaded plugin object may decide per provider attempt whether to return additional tags from `attributions(context)` ({§plugin-attribution}). MIT.

package/SPEC.md

@@ -93,6 +93,41 @@ Coordinated capabilities spanning families use explicit daemon-module
 composition ({§module-lifecycle}); a multi-kind manifest is not a parallel
 module mechanism.
 
+### §env-knob One environment reader
+
+`Knob` reads a declared key from the system environment by name and nothing
+else: `text`, `list`, `flag` (exactly `0` or `1`), `choice` (one of a
+vocabulary), `percent` (`80%` is 0.8) and `integer(name, floor)` (a safe
+integer of at least the floor, which bounds what the operator may say and is
+never a value used in the operator's place). An unset key is a broken floor
+and an invalid value is the operator's mistake; both crash naming the key.
+No reader accepts a fallback: a signature that could carry one is a second
+home for a choice. Every package reads its knobs through it, so the failure
+wording has one home.
+
+### §error-detail-bound One diagnostic-preview bound
+
+`new ErrorDetail(knob)` binds a package's model-facing diagnostic preview to
+that package's `*_ERROR_DETAIL_LIMIT` knob, read through {§env-knob}:
+`preview(value)` keeps at most that many characters of an error's message
+(or a value's string form) and marks the cut with `...`. The bound is read at
+each preview; an unset or invalid bound crashes by name at the first
+diagnostic, never degrades into an unbounded one.
+
+### §plugin-manifest-read One package.json read
+
+`Meta.readManifest(dir, kind)` is the one read of a package's family claim:
+its `package.json`, parsed, with a `plurnk` object declaring exactly that
+`kind` ({§plugin-family-kind}). It answers `null` for a missing or
+malformed manifest, a non-object, no `plurnk` object, or another family —
+none of those is a package of that family, and a scanner skips them without
+evidence. The result carries the manifest path, the package name when
+`name` is a non-empty string (otherwise `null`; what an unnamed package is
+remains the family's decision), and the `plurnk` object untouched: family
+fields are validated by the family, after the trust gate. A scanner that
+passes an `AbortSignal` receives the abort; it is never masked as an
+unreadable directory. No family reads a manifest any other way.
+
 ### §plugin-attribution Plugin-authored attribution tags
 
 | Surface                 | Contract                                                                                                                                                                                                                                  |
@@ -129,3 +164,13 @@ does not crash discovery: the family result preserves its package identity as
 skipped evidence. The composed host decides how to present that evidence.
 Direct framework consumers receive the same safe load boundary and can choose
 their own presentation.
+
+## §observed-span Redaction-first spans
+
+`observed(tracer, name, attributes, fn, options?)` and its synchronous twin wrap
+one span around `fn` on the caller's tracer: attributes admit strings (capped at
+300 characters), numbers and booleans and drop everything else; a thrown error
+marks the span `ERROR` and records only `error.type`, the error's class name,
+never its message. Every instrumented package binds these to its own tracer
+rather than declaring a second helper; prompts, payloads and arbitrary URLs never
+reach a span through them.

package/dist/ErrorDetail.d.ts

@@ -0,0 +1,7 @@
+export default class ErrorDetail {
+    #private;
+    constructor(knob: string);
+    limit(): number;
+    preview(value: unknown): string;
+}
+//# sourceMappingURL=ErrorDetail.d.ts.map

package/dist/ErrorDetail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorDetail.d.ts","sourceRoot":"","sources":["../src/ErrorDetail.ts"],"names":[],"mappings":"AAIA,MAAM,CAAC,OAAO,OAAO,WAAW;;IAG5B,YAAY,IAAI,EAAE,MAAM,EAEvB;IAED,KAAK,IAAI,MAAM,CAEd;IAED,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAI9B;CACJ"}

package/dist/ErrorDetail.js

@@ -0,0 +1,18 @@
+import Knob from "./Knob.js";
+// {§error-detail-bound} — a package's model-facing diagnostic detail is bounded by that package's
+// knob, read through the one reader: an unset or invalid bound crashes by name, never degrades.
+export default class ErrorDetail {
+    #knob;
+    constructor(knob) {
+        this.#knob = knob;
+    }
+    limit() {
+        return Knob.integer(this.#knob, 0);
+    }
+    preview(value) {
+        const text = value instanceof Error ? value.message : String(value);
+        const limit = this.limit();
+        return text.length > limit ? `${text.slice(0, limit)}...` : text;
+    }
+}
+//# sourceMappingURL=ErrorDetail.js.map

package/dist/ErrorDetail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ErrorDetail.js","sourceRoot":"","sources":["../src/ErrorDetail.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,kGAAkG;AAClG,gGAAgG;AAChG,MAAM,CAAC,OAAO,OAAO,WAAW;IACnB,KAAK,CAAS;IAEvB,YAAY,IAAY;QACpB,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACtB,CAAC;IAED,KAAK;QACD,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC;IACvC,CAAC;IAED,OAAO,CAAC,KAAc;QAClB,MAAM,IAAI,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QACpE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC;QAC3B,OAAO,IAAI,CAAC,MAAM,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC;IACrE,CAAC;CACJ"}

package/dist/Knob.d.ts

@@ -0,0 +1,9 @@
+export default class Knob {
+    static text(name: string): string;
+    static list(name: string): string[];
+    static flag(name: string): boolean;
+    static choice<T extends string>(name: string, options: readonly T[]): T;
+    static percent(name: string): number;
+    static integer(name: string, floor: number): number;
+}
+//# sourceMappingURL=Knob.d.ts.map

package/dist/Knob.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Knob.d.ts","sourceRoot":"","sources":["../src/Knob.ts"],"names":[],"mappings":"AAKA,MAAM,CAAC,OAAO,OAAO,IAAI;IACrB,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAIhC;IAGD,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAElC;IAGD,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAIjC;IAGD,MAAM,CAAC,MAAM,CAAC,CAAC,SAAS,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,CAAC,EAAE,GAAG,CAAC,CAMtE;IAGD,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAOnC;IAGD,MAAM,CAAC,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAOlD;CACJ"}

package/dist/Knob.js

@@ -0,0 +1,51 @@
+// {§env-knob} — a knob is read from the system environment, and its value lives on the panel and
+// nowhere else ({§operator-config-only-home}). The floor guarantees every declared key, so an unset
+// key is a broken deployment and an invalid one is the operator's mistake: both crash by name, never
+// degrade. No reader here accepts a value, because a signature that could carry one is a second home
+// for a choice. This is the one reader; a package that spells its own has a second home for the rule.
+export default class Knob {
+    static text(name) {
+        const raw = process.env[name];
+        if (raw === undefined)
+            throw new Error(`${name} is missing from the assembled environment floor.`);
+        return raw;
+    }
+    // A comma list; empty is the empty list.
+    static list(name) {
+        return Knob.text(name).split(",").map((item) => item.trim()).filter((item) => item.length > 0);
+    }
+    // The house switch: exactly 0 or 1.
+    static flag(name) {
+        const raw = Knob.text(name);
+        if (raw !== "0" && raw !== "1")
+            throw new Error(`${name} must be 0 or 1; got ${JSON.stringify(raw)}.`);
+        return raw === "1";
+    }
+    // `options` is the vocabulary the operator chooses from, never a choice made for them.
+    static choice(name, options) {
+        const raw = Knob.text(name);
+        if (!options.includes(raw)) {
+            throw new Error(`${name} must be one of ${options.join(", ")}; got ${JSON.stringify(raw)}.`);
+        }
+        return raw;
+    }
+    // The panel's own notation, a share strictly between nothing and everything: `80%` is 0.8.
+    static percent(name) {
+        const raw = Knob.text(name);
+        const percent = Number(/^([0-9]+(?:\.[0-9]+)?)%$/u.exec(raw)?.[1]);
+        if (!Number.isFinite(percent) || percent <= 0 || percent >= 100) {
+            throw new Error(`${name} must be a percentage in (0, 100); got ${JSON.stringify(raw)}.`);
+        }
+        return percent / 100;
+    }
+    // `floor` is a bound on what the operator may say, never a value used in the operator's place.
+    static integer(name, floor) {
+        const raw = Knob.text(name);
+        const value = Number(raw);
+        if (raw.trim().length === 0 || !Number.isSafeInteger(value) || value < floor) {
+            throw new Error(`${name} must be a safe integer of at least ${floor}; got ${JSON.stringify(raw)}.`);
+        }
+        return value;
+    }
+}
+//# sourceMappingURL=Knob.js.map

package/dist/Knob.js.map

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

package/dist/index.d.ts

@@ -1,8 +1,15 @@
+export { default as Knob } from "./Knob.ts";
+export { default as ErrorDetail } from "./ErrorDetail.ts";
 export interface PackageCandidate {
     dir: string;
     name: string;
 }
 export type PluginKind = "exec" | "mimetype" | "provider" | "scheme" | "http-materializer" | "module";
+export interface PluginManifest {
+    readonly manifestPath: string;
+    readonly packageName: string | null;
+    readonly plurnk: Record<string, unknown>;
+}
 export type PluginAttributionDeclaration = string | string[];
 export type PluginAttribution = readonly string[];
 export type PackageAttributions = ReadonlyMap<string, PluginAttribution>;
@@ -16,6 +23,7 @@ export interface PluginAttributionContext {
 export interface PluginAttributionSource {
     attributions?(context: PluginAttributionContext): PluginAttributionDeclaration | null | undefined;
 }
+export { observed, observedSync } from "./observe.ts";
 export declare const TEACHING_CORPUS: Readonly<{
     readonly policy: "POLICY.md";
     readonly recap: "recap.md";
@@ -28,6 +36,9 @@ export type TeachingCorpusSource = typeof TEACHING_CORPUS.policy | typeof TEACHI
 export default class Meta {
     #private;
     static declaresKind(manifest: unknown, kind: PluginKind): boolean;
+    static readManifest(dir: string, kind: PluginKind, { signal }?: {
+        signal?: AbortSignal;
+    }): Promise<PluginManifest | null>;
     static isTrusted(packageName: string, env?: Record<string, string | undefined>): boolean;
     static normalizeAttribution(raw: unknown, packageName: string): PluginAttribution;
     static runtimeAttribution(source: unknown, context: PluginAttributionContext, packageName: string): PluginAttribution;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAyBA,MAAM,WAAW,gBAAgB;IAC7B,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,GAAG,QAAQ,GAAG,mBAAmB,GAAG,QAAQ,CAAC;AAItG,MAAM,MAAM,4BAA4B,GAAG,MAAM,GAAG,MAAM,EAAE,CAAC;AAC7D,MAAM,MAAM,iBAAiB,GAAG,SAAS,MAAM,EAAE,CAAC;AAClD,MAAM,MAAM,mBAAmB,GAAG,WAAW,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;AAEzE,MAAM,WAAW,wBAAwB;IACrC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,uBAAuB;IACpC,YAAY,CAAC,CAAC,OAAO,EAAE,wBAAwB,GAAG,4BAA4B,GAAG,IAAI,GAAG,SAAS,CAAC;CACrG;AAQD,eAAO,MAAM,eAAe;qBAChB,WAAW;oBACZ,UAAU;oBACV,wBAAwB;;yBARvB,gBAAgB;;EAWjB,CAAC;AAEZ,MAAM,MAAM,oBAAoB,GAC1B,OAAO,eAAe,CAAC,MAAM,GAC7B,OAAO,eAAe,CAAC,KAAK,GAC5B,OAAO,eAAe,CAAC,KAAK,GAC5B,CAAC,OAAO,eAAe,CAAC,UAAU,CAAC,CAAC,MAAM,OAAO,eAAe,CAAC,UAAU,CAAC,CAAC;AAOnF,MAAM,CAAC,OAAO,OAAO,IAAI;;IAGrB,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,UAAU,GAAG,OAAO,CAGhE;IAqBD,MAAM,CAAC,SAAS,CAAC,WAAW,EAAE,MAAM,EAAE,GAAG,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAe,GAAG,OAAO,CAMpG;IAED,MAAM,CAAC,oBAAoB,CAAC,GAAG,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,GAAG,iBAAiB,CAiBhF;IAKD,MAAM,CAAC,kBAAkB,CACrB,MAAM,EAAE,OAAO,EACf,OAAO,EAAE,wBAAwB,EACjC,WAAW,EAAE,MAAM,GACpB,iBAAiB,CAcnB;IAED,MAAM,CAAC,mBAAmB,CAAC,GAAG,KAAK,EAAE,SAAS,iBAAiB,EAAE,GAAG,iBAAiB,CAIpF;IAkCD,OAAa,WAAW,CAAC,cAAc,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAyB5E;IAED,MAAM,CAAC,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CASxD;CACJ"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1,6 +1,13 @@
 // The metaproject layer's membership slice — the mechanics every discovery
 // surface shares ({§plugin-discovery} / {§operator-config-env-defaults}):
 //   - declaresKind:      the ONE package → capability-family representation.
+//   - readManifest:       the ONE package.json read: a family's manifest, or null for
+//                         anything that is not a package of that family. Field
+//                         validation past the family claim is the caller's.
+//   - Knob:               the ONE environment reader: the panel's value by name, or a
+//                         crash by name ({§env-knob}).
+//   - ErrorDetail:        the ONE diagnostic-preview bound, per package knob
+//                         ({§error-detail-bound}).
 //   - isTrusted:          THE trust rule. One implementation; a second definition
 //                         of membership trust anywhere in the family is a bug.
 //   - normalizeAttribution:
@@ -16,16 +23,19 @@
 //                         checkouts escape node_modules via symlink realpaths and
 //                         land on the monorepo root's. Null when nothing is found;
 //                         the fallback is the caller's policy.
-import { readdir } from "node:fs/promises";
+import { readdir, readFile } from "node:fs/promises";
 import { existsSync, readFileSync } from "node:fs";
 import { parseEnv } from "node:util";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+export { default as Knob } from "./Knob.js";
+export { default as ErrorDetail } from "./ErrorDetail.js";
 const SCHEME_TEACHING = Object.freeze({
     worker: "docs/worker.md",
 });
 // {§teaching-corpus} — the authored package membership is one exported fact;
 // consumers decide when and where each required source is projected.
+export { observed, observedSync } from "./observe.js";
 export const TEACHING_CORPUS = Object.freeze({
     policy: "POLICY.md",
     recap: "recap.md",
@@ -42,6 +52,36 @@ export default class Meta {
             return false;
         return manifest.kind === kind;
     }
+    // {§plugin-manifest-read} — null for a missing or malformed package.json, a non-object,
+    // no `plurnk` object, or another family: none of those is a package of this family, and
+    // discovery skips them without a word. An abort is the caller's contract and surfaces.
+    static async readManifest(dir, kind, { signal } = {}) {
+        const manifestPath = path.join(dir, "package.json");
+        let raw;
+        try {
+            raw = await readFile(manifestPath, { encoding: "utf8", signal });
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === "AbortError")
+                throw err;
+            return null;
+        }
+        let pkg;
+        try {
+            pkg = JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+        if (typeof pkg !== "object" || pkg === null)
+            return null;
+        const record = pkg;
+        const plurnk = record.plurnk;
+        if (typeof plurnk !== "object" || plurnk === null || !Meta.declaresKind(plurnk, kind))
+            return null;
+        const packageName = typeof record.name === "string" && record.name.length > 0 ? record.name : null;
+        return { manifestPath, packageName, plurnk: plurnk };
+    }
     // {§operator-config-only-home} — the trust gate is asked while the floor is still being
     // assembled (it decides whose panel joins it), so an unset key cannot mean "the panel said
     // nothing". This package owns the key, so it reads its own panel: the operator's environment

package/dist/index.js.map

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

package/dist/observe.d.ts

@@ -0,0 +1,4 @@
+import { type Span, type SpanOptions, type Tracer } from "@opentelemetry/api";
+export declare const observed: <T>(tracer: Tracer, name: string, attributes: Record<string, unknown>, fn: (span: Span) => Promise<T>, options?: SpanOptions) => Promise<T>;
+export declare const observedSync: <T>(tracer: Tracer, name: string, attributes: Record<string, unknown>, fn: (span: Span) => T, options?: SpanOptions) => T;
+//# sourceMappingURL=observe.d.ts.map

package/dist/observe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observe.d.ts","sourceRoot":"","sources":["../src/observe.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkC,KAAK,IAAI,EAAE,KAAK,WAAW,EAAE,KAAK,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAuC9G,eAAO,MAAM,QAAQ,GAAU,CAAC,UACpB,MAAM,QACR,MAAM,cACA,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,MAC/B,CAAC,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,CAAC,CAAC,YACpB,WAAW,KACtB,OAAO,CAAC,CAAC,CAUX,CAAC;AAEF,eAAO,MAAM,YAAY,GAAI,CAAC,UAClB,MAAM,QACR,MAAM,cACA,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,MAC/B,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC,YACX,WAAW,KACtB,CAUF,CAAC"}

package/dist/observe.js

@@ -0,0 +1,61 @@
+import { context, SpanStatusCode, trace } from "@opentelemetry/api";
+// {§observed-span} — redaction-first span helpers shared by every instrumented package. Callers
+// pass identifiers, counts and statuses only; string values are length-capped as a backstop, and a
+// failure marks the span ERROR with the error's class name, never its message.
+const MAX_STRING_LENGTH = 300;
+const errorType = (error) => {
+    const name = error instanceof Error ? error.constructor.name : typeof error;
+    return name.length <= MAX_STRING_LENGTH ? name : name.slice(0, MAX_STRING_LENGTH);
+};
+const sanitize = (attributes) => {
+    const out = {};
+    for (const [key, value] of Object.entries(attributes)) {
+        if (value === undefined)
+            continue;
+        if (typeof value === "string") {
+            out[key] = value.length <= MAX_STRING_LENGTH ? value : value.slice(0, MAX_STRING_LENGTH);
+        }
+        else if (typeof value === "number" || typeof value === "boolean") {
+            out[key] = value;
+        }
+    }
+    return out;
+};
+const spanOptions = (attributes, options) => ({
+    ...options,
+    attributes: {
+        ...sanitize(attributes),
+        ...(options?.attributes === undefined ? {} : sanitize(options.attributes)),
+    },
+});
+const failed = (span, error) => {
+    span.setAttribute("error.type", errorType(error));
+    span.setStatus({ code: SpanStatusCode.ERROR });
+};
+export const observed = async (tracer, name, attributes, fn, options) => {
+    const span = tracer.startSpan(name, spanOptions(attributes, options));
+    try {
+        return await context.with(trace.setSpan(context.active(), span), () => fn(span));
+    }
+    catch (error) {
+        failed(span, error);
+        throw error;
+    }
+    finally {
+        span.end();
+    }
+};
+export const observedSync = (tracer, name, attributes, fn, options) => {
+    const span = tracer.startSpan(name, spanOptions(attributes, options));
+    try {
+        return fn(span);
+    }
+    catch (error) {
+        failed(span, error);
+        throw error;
+    }
+    finally {
+        span.end();
+    }
+};
+//# sourceMappingURL=observe.js.map

package/dist/observe.js.map

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

package/docs/worker.md

@@ -2,21 +2,23 @@
 
 ## Summary
 
-Coordinate workers, request isolated BARE inference, and manage workspace entries.
+Coordinate workers (WORK, FORK), request isolated BARE inference, and manage workspace entries.
 
 Workers inhabit one workspace. The authority selects a worker; a path selects
 an entry rather than controlling that worker.
 
 | Address | Meaning | Model access |
 | --- | --- | --- |
-| `worker://alice` | Named worker | WORK/FORK create; SEND messages; READ collects; KILL terminates. |
-| `message://alice/ab3d5678` | Retained message | READ/FIND/COPY inspect; SEND replies. Neither EDIT nor KILL changes its source. |
-| `ops://alice/1` | What that loop said, or how it ended | READ/FIND/COPY inspect; source is immutable. |
-| `worker://alice/example.md` | Named scratch entry | Read and write from any worker in the workspace. |
+| `worker://exampleWorkerName` | Named worker | WORK/FORK create; SEND messages; READ collects; KILL terminates. |
+| `message://exampleWorkerName/ab3d5678` | Retained message | READ/FIND/COPY inspect; SEND replies. Neither EDIT nor KILL changes its source. |
+| `ops://exampleWorkerName/1` | What that loop said, or how it ended | READ/FIND/COPY inspect; source is immutable. |
+| `worker://exampleWorkerName/example.md` | Named scratch entry | Read and write from any worker in the workspace. |
 | `worker:///example.md` | Shared commons entry | Read and write. |
 
 The packet's `## Worker` block, below the log, names your worker, its parent
-(`null` at a root), and the loop and turn you are producing. Addresses are
+(`null` at a root), the loop and turn you are producing, and `previousEmission`, the
+address of the program you submitted last: the log rows at that coordinate are its
+receipts. Addresses are
 literal and keep the same meaning when passed to another worker. Scratch
 belongs to the workspace; a namespace does not require a namesake worker.
 Generated references live under `worker:///_plurnk/`, and reference refreshes
@@ -32,6 +34,12 @@ the default channel stays the source, and a pattern matches the channel it
 addresses. The projection follows every source write and is never written
 itself.
 
+A READ of an image, PDF or audio source retains its bytes: on a route whose
+model takes that media, every later packet carries them as a native part
+captioned with the READ's log coordinate, until you KILL that READ row. The
+service never re-sends media; a captioned part is your own earlier READ, not a
+new arrival.
+
 ## Delegation
 
 WORK starts a fresh log with the task body as its prompt; FORK copies your
@@ -43,6 +51,10 @@ an existing worker, even after it finishes. Names match
 worker gives it a follow-up task. `[{"env": {...}}]` on WORK or FORK is the
 child's starting environment (`env.md`).
 
+```FORK (worker://exampleWorkerName) <!-- a sibling that begins with your history -->
+The child's task, continuing from what you already know.
+```
+
 Parents observe a direct child's mutations, messages, executor invocations, and
 worker launches, including failed actions, as rows in their own log.
 Exploration and context curation (NOTE, READ, FIND, BARE, WAIT, and log KILL)
@@ -67,11 +79,11 @@ is empty when an already-delivered answer stands. While live work remains, that
 KILL joins it without cancelling it and delivers no final answer.
 
 Each child task's conclusion wakes its waiting parent and arrives once, as an
-`_plurnk` READ of `ops://alice/1` carrying what the child said: the
+`_plurnk` READ of `ops://exampleWorkerName/1` carrying what the child said: the
 execution outcome, not another message, and not delivered again as a reply. A
 failure retains its status and Problem. READ that address with a scope to
 inspect more of the exact result, even after the child starts another task.
-Bare `READ (worker://alice)` collects the current result instead, naming its
+Bare `READ (worker://exampleWorkerName)` collects the current result instead, naming its
 exact source in `resource`; while the child is running it returns `425`. A
 result does not imply that every task in that worker has finished.
 
@@ -100,11 +112,16 @@ ordinary message from `schedule://<alias>`.
 
 ## BARE inference
 
-BARE makes one isolated call to the child model, not a persistent worker. It
-receives no parent history or tools. Its prompt is the fence body.
+BARE makes one isolated call to the model, not a persistent worker. Nothing
+reaches it but the fence body: no log, no files, no web, no tools, no memory of
+this loop. It answers from the body and the model's own knowledge alone, so it
+cannot look anything up, and what it does not know it will guess. Use it to
+isolate a sub-problem whose complete inputs fit in the body — a long text to
+judge, a tangle to reason through without the log in view — never to search,
+recall, or fetch.
 
 ```BARE
-A self-contained prompt.
+A self-contained prompt, with everything it needs pasted in.
 ```
 
 The prompt is not truncated to fit; provider capacity still applies.
@@ -123,11 +140,11 @@ The worker name is required. Any worker in the workspace can READ these
 sources; `log:///` remains your own context. READ brings the selected source
 into your log, and KILL of that READ curates only its log projection, never the
 original evidence. The current turn's reasoning exists when its OPs execute, so
-`READ (reasoning://alice/1/3) <1,-1>` from `worker://alice` on loop 1,
+`READ (reasoning://exampleWorkerName/1/3) <1,-1>` from `worker://exampleWorkerName` on loop 1,
 turn 3 retains it; a turn that produced no reasoning reads empty, and a turn
 that has not happened returns a missing-source result. READ never requests
 inference. NOTE retains working memory without changing the loop state; only
 NOTE also executes from exposed reasoning, while quoted examples and other
 reasoned operations remain data. Notes are ordinary log items whose read-only
-sources stay searchable (`FIND (note://alice/**) /parser/`) and READable
+sources stay searchable (`FIND (note://exampleWorkerName/**) /parser/`) and READable
 after curation or a FORK.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@plurnk/plurnk-meta",
-  "version": "1.21.1",
-  "description": "The plurnk metaproject layer, published: plugin-membership primitives (the ONE trust rule, scope-agnostic symlink-aware enumeration, deployment-root resolution), the project teaching corpus (personality, Recap, scheme docs), and the home for family tooling.",
+  "version": "1.23.0",
+  "description": "Plugin discovery and trust primitives shared by plurnk plugin families, and the teaching material the plurnk service gives models: policy, Recap, the plurnk skill and scheme references.",
   "keywords": [
     "plurnk",
     "agent-skills",
@@ -13,12 +13,14 @@
   "engines": {
     "node": ">=26"
   },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.1"
+  },
   "files": [
     ".env.defaults",
     "dist/**/*",
     "README.md",
     "SPEC.md",
-    "DOGFOOD.md",
     "CORPUS.md",
     "POLICY.md",
     "recap.md",

package/DOGFOOD.md

@@ -1,94 +0,0 @@
-# Metaproject orientation-readiness gate
-
-This opt-in capstone asks a floor model to inspect an assembled open-project
-forest through the outside client and deliver an evidence-bearing orientation
-report. It is intentionally expensive: a fresh campaign semantically prepares
-the complete forest. Execute it only after the focused package, integration,
-demo, live-model, and modest-candidate paths are healthy—not as a routine
-debugging loop or release gate.
-
-Invoke it with:
-
-```sh
-PLURNK_ACCEPTANCE_PROJECT_ROOT=/path/to/open-project-forest \
-PLURNK_CLIENT_CHECKOUT=/path/to/open-client \
-  npm run readiness:metaproject -- --model <selector> --requiem --preserve
-```
-
-Both paths are explicit preconditions. The runner never guesses a sibling
-checkout or treats another organization under a shared parent directory as
-part of the open project.
-
-This gate does not replace the evidence ladder that qualifies it:
-
-1. Deterministic package and integration coverage proves owned contracts.
-2. An assembled modest-repository candidate smoke proves the production client
-   and daemon can work together.
-3. Focused `live/demo` stories are toy tasks that establish the system is sane
-   enough to test seriously.
-4. The separate bench lane runs real third-party agentic benchmarks and preserves
-   their digest, reasoning, and requiem evidence.
-5. Only after those layers are healthy does this full-forest campaign ask whether
-   PLURNK is ready to develop PLURNK itself.
-
-The canonical `plurnk-service` checkout owns this gate. Its doctrine lives in
-`plurnk-meta` because the report crosses service, contracts, plugins, the
-outside client, project membership, AG-UI, model routing, persistence, and
-forensic digestion.
-
-## Preconditions
-
-- A clean canonical `plurnk-service` checkout with its gate green.
-- The explicit outside open-client checkout built from its repository head.
-- Every default-installed optional provider resolvable from the daemon.
-- An explicitly assembled open-project forest with its root `AGENTS.md`; shared
-  parent directories containing other organizations are not valid substitutes.
-- One inexpensive capable model selector and, optionally, one local smoke-test selector.
-
-Missing preconditions are RED outcomes. The runner never silently skips a phase.
-
-## Contract
-
-One campaign proves the following through production client and AG-UI surfaces:
-
-1. **Candidate build.** The exact service and explicit outside-client checkouts build.
-2. **Clean bootstrap.** A canonical daemon starts on a new database and the
-   client creates a user-named workspace over the explicit forest.
-3. **Inspection.** The model performs successful retrievals, including READ,
-   before answering and names multiple inspected repository artifacts.
-4. **Comprehension.** The report covers service, contracts/DSL, client/AG-UI,
-   repository topology, current-work evidence, and confidence-limiting gaps.
-   If the canonical forge is unavailable inside the run, it must say that the
-   current goal is unverified rather than promote archived GitHub history.
-5. **Forensics.** The supported digest captures the database, packet, reasoning,
-   usage, and operation evidence used by the deterministic verdict.
-
-Proposal modes, reconnect, model hot-swap, and restart/resume are not asserted
-by this executable slice. Expansion of the capstone remains tracked in #3.
-
-Passing individual package tests or receiving HTTP 200 is insufficient. The user-visible client must remain usable and the requested terminal deliverable must be present.
-
-## Evidence
-
-Each preserved campaign atomically claims `benchmarks/run<N>-orientation/` and writes:
-
-- `workspace` — the generated workspace name;
-- `prompt.md` — the exact orientation request;
-- `client.json` and `client.stderr.log` — the client result and diagnostics;
-- `service.stdout.log` and `service.stderr.log`;
-- `phases.json` — commands, timings, and exit statuses without secrets;
-- `verdict.json` — lifecycle, publication, inspection, evidence, and coverage checks;
-- `plurnk.db` — the preserved database;
-- `digest/` — `digest.md`, `digest.json`, `reasoning.md`, and packet sections;
-- requiem artifacts in `digest/` when `--requiem` is requested.
-
-The database is evidence, never the diagnostic interface. Assertions consume client output, AG-UI events, and digest artifacts.
-
-## Posture
-
-- Execute in the foreground and fail hard.
-- Preserve every failing specimen; preserve passing specimens when requested.
-- Never reuse a database for a clean-bootstrap comparison.
-- A provider/configuration/install failure is a gate failure, not a skipped model test.
-- Never infer current work from an archived issue or an uninspected forge reference.
-- File every cross-family defect on the canonical forge with its owning lane label and specimen path.