plurnk-execs

Lean framework and contract for @plurnk/plurnk-execs-* runtime packages. Core uses it to discover EXEC tags, admit calls, and stream each runtime's output under its own tag-addressed scheme. The default service manifest, not this framework, owns the standard installed leaf set ({§bundled-set}).

Install

npm install @plurnk/plurnk-execs

Install executor leaves beside the framework to assemble a standalone host. Any compatible third-party leaf remains discoverable without changing the framework or service.

Documentation

• SPEC.md — authoritative executor author and consumer contract.
• plurnk-contracts — EXEC AST and shared runtime-neutral contracts.
• plurnk-schemes — universal operation results and derived output-scheme contract.

Write an executor

Publish a package under any scope with plurnk.kind === "exec", one or more runtime declarations, and a default-exported BaseExecutor subclass.

Declare runtime tags

{
  "plurnk": {
    "kind": "exec",
    "runtimes": [
      {
        "name": "cobol",
        "glyph": "🗄",
        "summary": "Run a COBOL program.",
        "invocation": {
          "body": { "role": "COBOL program", "required": true },
          "example": { "body": "DISPLAY 'HELLO'." }
        }
      }
    ]
  }
}

One package may claim several tags; the consumer instantiates and probes each tag independently. A name uses lowercase URI-scheme syntax [a-z][a-z0-9+.-]*; only is reserved by runtime policy. summary is the one-line capability description. invocation defines the body and optional target buckets plus one canonical example used for dispatch enforcement and the generated worker://~/_plurnk/tools/ document. A docs/<tag>.md file supplies supplemental detail. See {§executor-runtime-declaration}.

Implement the executor

| Runtime shape | Base class | Author-owned hooks | | --------------------- | -------------------- | --------------------------------------------------------------------------------------- | | Subprocess | SubprocessExecutor | spawnArgs() and normally binary; stdout/stderr, abort, env, and exit are inherited. | | Logical or in-process | BaseExecutor | channels, run(), and optional probe() / effect(). |

run() receives only the inputs and consumer-owned sinks in {§executor-sinks}. Return a universal result; expected failures carry RFC 9457 Problem Details and leave affected channels errored. Honor signal, write only declared channels, and retain no state between runs.

effect(target) declares one admission fact for the consumer-canonical logical target. host is proposal-gated; read and pure are automatically accepted. The consumer preserves the fact rather than asking again after target materialization. All three then use the same background stream path—automatic acceptance is not a same-turn result. See {§executor-effect}.

Understand the target

The EXEC (target) slot is runtime-specific:

| Runtime family | Typical mapping | | -------------- | ----------------------------------------------------------------- | | Data | Target is input; body is the program (jq, SQLite, WebAssembly). | | Executable | Target is the program; body is its stdin (shell, Python). |

The consumer supplies both cwd and a resolved target; the leaf maps them to its tool rather than reconstructing filesystem or scheme policy.

Address output

The runtime tag is also the output scheme. A subprocess result is therefore read at an address such as sh:///1/2/3#stdout, while a structured result may be sqlite:///1/2/3#results. exec:// is not an output address. Executors only produce channels; the consumer owns storage and every later READ/FIND. See {§executor-output-address}.

Discovery and policy

discover(options?) scans scoped and unscoped packages under the nearest node_modules, applies trust before executable hooks, applies boot policy, and returns { registry, packageAttributions, skipped, disabled }. Tag collisions fail hard. Static attribution is normalized once per represented package; an executor may additionally decide per provider attempt whether its synchronous attributions(context) hook returns no, one, or many opaque tags ({§plugin-attribution}).

| Policy | Result | | ----------------------------------- | --------------------------------------------- | | PLURNK_EXECS_<TAG>=0 or false | Tag is not registered. | | PLURNK_EXECS_ONLY=<list> | Only named tags remain; empty registers none. | | Policy.enabledAcross(tag, layers) | Every layer must admit the tag. |

Policy is subtractive; a downstream layer cannot restore a removed tag. See {§executor-discovery}, {§executor-trust}, and {§executor-policy}.

Exports

• BaseExecutor, SubprocessExecutor, and SpawnArgs.
• discover, Policy, RuntimeTag, and runtime discovery types.
• Advertise, a deprecated frozen 1.x compatibility helper with no current service path.
• ErrorDetail and PLURNK_EXECS_ERROR_DETAIL_LIMIT.
• Executor arguments, channel, availability, and effect types.
• Results, result types, and runtime-neutral Notice types.

Tests

test:lint, test:unit.