@plurnk/plurnk-service 3.0.0 → 3.2.0

package/dist/evidence/digest.sql

@@ -72,7 +72,7 @@ SELECT pr.id, pr.inference_call_id, a.id AS turn_attempt_id, ic.kind,
        pr.usage_input_no_cache, pr.usage_input_cache_read, pr.usage_input_cache_write,
        pr.usage_output_text, pr.usage_output_reasoning,
        pr.cost_kind, pr.cost_amount, pr.cost_currency, pr.cost_usd_equivalent,
-       pr.cost_source, pr.cost_reason, pr.started_at, pr.completed_at
+       pr.cost_source, pr.cost_reason, pr.started_at, pr.completed_at, ic.payloads_retired_at
 FROM provider_requests pr
 JOIN inference_calls ic ON ic.id = pr.inference_call_id
 LEFT JOIN turn_attempts a ON a.model_call_id = ic.id
@@ -87,8 +87,11 @@ SELECT * FROM provider_requests WHERE id = $request_id;
 
 -- PREP: digest_log_entries
 SELECT id, worker_id, loop_id, turn_id, sequence, at, origin, source, model_call_id,
+       inherited_history, ambient_event_id,
        op, signal,
        scheme, hostname, port, pathname, query, fragment,
+       CASE WHEN scheme IS NULL AND mimetype_tx = 'application/json'
+            THEN coalesce(json_extract(tx, '$.source.target'), json_extract(tx, '$.target')) END AS target_tx,
        rx, status_rx, mimetype_rx,
        state, outcome, attrs, initial_folded,
        projection.active AS projection_active,
@@ -97,6 +100,9 @@ FROM log_entries le
 JOIN log_entry_projections projection ON projection.log_entry_id = le.id
 ORDER BY loop_id, turn_id, sequence;
 
+-- PREP: digest_proposal_decisions
+SELECT log_entry_id, decision, resolver, body, outcome, decided_at FROM proposal_decisions;
+
 -- PREP: digest_worker_rollups
 -- Structural per-worker aggregates. Accounting is derived through the shared
 -- exact-decimal provider contract rather than SQLite numeric arithmetic.

package/dist/man/plurnk-service.1

@@ -0,0 +1,499 @@
+.TH PLURNK-SERVICE 1 "2026-10-12" "plurnk-service 3.2.0" "User Commands"
+.SH NAME
+plurnk-service \- persistent agent runtime
+.SH SYNOPSIS
+.nf
+plurnk-service [options] [start|migrate]
+       plurnk-service [options] config [edit|defaults|check]
+       plurnk-service [options] share [<file.db>] [<folder>] [--workspace=<id>] [--requiem]
+       plurnk-service [options] requiem <file.db> <folder>
+.fi
+.SH DESCRIPTION
+Runs the Plurnk daemon or performs a local administrative command.
+The terminal client is plurnk(1).
+.SH OPTIONS AND COMMANDS
+.TP
+.B --service-db-path
+Database path; empty = $XDG_DATA_HOME/plurnk/plurnk.db (~/.local/share
+by default). Module operational state: $XDG_STATE_HOME/plurnk
+(~/.local/state/plurnk by default).
+(PLURNK_SERVICE_DB_PATH=)
+.TP
+.B --service-state-root
+A private daemon's root ({§state-root}): empty = the XDG homes; an
+absolute path (a leading ~/ expands) roots data, state, cache and
+runtime under it as <root>/{data,state,cache,runtime}/plurnk.
+Configuration and the shared Agent Skills root never move;
+PLURNK_SERVICE_DB_PATH still wins.
+(PLURNK_SERVICE_STATE_ROOT=)
+.TP
+.B --service-share-folder
+Where `share` writes when no folder is named: each share is a stamped
+child folder. A leading ~/ expands; empty =
+$XDG_STATE_HOME/plurnk/shares (~/.local/state/plurnk/shares by default).
+(PLURNK_SERVICE_SHARE_FOLDER=)
+.TP
+.B --service-sqlite-synchronous
+WAL durability ({§db-durability}): FULL syncs every commit; NORMAL may
+lose recent commits on power loss; OFF may corrupt the database; EXTRA
+equals FULL in WAL. Applied before migration.
+(PLURNK_SERVICE_SQLITE_SYNCHRONOUS=FULL)
+.TP
+.B --service-sqlite-readers
+Read-only database Workers beside the one writer Worker (database
+Workers = 1 + readers); 0 = every read shares the writer. Non-negative
+integer. Blank = sqlrite's own default.
+(PLURNK_SERVICE_SQLITE_READERS=0)
+.TP
+.B --service-capabilities
+CapabilityPolicy JSON: deny removes matching demands; only admits only
+matches. Workspace policy may narrow this ceiling, never widen it.
+(PLURNK_SERVICE_CAPABILITIES={})
+.TP
+.B --service-proposals
+Proposal settlement: review asks the worker's owner; accept or reject
+settles in core. Review without a capable owner rejects. Disconnect
+alone never removes that capability.
+(PLURNK_SERVICE_PROPOSALS=review)
+.TP
+.B --service-file-create-scope
+New filesystem files: none | root | namespace (also outside root).
+Existing-member writes unchanged.
+(PLURNK_SERVICE_FILE_CREATE_SCOPE=root)
+.TP
+.B --service-members-model-scope
+Model-added membership: none | root | namespace. Workspaces may narrow
+it.
+(PLURNK_SERVICE_MEMBERS_MODEL_SCOPE=namespace)
+.TP
+.B --members-enabled
+Enable declared membership rules by default; per-alias _ENABLED
+overrides this.
+(PLURNK_MEMBERS_ENABLED=1)
+.TP
+.B --service-members-sample
+Matched paths a members definition lists as its sample; the rest are
+counted.
+(PLURNK_SERVICE_MEMBERS_SAMPLE=20)
+.TP
+.B --service-git-allowed
+Git membership, status, and branch integration: 1 = permitted; 0 =
+denied service-wide.
+(PLURNK_SERVICE_GIT_ALLOWED=1)
+.TP
+.B --service-git-auto
+Include the repository containing project_root as members: 1 = yes; 0 =
+explicit members only.
+(PLURNK_SERVICE_GIT_AUTO=1)
+.TP
+.B --service-git-output-max-bytes
+Maximum stdout/stderr bytes accepted from one native Git subprocess.
+(PLURNK_SERVICE_GIT_OUTPUT_MAX_BYTES=67108864)
+.TP
+.B --service-file-materialize-max-bytes
+Maximum bytes per workspace-file snapshot, 1..104857600. Larger sources
+return 413 on READ/EDIT.
+(PLURNK_SERVICE_FILE_MATERIALIZE_MAX_BYTES=104857600)
+.TP
+.B --service-max-turns
+Opt-in model-call ceiling shared by the worker tree, including BARE and
+resumes; -1 = uncapped. Runtime (_plurnk) ancestry supplies no ceiling.
+Clients may tighten the model tree's limit.
+(PLURNK_SERVICE_MAX_TURNS=-1)
+.TP
+.B --service-max-commands
+Resolved actions per emission, including glob targets; -1 = unlimited.
+WAIT remains exempt.
+(PLURNK_SERVICE_MAX_COMMANDS=-1)
+.TP
+.B --service-workspace-workers-max-active
+Concurrent live workers per workspace; -1 = unlimited. Excess spawns
+return 508, not a queue.
+(PLURNK_SERVICE_WORKSPACE_WORKERS_MAX_ACTIVE=-1)
+.TP
+.B --service-loop-timeout
+Active execution allowance per task, positive ms; WAIT pauses it, wakes
+retain it. Exhaustion: 504.
+(PLURNK_SERVICE_LOOP_TIMEOUT=86400000)
+.TP
+.B --service-live-timeout
+Live/demo whole-specimen deadline, ms; includes all prompts and cancels
+before cleanup.
+(PLURNK_SERVICE_LIVE_TIMEOUT=600000)
+.TP
+.B --service-stop-timeout-ms
+End-to-end shutdown budget, positive ms; includes database and listener
+cleanup.
+(PLURNK_SERVICE_STOP_TIMEOUT_MS=30000)
+.TP
+.B --service-provider-recovery
+Provider recovery window, ms; 0 = no reissue. Expiry parks workers with
+a reviewer; without one the loop concludes. BARE returns the provider
+failure.
+(PLURNK_SERVICE_PROVIDER_RECOVERY=900000)
+.TP
+.B --service-provider-recovery-backoff
+First recovery delay, ms; doubles on failure up to
+PROVIDER_RECOVERY_BACKOFF_MAX below.
+(PLURNK_SERVICE_PROVIDER_RECOVERY_BACKOFF=5000)
+.TP
+.B --service-provider-recovery-backoff-max
+Ceiling of that doubling delay, ms.
+(PLURNK_SERVICE_PROVIDER_RECOVERY_BACKOFF_MAX=60000)
+.TP
+.B --service-max-strikes
+Consecutive turn-contract strike threshold.
+(PLURNK_SERVICE_MAX_STRIKES=3)
+.TP
+.B --service-emission-attempts
+Completed responses allowed to produce an admissible turn against the
+same packet.
+(PLURNK_SERVICE_EMISSION_ATTEMPTS=3)
+.TP
+.B --service-min-cycles
+Minimum repetitions before cycle detection fires.
+(PLURNK_SERVICE_MIN_CYCLES=3)
+.TP
+.B --service-max-cycle-period
+Maximum repeating period examined by cycle detection, turns.
+(PLURNK_SERVICE_MAX_CYCLE_PERIOD=4)
+.TP
+.B --service-error-detail-limit
+Maximum characters of runtime diagnostics exposed in model-facing
+errors.
+(PLURNK_SERVICE_ERROR_DETAIL_LIMIT=512)
+.TP
+.B --service-workspace-warm-ms
+Idle workspace Functionality grace, ms; 0 = cool immediately; -1 = no
+time limit.
+(PLURNK_SERVICE_WORKSPACE_WARM_MS=900000)
+.TP
+.B --service-workspace-warm-max
+Retained idle workspace snapshots; 0 = none; -1 = unlimited. Active work
+is exempt.
+(PLURNK_SERVICE_WORKSPACE_WARM_MAX=2)
+.TP
+.B --service-proposal-timeout-ms
+Proposal wait, positive ms; empty = wait indefinitely. Expiry cancels
+the proposal.
+(PLURNK_SERVICE_PROPOSAL_TIMEOUT_MS=)
+.TP
+.B --service-exec-hold
+Comma-separated runtime or runtime:effect names that hold the next turn
+while executing; empty = none.
+(PLURNK_SERVICE_EXEC_HOLD=)
+.TP
+.B --service-exec-hold-ms
+Maximum turn hold, ms; expiry lets the loop continue while the stream
+remains live.
+(PLURNK_SERVICE_EXEC_HOLD_MS=300000)
+.TP
+.B --service-exec-concurrency
+Concurrent EXEC producers per workspace; excess executions wait FIFO; -1
+= unlimited.
+(PLURNK_SERVICE_EXEC_CONCURRENCY=12)
+.TP
+.B --service-exec-input-timeout-ms
+Live input delivery deadline, positive ms, including queued writes;
+expiry retires input, not the process.
+(PLURNK_SERVICE_EXEC_INPUT_TIMEOUT_MS=10000)
+.TP
+.B --service-exec-probe-timeout-ms
+Deadline for one runtime's availability probe at boot, positive ms;
+expiry reports it unavailable.
+(PLURNK_SERVICE_EXEC_PROBE_TIMEOUT_MS=3000)
+.TP
+.B --service-exec-scratch
+Directory a non-file execution source (`sh (log:///…)`) is written to
+for its run, created 0700 on first use ({§exec-scratch-directory}).
+Empty = $XDG_RUNTIME_DIR/plurnk, else the platform temporary directory.
+An executor in another filesystem namespace (a container that mounts
+only the repository) must see the same directory: point this at one it
+mounts.
+(PLURNK_SERVICE_EXEC_SCRATCH=)
+.TP
+.B --service-effect-host
+What an operation that runs code or changes the world does: propose = it
+needs a settlement; auto = it runs ungated. This covers a subprocess and
+an outbound POST, PUT or DELETE alike.
+(PLURNK_SERVICE_EFFECT_HOST=propose)
+.TP
+.B --service-effect-read
+The same for an operation that only observes external state.
+(PLURNK_SERVICE_EFFECT_READ=auto)
+.TP
+.B --service-effect-pure
+The same for an operation with no observable effect.
+(PLURNK_SERVICE_EFFECT_PURE=auto)
+.TP
+.B --service-optimistic-wait-ms
+Brief settlement wait for new streams/completing siblings, ms; 0 = off;
+quiescence ends it early.
+(PLURNK_SERVICE_OPTIMISTIC_WAIT_MS=5000)
+.TP
+.B --service-wait-sec
+Maximum park before reassessing live work, positive seconds; WAIT
+[seconds] overrides one park.
+(PLURNK_SERVICE_WAIT_SEC=300)
+.TP
+.B --service-exec-env-inherit
+Ambient environment an EXEC subprocess may inherit from the host: exact
+names, or one trailing-* prefix glob. This bounds inherited host values,
+not explicit non-reserved values. PLURNK_* and provider credential names
+remain excluded regardless of these selectors. Module-owned launches and
+explicit MCP bindings follow their own launch contract. The shipped list
+is what a shell, git, node and python need to run at all. An operator
+who wants a non-reserved tool credential inherited by commands adds its
+name.
+(PLURNK_SERVICE_EXEC_ENV_INHERIT=PATH,HOME,USER,LOGNAME,SHELL,PWD,TMPDIR,TERM,TZ,LANG,LC_*,PAGER,GIT_PAGER,NO_COLOR,CI)
+.TP
+.B --service-exec-env-exclude
+Names removed after INHERIT, same shapes; narrows without rewriting the
+list above.
+(PLURNK_SERVICE_EXEC_ENV_EXCLUDE=)
+.TP
+.B --service-exec-kill-grace-ms
+Grace after a termination signal, ms; then SIGKILL the surviving process
+group.
+(PLURNK_SERVICE_EXEC_KILL_GRACE_MS=2000)
+.TP
+.B --service-line-anchor-context-lines
+Minimum neighbors hashed on each side of an editable line anchor;
+repeated handles widen context.
+(PLURNK_SERVICE_LINE_ANCHOR_CONTEXT_LINES=2)
+.TP
+.B --service-edit-receipt-context-lines
+Surrounding and changed lines shown at each EDIT boundary; overlapping
+windows coalesce.
+(PLURNK_SERVICE_EDIT_RECEIPT_CONTEXT_LINES=4)
+.TP
+.B --service-edit-receipt-removed-lines
+Removed lines a pure deletion's receipt carries so it can be undone; a
+longer span is cut and counted.
+(PLURNK_SERVICE_EDIT_RECEIPT_REMOVED_LINES=40)
+.TP
+.B --service-git-status-paths
+Paths named per class in the packet's git status; the rest are counted.
+(PLURNK_SERVICE_GIT_STATUS_PATHS=8)
+.TP
+.B --service-budget-pressure
+Above this share of the budget, measured before adding either, the
+Context gauge names its largest rows and a packet within its budget
+carries the budget_pressure notice ({§context-pressure-notice}).
+(PLURNK_SERVICE_BUDGET_PRESSURE=80%)
+.TP
+.B --service-budget-largest-items
+Heaviest retained log rows the pressured Context gauge names, as {path,
+tokens}; 0 names none.
+(PLURNK_SERVICE_BUDGET_LARGEST_ITEMS=5)
+.TP
+.B --service-preview-lines
+First page of everything that comes back unasked in size: a READ or FIND
+without a scope, a stream's delivery, a peer worker's message, a receipt
+the model did not author ({§markerless-first-page}). Lines of text,
+bytes of a byte view, results of a FIND; explicit scopes stay exact. 100
+is a page for the million-token windows hosted models have; a deployment
+with a small room tunes it down.
+(PLURNK_SERVICE_PREVIEW_LINES=100)
+.TP
+.B --service-preview-chars
+Independent bound on the same page, Unicode code points; CRLF counts as
+one separator.
+(PLURNK_SERVICE_PREVIEW_CHARS=16000)
+.TP
+.B --service-emission-history
+Assistant replay ({§emission-history}): none, latest, or all eligible
+turns from this loop, each as the NOTEs it wrote, in the model's voice;
+every other operation is omitted. The context wall may omit the whole
+section; source evidence never changes.
+(PLURNK_SERVICE_EMISSION_HISTORY=all)
+.TP
+.B --service-reasoning-rows
+Optional reasoning memory ({§reasoning-row}): 1 adds the turn's preview
+before its emission or results, only when room remains after all
+requested results and diagnostics. Otherwise omit it silently. 0
+disables it.
+(PLURNK_SERVICE_REASONING_ROWS=0)
+.TP
+.B --service-catalog-summary-chars
+Code points of an entry's prose summary the catalog shows whole.
+(PLURNK_SERVICE_CATALOG_SUMMARY_CHARS=256)
+.TP
+.B --service-log-read-page
+Log entries one client read returns when it names no limit.
+(PLURNK_SERVICE_LOG_READ_PAGE=100)
+.TP
+.B --service-log-read-max
+Ceiling of one client log read, whatever limit it names.
+(PLURNK_SERVICE_LOG_READ_MAX=1000)
+.TP
+.B --service-prompts-page
+Root-conversation prompts one listing returns when it names no limit.
+(PLURNK_SERVICE_PROMPTS_PAGE=100)
+.TP
+.B --service-model-catalog-page
+Models one catalog page lists when the query names no limit.
+(PLURNK_SERVICE_MODEL_CATALOG_PAGE=50)
+.TP
+.B --service-files-items
+Turn-0 surveys: -1 = whole surveys (each fits the budget or lands as its
+size); N > 0 caps file-map rows; 0 = off. Workspace settings.filesItems
+overrides this default; other surveys stay whole.
+(PLURNK_SERVICE_FILES_ITEMS=-1)
+.TP
+.B --service-docs-exclude
+Scheme names omitted from discoverable references, comma-separated;
+empty = none. Executable docs instead follow tool enablement. Extension
+trust lives in plurnk-meta's defaults.
+(PLURNK_SERVICE_DOCS_EXCLUDE=plurnk,file,exec)
+.TP
+.B --service-roots
+Skills, plugin and standalone MCP configuration roots, comma-separated,
+nearest first: project (the workspace project's .agents), plurnk
+($XDG_CONFIG_HOME/plurnk), global (~/.agents).
+(PLURNK_SERVICE_ROOTS=project,plurnk,global)
+.TP
+.B --service-search-exclude
+Comma-separated globs excluded from derivation, not READ. No slash =
+basename; slash = pathname.
+(PLURNK_SERVICE_SEARCH_EXCLUDE=*.min.*,*.map,package-lock.json,npm-shrinkwrap.json,packages.lock.json,yarn.lock,pnpm-lock.yaml,bun.lockb,Cargo.lock,poetry.lock,uv.lock,Pipfile.lock,Gemfile.lock,composer.lock,go.sum,flake.lock,gradle.lockfile,*/dist/*,dist/*,*/build/*,build/*,*/.next/*,.next/*,*/node_modules/*,node_modules/*,*/vendor/*,vendor/*,*/coverage/*,coverage/*,*/.vuepress/*,.vuepress/*,*/.nuxt/*,.nuxt/*)
+.TP
+.B --service-search-max-bytes
+Bodies larger than this many bytes are not parsed or full-text indexed
+(READ is unaffected); empty = unbounded.
+(PLURNK_SERVICE_SEARCH_MAX_BYTES=)
+.TP
+.B --service-derive-concurrency
+Concurrent parser derivations: empty = sqrt(available cores); -1 = all
+cores; positive N = exact cap.
+(PLURNK_SERVICE_DERIVE_CONCURRENCY=)
+.TP
+.B --service-derive-store-batch
+Maximum symbol/reference rows per indexing SQLite statement.
+(PLURNK_SERVICE_DERIVE_STORE_BATCH=1024)
+.TP
+.B --service-derive-progress-heartbeat-ms
+Progress heartbeat, ms; starts, failures, and completion are immediate;
+no-op passes stay silent.
+(PLURNK_SERVICE_DERIVE_PROGRESS_HEARTBEAT_MS=15000)
+.TP
+.B --service-retain-packet-turns
+Packet compositions kept per loop, newest first; -1 disables the count
+limit, not the age limit.
+(PLURNK_SERVICE_RETAIN_PACKET_TURNS=-1)
+.TP
+.B --service-retain-packet-ms
+Packet compositions kept by age, ms since the turn completed; -1
+disables the age limit.
+(PLURNK_SERVICE_RETAIN_PACKET_MS=2592000000)
+.TP
+.B --service-retain-response-turns
+Calls with captured payloads kept per loop, newest first; -1 disables
+the count limit. These controls do not retire messages, turn sources,
+operations, approval decisions or accounting.
+(PLURNK_SERVICE_RETAIN_RESPONSE_TURNS=-1)
+.TP
+.B --service-retain-response-ms
+Call payloads kept by age, ms since the turn completed; -1 disables the
+age limit. Covers normalized responses and all physical-request
+payloads, including failed retries. Identities, status, usage and cost
+remain; retirement is timestamped on the logical call.
+(PLURNK_SERVICE_RETAIN_RESPONSE_MS=2592000000)
+.TP
+.B --service-collect-packet-items
+Collect packet items no turn's composition references (1), or keep them
+(0).
+(PLURNK_SERVICE_COLLECT_PACKET_ITEMS=1)
+.TP
+.B --service-collect-derivations
+Collect derivations no channel, turn source, or log row cites (1), or
+keep them (0).
+(PLURNK_SERVICE_COLLECT_DERIVATIONS=1)
+.TP
+.B --service-collect-contents
+Collect unreferenced text and native bodies (1), or keep them (0).
+Retained messages, operations and packet attachments pin native bytes
+({§native-content-lifetime}).
+(PLURNK_SERVICE_COLLECT_CONTENTS=1)
+.TP
+.B --service-retention-interval-ms
+Retention cadence while the daemon runs, ms; 0 = at shutdown only.
+(PLURNK_SERVICE_RETENTION_INTERVAL_MS=3600000)
+.TP
+.B --service-auto-vacuum
+SQLite auto-vacuum mode the daemon keeps its file in
+({§db-space-reclamation}): incremental = retention passes return free
+pages to the OS; none = the file only grows, and freed pages are reused.
+A change takes effect at the next start through one VACUUM, which
+rewrites the whole file (needs free disk about the file's size and
+blocks the daemon for its duration).
+(PLURNK_SERVICE_AUTO_VACUUM=incremental)
+.TP
+.B --service-reclaim-min-free-bytes
+Free space, bytes, below which a retention pass leaves free pages for
+SQLite to reuse instead of returning them; 0 = return every free page
+each pass.
+(PLURNK_SERVICE_RECLAIM_MIN_FREE_BYTES=0)
+.TP
+.B --host
+Where the daemon listens, and so where a local client dials: one line
+moves both.
+(PLURNK_HOST=127.0.0.1)
+.TP
+.B --port
+The daemon's TCP port, shared by all client interfaces.
+(PLURNK_PORT=1066)
+.TP
+.B --env-file=<path>
+layer env from <path> (repeatable; later wins; errors if
+missing)
+.TP
+.B --env-file-if-exists=<path>
+layer env from <path> if present (repeatable; later
+wins)
+.TP
+.B --config=<path>
+layer additional env from
+<path>
+.TP
+.B config defaults
+print every installed package's annotated
+\&.env.defaults
+.TP
+.B config check
+validate configuration without contacting a
+provider
+.TP
+.B share
+share a consistent copy of the database as a digest <folder> (default
+database: the service's; default folder: a stamped child of
+PLURNK_SERVICE_SHARE_FOLDER); --workspace=<id> limits it to one
+workspace; --requiem adds the forensic interview (calls a
+model)
+.TP
+.B requiem
+add the forensic interview to a digest <folder> of <file.db> (calls a
+model)
+.TP
+.B -v, --version
+show executable
+provenance
+.TP
+.B -h, --help
+show this
+help
+.SH CONFIGURATION
+Run plurnk-service config defaults for the installed configuration catalog,
+or plurnk-service config check to validate configuration
+without contacting a provider.
+The package's INSTALL.md describes the configuration cascade
+and resource scopes.
+.SH FILES
+.TP
+.I $XDG_CONFIG_HOME/plurnk/.env
+Operator configuration; ~/.config/plurnk/.env when XDG_CONFIG_HOME is unset.
+.TP
+.I plurnk.service
+Optional systemd user unit shipped in the package; installation is manual.
+.SH SEE ALSO
+plurnk(1)

package/dist/schemes/Env.d.ts

@@ -0,0 +1,26 @@
+import type { FindStatement, KillStatement } from "@plurnk/plurnk-contracts";
+import { type EditBatchResult, type RepresentationPreparationRequest, type RepresentationPreparationResult, type ResolvedEditStatement, type RuntimeSchemeFacet, type SchemeCtx, type SchemeResult } from "@plurnk/plurnk-schemes";
+import type { EnvRecord } from "../server/EnvFunctionality.ts";
+export interface EnvRegistry {
+    readonly env: NodeJS.ProcessEnv;
+    readonly record: Readonly<Record<string, EnvRecord>>;
+}
+export type EnvResolve = (workspaceId: number, workerId: number) => Promise<EnvRegistry>;
+export type EnvWriteVerb = "replace" | "remove" | "disable";
+export interface EnvWriteIdentity {
+    readonly workspaceId: number;
+    readonly workerId: number;
+    readonly scope: "worker";
+}
+export type EnvInvoke = (verb: EnvWriteVerb, params: unknown, identity: EnvWriteIdentity) => Promise<unknown>;
+export default class EnvScheme implements RuntimeSchemeFacet {
+    #private;
+    readonly manifest: NonNullable<RuntimeSchemeFacet["manifest"]>;
+    constructor(resolve: EnvResolve, invoke: EnvInvoke);
+    claims(pathname: string): boolean;
+    prepareRepresentation(request: RepresentationPreparationRequest, ctx: SchemeCtx): Promise<RepresentationPreparationResult>;
+    prepareFind(statement: FindStatement, ctx: SchemeCtx): Promise<SchemeResult>;
+    editBatch(statements: readonly ResolvedEditStatement[], ctx: SchemeCtx): Promise<EditBatchResult>;
+    kill(statement: KillStatement, ctx: SchemeCtx): Promise<SchemeResult>;
+}
+//# sourceMappingURL=Env.d.ts.map

package/dist/schemes/Env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Env.d.ts","sourceRoot":"","sources":["../../src/schemes/Env.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAc,MAAM,0BAA0B,CAAC;AACzF,OAAO,EAEH,KAAK,eAAe,EACpB,KAAK,gCAAgC,EACrC,KAAK,+BAA+B,EACpC,KAAK,qBAAqB,EAC1B,KAAK,kBAAkB,EACvB,KAAK,SAAS,EACd,KAAK,YAAY,EACpB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE/D,MAAM,WAAW,WAAW;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC,CAAC;CACxD;AACD,MAAM,MAAM,UAAU,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;AACzF,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,QAAQ,GAAG,SAAS,CAAC;AAC5D,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,QAAQ,CAAC;CAC5B;AACD,MAAM,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,EAAE,gBAAgB,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;AAa9G,MAAM,CAAC,OAAO,OAAO,SAAU,YAAW,kBAAkB;;IACxD,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAC,kBAAkB,CAAC,UAAU,CAAC,CAAC,CAE5D;IAIF,YAAY,OAAO,EAAE,UAAU,EAAE,MAAM,EAAE,SAAS,EAGjD;IAGD,MAAM,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAEhC;IA2CK,qBAAqB,CAAC,OAAO,EAAE,gCAAgC,EAAE,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,+BAA+B,CAAC,CAU/H;IAIK,WAAW,CAAC,SAAS,EAAE,aAAa,EAAE,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC,CAejF;IAGK,SAAS,CAAC,UAAU,EAAE,SAAS,qBAAqB,EAAE,EAAE,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,eAAe,CAAC,CActG;IAIK,IAAI,CAAC,SAAS,EAAE,aAAa,EAAE,GAAG,EAAE,SAAS,GAAG,OAAO,CAAC,YAAY,CAAC,CAU1E;CACJ"}

package/dist/schemes/Env.js

@@ -0,0 +1,133 @@
+import { Results, } from "@plurnk/plurnk-schemes";
+import { OperationFailureError } from "../core/results.js";
+const OWNER = "scheme:env";
+const NAME = /^[A-Za-z_][A-Za-z0-9_]*$/u;
+// {§execution-output-identity} — the manager's own output streams, which stay the executor's.
+const STREAM = /^[0-9a-f]{8}$/u;
+const ADDRESS = /^[a-z][a-z0-9+.-]*:\/\/[^/]*(\/.*)$/iu;
+const nameOf = (pathname) => {
+    const name = pathname.replace(/^\//u, "");
+    return NAME.test(name) && !STREAM.test(name) ? name : null;
+};
+export default class EnvScheme {
+    manifest = {
+        authority: "resource", channels: {}, defaultChannel: "body", writableBy: ["model", "client", "_plurnk"],
+    };
+    #resolve;
+    #invoke;
+    constructor(resolve, invoke) {
+        this.#resolve = resolve;
+        this.#invoke = invoke;
+    }
+    // The registry is the namespace: every coordinate but the manager's own output streams.
+    claims(pathname) {
+        return !STREAM.test(pathname.replace(/^\//u, ""));
+    }
+    static #named(target) {
+        if (target === null || target.kind !== "url") {
+            return Results.failure(OWNER, "target-required", 400, "The operation needs an env:///NAME target.", {}, { retryable: false });
+        }
+        const name = (target.hostname ?? "") === "" ? nameOf(target.pathname) : null;
+        if (name === null)
+            return EnvScheme.#invalid(target.raw);
+        return { name, pathname: `/${name}` };
+    }
+    static #invalid(target) {
+        return Results.failure(OWNER, "name-invalid", 400, `'${target}' is not a name a shell can export; the form is env:///NAME.`, {}, { target, retryable: false });
+    }
+    static #missing(name) {
+        return Results.failure(OWNER, "entry-not-found", 404, `No name ${name} is in effect for this Worker's commands.`, {}, { target: `env:///${name}` });
+    }
+    static #whole(name, op) {
+        return Results.failure(OWNER, "value-whole", 400, `env:///${name} is one value: a scope or a pattern selects nothing in it.`, {}, {
+            target: `env:///${name}`, retryable: false,
+            recovery: op === "EDIT" ? `EDIT (env:///${name}) with the whole value as the body.` : `KILL (env:///${name}) retires the name.`,
+        });
+    }
+    // The family's refusal is the operation's result.
+    async #write(verb, params, ctx) {
+        try {
+            await this.#invoke(verb, params, { workspaceId: ctx.workspaceId, workerId: ctx.workerId, scope: "worker" });
+            return null;
+        }
+        catch (cause) {
+            if (cause instanceof OperationFailureError)
+                return cause.result;
+            throw cause;
+        }
+    }
+    #project(ctx, pathname, value) {
+        return ctx.entries.write(pathname, { channels: { body: { content: value, mimetype: "text/plain" } } });
+    }
+    // READ projects the value the Worker's commands receive now; a name no longer in effect
+    // withdraws its projection.
+    async prepareRepresentation(request, ctx) {
+        const name = request.authority === "" ? nameOf(request.pathname) : null;
+        if (name === null)
+            return EnvScheme.#invalid(`env://${request.authority}${request.pathname}`);
+        const value = (await this.#resolve(ctx.workspaceId, ctx.workerId)).env[name];
+        if (value === undefined) {
+            await ctx.entries.delete(request.pathname);
+            return EnvScheme.#missing(name);
+        }
+        const written = await this.#project(ctx, request.pathname, value);
+        return written.status >= 400 ? { status: written.status, problem: written.problem } : { status: 200 };
+    }
+    // FIND lists exactly what is in effect: stored projections of names no longer in effect are
+    // withdrawn and every current name is projected before the host selects among them.
+    async prepareFind(statement, ctx) {
+        const { env } = await this.#resolve(ctx.workspaceId, ctx.workerId);
+        const stored = await ctx.entries.operations.find({ ...statement, matcher: null, lineMarker: { marks: [1, -1] } });
+        if (stored.status === 200) {
+            for (const item of stored.results) {
+                const path = Array.isArray(item) ? item[0].path : undefined;
+                const pathname = path === undefined ? undefined : ADDRESS.exec(path)?.[1];
+                const name = pathname === undefined ? null : nameOf(pathname);
+                if (name !== null && env[name] === undefined)
+                    await ctx.entries.delete(`/${name}`);
+            }
+        }
+        for (const [name, value] of Object.entries(env)) {
+            if (value !== undefined && nameOf(`/${name}`) !== null)
+                await this.#project(ctx, `/${name}`, value);
+        }
+        return { status: 200 };
+    }
+    // {§functionality-replacement} — EDIT assigns a whole value without changing enabledness.
+    async editBatch(statements, ctx) {
+        const statement = statements[0];
+        if (statement === undefined || statements.length > 1) {
+            return Results.failure(OWNER, "value-whole", 400, "One EDIT sets one value, whole.", {}, {
+                recovery: "EDIT (env:///NAME) with the value as the body, one statement per name.", retryable: false,
+            });
+        }
+        const named = EnvScheme.#named(statement.target);
+        if ("status" in named)
+            return named;
+        if (statement.lineMarker !== null || statement.matcher !== null)
+            return EnvScheme.#whole(named.name, "EDIT");
+        const refused = await this.#write("replace", { alias: named.name, definition: { value: statement.body ?? "" } }, ctx);
+        if (refused !== null)
+            return refused;
+        await ctx.entries.delete(named.pathname);
+        return { status: 200 };
+    }
+    // KILL retires the name from the Worker's commands: the family's `remove` for an entry the
+    // Worker owns, its `disable` for an inherited one, whose definition is kept.
+    async kill(statement, ctx) {
+        const named = EnvScheme.#named(statement.target);
+        if ("status" in named)
+            return named;
+        if (statement.lineMarker !== null || statement.matcher !== null)
+            return EnvScheme.#whole(named.name, "KILL");
+        const entry = (await this.#resolve(ctx.workspaceId, ctx.workerId)).record[named.name];
+        if (entry === undefined || entry.source === "masked" || entry.value === undefined)
+            return EnvScheme.#missing(named.name);
+        const refused = await this.#write(entry.source === "worker" ? "remove" : "disable", { alias: named.name }, ctx);
+        if (refused !== null)
+            return refused;
+        await ctx.entries.delete(named.pathname);
+        return { status: 200 };
+    }
+}
+//# sourceMappingURL=Env.js.map