@mnmal-ai/substrate 1.0.0-alpha.5 → 1.0.0-alpha.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -25,6 +25,7 @@ A plugin package declares `@mnmal-ai/substrate` as a peer dependency and as a de
25
25
  | `substrate mcp` | stdio MCP server; reads `SUBSTRATE_URL`, and `SUBSTRATE_MCP_TOOLS` (csv) to register only some tools |
26
26
  | `substrate init [dir] [flags]` | Scaffold a runtime directory (interactive; `--yes` for scripted use) |
27
27
  | `substrate ask <question…>` | Ask a natural-language question (needs `substrate-nl`) |
28
+ | `substrate run <script.mts>` | Run a script against a signed, guarded client and print one JSON report |
28
29
  | `substrate federate <verb>` | Federation onboarding: `enroll` / `join` / `check` |
29
30
  | `substrate check-enums [--json]` | Report stored values outside a field's declared enum; exits 1 on drift, so it works as a CI gate |
30
31
  | `substrate normalise-vocab <ns> <Type> <field> [--apply]` | Rewrite stored vocabulary aliases to canonical values (admin) |
@@ -44,6 +45,41 @@ substrate ask [--ns <namespace>] [--project <name>] [--json] <question…>
44
45
 
45
46
  Posts the question to `POST /substrate/v1/nl` on `SUBSTRATE_URL` and prints the answer. `--ns` defaults to `SUBSTRATE_NAMESPACE`, and one of the two is required; `--project` defaults to the current directory's name. Human output leads with the frame line (`▸ <ns>/<Type> · parser · 3 rows`); a frame the engine rejected prints `· rejected` and the errors. `--json` prints the raw `{ outcome, trail }`. Exit codes: `0` answered, `1` refused / engine errors / request failed, `2` usage or configuration error.
46
47
 
48
+ ### `substrate run`
49
+
50
+ ```bash
51
+ substrate run <script.mts> [--args <json>] [--dry-run | --write] [--max-writes <n>] [--out <file>]
52
+ ```
53
+
54
+ Imports the script and calls its default export with a `ScriptContext` (`args`, `query`, `queryAll`, `recall`, `mutate`, `log`), so one call can chain many reads and writes and return one result. The client is signed from `SUBSTRATE_URL`, `SUBSTRATE_AGENT_KEY_ID` and `SUBSTRATE_AGENT_KEY_PATH`; an unsigned run is refused.
55
+
56
+ ```ts
57
+ import type { ScriptContext } from '@mnmal-ai/substrate/client';
58
+
59
+ // substrate run open-todos.mts --args '{"project":"substrate"}'
60
+ export default async function (s: ScriptContext) {
61
+ const open = await s.queryAll('cortext/Todo', {
62
+ params: { where: { status: { eq: 'open' }, project: { eq: s.args.project } }, limit: 100 },
63
+ fields: { id: true, project: true }
64
+ });
65
+ return { open: open.length };
66
+ }
67
+ ```
68
+
69
+ Guardrails:
70
+
71
+ - **Read-only by default.** `mutate` throws unless `--dry-run` (records each payload, sends nothing, returns `null`) or `--write` (sends up to `--max-writes` frames, default 50).
72
+ - **A rejected frame throws.** A query whose key is missing from `data`, or a mutate the server refused, fails the run with the server's error rather than reading as empty.
73
+ - **Truncation is reported.** `query` adds a warning when a result has `hasMore`; `queryAll` pages to the end.
74
+
75
+ `s.recall({ query, namespace, type?, k?, threshold?, where?, row? })` returns hits best first, through the `recall/Hit` frame. Each hit's `row` is `id` plus the handle fields; pass `row: { body: true }` (or `true`) for more, on the hits you will read.
76
+
77
+ `--args` takes a JSON object, which the script reads as `s.args` (`{}` when omitted), so one script serves many calls.
78
+
79
+ Stdout carries one JSON report, `{ ok, kid, mode, args, result, error?, mutations, warnings, stats }`. `mutations` lists every payload with `applied`, including those sent before a failure. `--out` writes the report to a file and prints a one-line summary. `.mts` scripts run as-is: the Node this package requires strips types natively. Exit codes: `0` ok, `1` the script failed, `2` usage or configuration error.
80
+
81
+ The pieces are exported for use outside the CLI: `createClientFromEnv()` builds the same signed client, and `runScript()` runs a function against the guarded context.
82
+
47
83
  ### `substrate-admin`
48
84
 
49
85
  A separate binary for key management: `bootstrap` (seed the genesis admin key), `doctor` (check a deployment end to end), `onboard`, `list`, `register`, `update`, `rotate`, `revoke`. `substrate-admin --help` documents each.
package/dist/client.d.ts CHANGED
@@ -742,6 +742,128 @@ export declare class SubscribeError extends Error {
742
742
  constructor(message: string, code: string);
743
743
  }
744
744
  //#endregion
745
+ //#region ../../packages/substrate-client/src/from-env.d.ts
746
+ /**
747
+ * The capabilities a client asks for, from `SUBSTRATE_AGENT_CAPABILITIES` (csv),
748
+ * defaulting to `substrate-policy`'s default.
749
+ *
750
+ * Not `ADMIN_CAPABILITIES`: a dataset-registry key intersects the claim, but a
751
+ * file-registry key takes it verbatim, so a wider default would promote every
752
+ * agent on such a deployment to admin.
753
+ */
754
+ export declare function resolveAgentCapabilities(env: NodeJS.ProcessEnv): ReadonlyArray<string>;
755
+ interface ClientFromEnvOptions extends Omit<SubstrateClientOptions, 'endpoint' | 'token' | 'getToken'> {
756
+ env?: NodeJS.ProcessEnv;
757
+ /** Allow an unsigned client when no signing key is configured. Default false. */
758
+ allowAnonymous?: boolean;
759
+ }
760
+ interface ClientFromEnv {
761
+ client: SubstrateClient;
762
+ endpoint: string;
763
+ /** The signing kid, or null for an anonymous client. */
764
+ kid: string | null;
765
+ }
766
+ /**
767
+ * Builds a client from `SUBSTRATE_URL` and `SUBSTRATE_AGENT_KEY_ID` +
768
+ * `SUBSTRATE_AGENT_KEY_PATH`, signing every request as that kid.
769
+ *
770
+ * Redirects are refused and the token's audience is the endpoint's origin.
771
+ *
772
+ * @throws Error when `SUBSTRATE_URL` is unset or unsafe for a credential, when
773
+ * only one of the key pair is set, when the key cannot be read, or when no
774
+ * key is set and `allowAnonymous` is not.
775
+ */
776
+ export declare function createClientFromEnv(opts?: ClientFromEnvOptions): ClientFromEnv;
777
+ //#endregion
778
+ //#region ../../packages/substrate-client/src/script.d.ts
779
+ /**
780
+ * `read` refuses every mutation, `dry-run` records mutations without sending
781
+ * them, and `write` sends them up to `maxWrites` frames.
782
+ */
783
+ type ScriptMode = 'read' | 'dry-run' | 'write';
784
+ interface ScriptMutation {
785
+ frame: QualifiedFrame;
786
+ /** True when any op-key came back with data; a refused payload otherwise rolls back whole. */
787
+ applied: boolean;
788
+ errors?: PackEnvelope['errors'];
789
+ }
790
+ interface ScriptRecallInput {
791
+ query: string;
792
+ /** Required, as on every recall surface. */
793
+ namespace: string;
794
+ type?: string;
795
+ k?: number;
796
+ threshold?: number;
797
+ where?: Record<string, unknown>;
798
+ /** `true` for the whole row, or the fields to return beside `id`. Omit for the handle fields. */
799
+ row?: true | Record<string, true>;
800
+ }
801
+ interface ScriptRecallHit {
802
+ id: string;
803
+ namespace: string;
804
+ type: string;
805
+ score: number;
806
+ kind: 'seed' | 'expansion';
807
+ expandedFrom?: unknown;
808
+ row: Record<string, unknown>;
809
+ }
810
+ /** What a script's default export receives. */
811
+ interface ScriptContext {
812
+ readonly kid: string | null;
813
+ readonly mode: ScriptMode;
814
+ /** The caller's `--args` object; `{}` when none was passed. */
815
+ readonly args: Readonly<Record<string, unknown>>;
816
+ /**
817
+ * One query. Throws when a requested key is missing from `data`, which is a
818
+ * rejected frame, not an empty result.
819
+ */
820
+ query(frame: QualifiedFrame): Promise<PackEnvelope>;
821
+ /** Every row of a single-key query, paging until `hasMore` is false. */
822
+ queryAll(key: string, frame: {
823
+ params?: Record<string, unknown>;
824
+ fields?: unknown;
825
+ }): Promise<Record<string, unknown>[]>;
826
+ /** Recall hits, best first, through the `recall/Hit` frame. */
827
+ recall(input: ScriptRecallInput): Promise<ScriptRecallHit[]>;
828
+ /**
829
+ * One mutate payload (one transaction). Returns null in `dry-run`, and throws
830
+ * in `read`, past `maxWrites`, or when the server refuses any frame.
831
+ */
832
+ mutate(frame: QualifiedFrame): Promise<PackEnvelope | null>;
833
+ /** Writes to stderr; stdout carries only the result. */
834
+ log(...args: unknown[]): void;
835
+ }
836
+ interface ScriptReport {
837
+ ok: boolean;
838
+ kid: string | null;
839
+ mode: ScriptMode;
840
+ args: Record<string, unknown>;
841
+ result?: unknown;
842
+ error?: string;
843
+ mutations: ScriptMutation[];
844
+ warnings: string[];
845
+ stats: {
846
+ queries: number;
847
+ writes: number;
848
+ ms: number;
849
+ };
850
+ }
851
+ interface RunScriptOptions {
852
+ client: SubstrateClient;
853
+ kid: string | null;
854
+ mode?: ScriptMode;
855
+ args?: Record<string, unknown>;
856
+ maxWrites?: number;
857
+ maxPages?: number;
858
+ log?: (line: string) => void;
859
+ }
860
+ export declare const DEFAULT_MAX_WRITES = 50;
861
+ /**
862
+ * Runs `script` against a guarded context and reports everything it did,
863
+ * including the mutations applied before any failure.
864
+ */
865
+ export declare function runScript(script: (s: ScriptContext) => unknown, opts: RunScriptOptions): Promise<ScriptReport>;
866
+ //#endregion
745
867
  //#region ../../packages/substrate-client/src/subscribe-rows.d.ts
746
868
  /**
747
869
  * Fold one subscribe event into `current`, returning the next row list. Pure:
@@ -779,4 +901,4 @@ export declare function tokenAudience(baseUrl: string): string;
779
901
  /** `fetchImpl` with redirects refused: a redirect would carry the credential to wherever it points. */
780
902
  export declare function noRedirectFetch(fetchImpl?: typeof fetch): typeof fetch;
781
903
  //#endregion
782
- export { ADMIN_CAPABILITIES, type AdminApi, type AdminBackfillChunk, type AdminBackfillInput, type AdminBackfillSummary, type AdminCredential, type AdminDropCascade, type AdminDropNamespaceInput, type AdminDropResult, type AdminDropTypeInput, type AdminEmbedStats, type AdminEnv, type AdminGrantChange, type AdminInviteInput, type AdminInviteResult, type AdminKeyAlgorithm, type AdminKeyRow, type AdminNormaliseInput, type AdminNormaliseResult, type AdminRegisterInput, type AdminRegisterResult, type AdminReindexInput, type AdminReindexPage, type AdminRevokeResult, type AdminUpdateResult, type CallOpts, DEFAULT_CAPABILITIES, type DiagnoseCredential, type DiagnoseFacts, type DiagnoseOpts, type DiagnoseResult, type Diagnostic, type DiagnosticsSink, type DirectoryReconciliation, type DoctorCheck, type DoctorReport, type DoctorStatus, type Grant, type KeyMutationRefusal, type KeyUpdateRefusal, type NlApi, type NlAskRequest, type NlAskResult, type NlOutcome, type NlServedPack, type NlTrailEvent, type NlWireEvent, type OnboardAction, type OnboardStep, type OnboardStepStatus, type PlanOnboardingOpts, type ProcessStat, type QualifiedFrame, type ResolverStat, type RuntimeErrorEntry, type RuntimeErrors, type RuntimeMetrics, SYSTEM_NAMESPACE, SchemaDriftError, type SlowRequest, type SubscribeEvent, type SubstrateClientOptions, type SurgeryApi, type TokenProviderOpts, type WebSocketImpl, type WsOverloadResubscribeOpts, adminClaimCapabilities, allowAll, allowVerbs, and, applyRowFilters, capabilitiesFor, checkRevocable, checkUpdatable, decodeList, denyAll, denyVerbs, describeGrant, encodeGrant, encodeList, expandFlat, flattenGrant, grantCovers, grantEntriesConfer, grantEntryError, grantIsUniform, intersectGrants, isActiveAdminKeyRow, isEncryptedKey, makeAuthorizationProvider, makeTokenProvider, newlyGranted, newlyGrantedPairs, not, or, parseGrantEntries, requireCapability, requireIdentity, requireNamespace, resolveAdminCredential, resolveDefaultKeyPath, resolveDefaultKidPath, revokedAtIso, row };
904
+ export { ADMIN_CAPABILITIES, type AdminApi, type AdminBackfillChunk, type AdminBackfillInput, type AdminBackfillSummary, type AdminCredential, type AdminDropCascade, type AdminDropNamespaceInput, type AdminDropResult, type AdminDropTypeInput, type AdminEmbedStats, type AdminEnv, type AdminGrantChange, type AdminInviteInput, type AdminInviteResult, type AdminKeyAlgorithm, type AdminKeyRow, type AdminNormaliseInput, type AdminNormaliseResult, type AdminRegisterInput, type AdminRegisterResult, type AdminReindexInput, type AdminReindexPage, type AdminRevokeResult, type AdminUpdateResult, type CallOpts, type ClientFromEnv, type ClientFromEnvOptions, DEFAULT_CAPABILITIES, type DiagnoseCredential, type DiagnoseFacts, type DiagnoseOpts, type DiagnoseResult, type Diagnostic, type DiagnosticsSink, type DirectoryReconciliation, type DoctorCheck, type DoctorReport, type DoctorStatus, type Grant, type KeyMutationRefusal, type KeyUpdateRefusal, type NlApi, type NlAskRequest, type NlAskResult, type NlOutcome, type NlServedPack, type NlTrailEvent, type NlWireEvent, type OnboardAction, type OnboardStep, type OnboardStepStatus, type PlanOnboardingOpts, type ProcessStat, type QualifiedFrame, type ResolverStat, type RunScriptOptions, type RuntimeErrorEntry, type RuntimeErrors, type RuntimeMetrics, SYSTEM_NAMESPACE, SchemaDriftError, type ScriptContext, type ScriptMode, type ScriptMutation, type ScriptRecallHit, type ScriptRecallInput, type ScriptReport, type SlowRequest, type SubscribeEvent, type SubstrateClientOptions, type SurgeryApi, type TokenProviderOpts, type WebSocketImpl, type WsOverloadResubscribeOpts, adminClaimCapabilities, allowAll, allowVerbs, and, applyRowFilters, capabilitiesFor, checkRevocable, checkUpdatable, decodeList, denyAll, denyVerbs, describeGrant, encodeGrant, encodeList, expandFlat, flattenGrant, grantCovers, grantEntriesConfer, grantEntryError, grantIsUniform, intersectGrants, isActiveAdminKeyRow, isEncryptedKey, makeAuthorizationProvider, makeTokenProvider, newlyGranted, newlyGrantedPairs, not, or, parseGrantEntries, requireCapability, requireIdentity, requireNamespace, resolveAdminCredential, resolveDefaultKeyPath, resolveDefaultKidPath, revokedAtIso, row };
package/dist/client.js CHANGED
@@ -2,6 +2,7 @@ import { createRequire as __binCreateRequire } from 'node:module'; const require
2
2
  import { a as adminClaimCapabilities, c as makeTokenProvider, d as resolveDefaultKidPath, i as DEFAULT_CAPABILITIES, l as resolveAdminCredential, o as isEncryptedKey, r as ADMIN_CAPABILITIES, s as makeAuthorizationProvider, u as resolveDefaultKeyPath } from "./env-utils-CGNazUNt.js";
3
3
  import { A as expandFlat, C as not, D as isActiveAdminKeyRow, E as describeGrant, F as parseGrantEntries, I as decodeList, L as encodeList, M as grantEntryError, N as grantIsUniform, O as capabilitiesFor, P as intersectGrants, S as and, T as SYSTEM_NAMESPACE, _ as grantCovers, a as denyAll, b as newlyGrantedPairs, c as requireIdentity, g as checkUpdatable, h as checkRevocable, i as allowVerbs, j as flattenGrant, k as encodeGrant, l as requireNamespace, n as row, o as denyVerbs, r as allowAll, s as requireCapability, t as applyRowFilters, v as grantEntriesConfer, w as or, x as revokedAtIso, y as newlyGranted } from "./row-DZ0Fnpc6.js";
4
4
  import { g as SchemaDriftError } from "./src-BLgbLq2k.js";
5
- import { S as reconcileIdentities, _ as currentStep, a as createDefaultDiagnosticsSink, b as DIAGNOSE_CHECKS, c as AuthError, d as AdminBackfillError, f as BACKFILL_CHUNK, g as STEP_MARKS, h as SKIPPABLE_STEPS, i as collectDiagnostics, l as NetworkError, m as ONBOARD_STEPS, n as tokenAudience, o as reduceSubscribeRows, p as CURRENT_MARK, r as SubstrateClient, s as watchRows, t as noRedirectFetch, u as SubscribeError, v as planOnboarding, x as diagnose, y as requiredOutstanding } from "./src-DMzc3HfW.js";
5
+ import { C as diagnose, S as DIAGNOSE_CHECKS, _ as SKIPPABLE_STEPS, a as SubstrateClient, b as planOnboarding, c as reduceSubscribeRows, d as NetworkError, f as SubscribeError, g as ONBOARD_STEPS, h as CURRENT_MARK, i as tokenAudience, l as watchRows, m as BACKFILL_CHUNK, n as resolveAgentCapabilities, o as collectDiagnostics, p as AdminBackfillError, r as noRedirectFetch, s as createDefaultDiagnosticsSink, t as createClientFromEnv, u as AuthError, v as STEP_MARKS, w as reconcileIdentities, x as requiredOutstanding, y as currentStep } from "./src-Dk3Zlsgd.js";
6
+ import { n as runScript, t as DEFAULT_MAX_WRITES } from "./script-C6DSa_Na.js";
6
7
 
7
- export { ADMIN_CAPABILITIES, AdminBackfillError, AuthError, BACKFILL_CHUNK, CURRENT_MARK, DEFAULT_CAPABILITIES, DIAGNOSE_CHECKS, NetworkError, ONBOARD_STEPS, SKIPPABLE_STEPS, STEP_MARKS, SYSTEM_NAMESPACE, SchemaDriftError, SubscribeError, SubstrateClient, adminClaimCapabilities, allowAll, allowVerbs, and, applyRowFilters, capabilitiesFor, checkRevocable, checkUpdatable, collectDiagnostics, createDefaultDiagnosticsSink, currentStep, decodeList, denyAll, denyVerbs, describeGrant, diagnose, encodeGrant, encodeList, expandFlat, flattenGrant, grantCovers, grantEntriesConfer, grantEntryError, grantIsUniform, intersectGrants, isActiveAdminKeyRow, isEncryptedKey, makeAuthorizationProvider, makeTokenProvider, newlyGranted, newlyGrantedPairs, noRedirectFetch, not, or, parseGrantEntries, planOnboarding, reconcileIdentities, reduceSubscribeRows, requireCapability, requireIdentity, requireNamespace, requiredOutstanding, resolveAdminCredential, resolveDefaultKeyPath, resolveDefaultKidPath, revokedAtIso, row, tokenAudience, watchRows };
8
+ export { ADMIN_CAPABILITIES, AdminBackfillError, AuthError, BACKFILL_CHUNK, CURRENT_MARK, DEFAULT_CAPABILITIES, DEFAULT_MAX_WRITES, DIAGNOSE_CHECKS, NetworkError, ONBOARD_STEPS, SKIPPABLE_STEPS, STEP_MARKS, SYSTEM_NAMESPACE, SchemaDriftError, SubscribeError, SubstrateClient, adminClaimCapabilities, allowAll, allowVerbs, and, applyRowFilters, capabilitiesFor, checkRevocable, checkUpdatable, collectDiagnostics, createClientFromEnv, createDefaultDiagnosticsSink, currentStep, decodeList, denyAll, denyVerbs, describeGrant, diagnose, encodeGrant, encodeList, expandFlat, flattenGrant, grantCovers, grantEntriesConfer, grantEntryError, grantIsUniform, intersectGrants, isActiveAdminKeyRow, isEncryptedKey, makeAuthorizationProvider, makeTokenProvider, newlyGranted, newlyGrantedPairs, noRedirectFetch, not, or, parseGrantEntries, planOnboarding, reconcileIdentities, reduceSubscribeRows, requireCapability, requireIdentity, requireNamespace, requiredOutstanding, resolveAdminCredential, resolveAgentCapabilities, resolveDefaultKeyPath, resolveDefaultKidPath, revokedAtIso, row, runScript, tokenAudience, watchRows };
@@ -2,7 +2,7 @@ import { createRequire as __binCreateRequire } from 'node:module'; const require
2
2
  import { d as buildAuditRow, f as AUDIT_EVENT_TYPE } from "./src-CHp3QyqB.js";
3
3
  import { a as adminClaimCapabilities, d as resolveDefaultKidPath, l as resolveAdminCredential, n as trimTrailingSlashes, r as ADMIN_CAPABILITIES, s as makeAuthorizationProvider, u as resolveDefaultKeyPath } from "./env-utils-CGNazUNt.js";
4
4
  import { D as isActiveAdminKeyRow, E as describeGrant, L as encodeList, M as grantEntryError, T as SYSTEM_NAMESPACE, v as grantEntriesConfer } from "./row-DZ0Fnpc6.js";
5
- import { _ as currentStep, b as DIAGNOSE_CHECKS, g as STEP_MARKS, h as SKIPPABLE_STEPS, n as tokenAudience, p as CURRENT_MARK, v as planOnboarding, x as diagnose, y as requiredOutstanding } from "./src-DMzc3HfW.js";
5
+ import { C as diagnose, S as DIAGNOSE_CHECKS, _ as SKIPPABLE_STEPS, b as planOnboarding, h as CURRENT_MARK, i as tokenAudience, v as STEP_MARKS, x as requiredOutstanding, y as currentStep } from "./src-Dk3Zlsgd.js";
6
6
  import { i as pendingMigrations, o as runMigrations, t as PgDataset } from "./src-CXKnqeTW.js";
7
7
  import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
8
8
  import { homedir } from "node:os";
@@ -11,7 +11,7 @@ import { createHash, createPublicKey, generateKeyPairSync, randomUUID } from "no
11
11
  import postgres from "postgres";
12
12
 
13
13
  //#region package.json
14
- var version = "1.0.0-alpha.5";
14
+ var version = "1.0.0-alpha.6";
15
15
 
16
16
  //#endregion
17
17
  //#region src/admin/errors.ts
package/dist/recall.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import { createRequire as __binCreateRequire } from 'node:module'; const require = __binCreateRequire(import.meta.url);
2
- import { a as InMemoryLexicalStore, i as PgClusterStore, n as PgLexicalStore, o as InMemoryEmbeddingsStore, r as PgEmbeddingsStore, s as InMemoryClusterStore, t as RECALL_VERSION } from "./src-BobBNg4q.js";
2
+ import { a as InMemoryLexicalStore, i as PgClusterStore, n as PgLexicalStore, o as InMemoryEmbeddingsStore, r as PgEmbeddingsStore, s as InMemoryClusterStore, t as RECALL_VERSION } from "./src-BNJW0F9B.js";
3
3
  import { $ as CLUSTERER_BACKEND_VERSION, A as CLUSTER_MEMBER_FIELDS, C as EmbedSourceRegistry, D as makeReembed, E as makeEmbedPostWrite, F as unknownParams, G as DEFAULT_CRYSTALLISE_CONFIG, H as CRYSTALLISE_IN_FLIGHT_CODE, I as handleRecallRequest, J as runClusterer, K as handleCrystallise, L as RRF_K, M as recallRouteHandler, N as checkParams, O as crystalliseRouteHandler, P as unknownParamMessage, Q as CLUSTERER_BACKEND, R as armRanks, S as createEmbedStats, T as embedRowReporting, U as createCrystalliseGuard, X as l2normalize, _ as EMBEDDINGS_FETCH_MAX_REFS, a as REINDEX_MAX_LIMIT, b as handleLexicalCoverage, c as SALIENCE_BOOST_MAX_TARGETS, d as embeddingsMigration, et as memberKey, f as recallMcpTool, g as embeddingsFetchRouteHandler, h as embeddingSimilarOperator, i as REINDEX_DEFAULT_LIMIT, j as buildClusterSurface, k as CLUSTER_FIELDS, l as lexicalMigration, m as makeLexicalPostWrite, n as salienceBoostRouteHandler, nt as validateSelector, o as handleReindex, p as makeLexicalClassify, q as validateCrystalliseInput, r as reindexRouteHandler, s as validateReindexInput, t as createRecallPlugin, tt as SELECT_CANDIDATES_MAX_LIMIT, u as recallClustersMigration, v as embedStatsRouteHandler, w as embedAndStore, x as validateLexicalCoverageInput, y as handleEmbedStatsRequest, z as fuseByRank } from "./plugin-BG8E04wi.js";
4
4
 
5
5
  export { CLUSTERER_BACKEND, CLUSTERER_BACKEND_VERSION, CLUSTER_FIELDS, CLUSTER_MEMBER_FIELDS, CRYSTALLISE_IN_FLIGHT_CODE, DEFAULT_CRYSTALLISE_CONFIG, EMBEDDINGS_FETCH_MAX_REFS, EmbedSourceRegistry, InMemoryClusterStore, InMemoryEmbeddingsStore, InMemoryLexicalStore, PgClusterStore, PgEmbeddingsStore, PgLexicalStore, RECALL_VERSION, REINDEX_DEFAULT_LIMIT, REINDEX_MAX_LIMIT, RRF_K, SALIENCE_BOOST_MAX_TARGETS, SELECT_CANDIDATES_MAX_LIMIT, armRanks, buildClusterSurface, checkParams, createCrystalliseGuard, createEmbedStats, createRecallPlugin, crystalliseRouteHandler, embedAndStore, embedRowReporting, embedStatsRouteHandler, embeddingSimilarOperator, embeddingsFetchRouteHandler, embeddingsMigration, fuseByRank, handleCrystallise, handleEmbedStatsRequest, handleLexicalCoverage, handleRecallRequest, handleReindex, l2normalize, lexicalMigration, makeEmbedPostWrite, makeLexicalClassify, makeLexicalPostWrite, makeReembed, memberKey, recallClustersMigration, recallMcpTool, recallRouteHandler, reindexRouteHandler, runClusterer, salienceBoostRouteHandler, unknownParamMessage, unknownParams, validateCrystalliseInput, validateLexicalCoverageInput, validateReindexInput, validateSelector };
@@ -0,0 +1,134 @@
1
+ import { createRequire as __binCreateRequire } from 'node:module'; const require = __binCreateRequire(import.meta.url);
2
+ //#region ../../packages/substrate-client/src/script.ts
3
+ const DEFAULT_MAX_WRITES = 50;
4
+ const DEFAULT_MAX_PAGES = 200;
5
+ /** Counts the frames in a mutate payload: an array under an op-key is one frame per element. */
6
+ function frameCount(frame) {
7
+ return Object.values(frame).reduce((n, v) => n + (Array.isArray(v) ? v.length : 1), 0);
8
+ }
9
+ function assertKeys(frame, env, verb) {
10
+ const missing = Object.keys(frame).filter((k) => !(k in env.data));
11
+ if (missing.length > 0 || verb === "mutate" && (env.errors?.length ?? 0) > 0) {
12
+ const errs = (env.errors ?? []).map((e) => `${e.code ?? "error"}: ${e.message}`).join("; ");
13
+ throw new Error(`${verb} refused${missing.length > 0 ? ` for ${missing.join(", ")}` : ""}${errs !== "" ? ` (${errs})` : ""}`);
14
+ }
15
+ }
16
+ /**
17
+ * Runs `script` against a guarded context and reports everything it did,
18
+ * including the mutations applied before any failure.
19
+ */
20
+ async function runScript(script, opts) {
21
+ const { client, kid, mode = "read", args = {}, maxWrites = 50, maxPages = DEFAULT_MAX_PAGES } = opts;
22
+ const log = opts.log ?? ((line) => process.stderr.write(`${line}\n`));
23
+ const mutations = [];
24
+ const warnings = [];
25
+ const stats = {
26
+ queries: 0,
27
+ writes: 0,
28
+ ms: 0
29
+ };
30
+ const started = Date.now();
31
+ const query = async (frame) => {
32
+ stats.queries++;
33
+ const env = await client.query(frame);
34
+ assertKeys(frame, env, "query");
35
+ for (const [key, page] of Object.entries(env._pagination ?? {})) if (page.hasMore) warnings.push(`${key}: result truncated (hasMore); use queryAll for a complete read`);
36
+ return env;
37
+ };
38
+ const ctx = {
39
+ kid,
40
+ mode,
41
+ args: Object.freeze({ ...args }),
42
+ query,
43
+ async queryAll(key, frame) {
44
+ const rows = [];
45
+ let cursor;
46
+ for (let page = 0; page < maxPages; page++) {
47
+ const params = {
48
+ ...frame.params,
49
+ ...cursor !== void 0 ? { cursor } : {}
50
+ };
51
+ stats.queries++;
52
+ const env = await client.query({ [key]: {
53
+ ...frame,
54
+ params
55
+ } });
56
+ assertKeys({ [key]: frame }, env, "query");
57
+ const data = env.data[key];
58
+ rows.push(...Array.isArray(data) ? data : [data]);
59
+ const p = env._pagination?.[key];
60
+ if (p?.hasMore !== true) return rows;
61
+ if (p.nextCursor === void 0) throw new Error(`${key}: hasMore with no nextCursor`);
62
+ cursor = p.nextCursor;
63
+ }
64
+ throw new Error(`${key}: still hasMore after ${maxPages} pages`);
65
+ },
66
+ async recall({ query: to, row, ...params }) {
67
+ const fields = row === void 0 ? {} : { fields: {
68
+ id: true,
69
+ namespace: true,
70
+ type: true,
71
+ score: true,
72
+ kind: true,
73
+ expandedFrom: true,
74
+ row
75
+ } };
76
+ return (await query({ "recall/Hit": {
77
+ params: {
78
+ to,
79
+ ...params
80
+ },
81
+ ...fields
82
+ } })).data["recall/Hit"];
83
+ },
84
+ async mutate(frame) {
85
+ if (mode === "read") throw new Error("mutate refused: read mode (pass --dry-run or --write)");
86
+ if (mode === "dry-run") {
87
+ mutations.push({
88
+ frame,
89
+ applied: false
90
+ });
91
+ return null;
92
+ }
93
+ const n = frameCount(frame);
94
+ if (stats.writes + n > maxWrites) throw new Error(`mutate refused: ${stats.writes + n} frames would exceed --max-writes ${maxWrites}`);
95
+ const env = await client.mutate(frame);
96
+ const applied = Object.keys(frame).some((k) => k in env.data);
97
+ if (applied) stats.writes += n;
98
+ mutations.push({
99
+ frame,
100
+ applied,
101
+ ...env.errors !== void 0 ? { errors: env.errors } : {}
102
+ });
103
+ assertKeys(frame, env, "mutate");
104
+ return env;
105
+ },
106
+ log: (...args) => log(args.map((a) => typeof a === "string" ? a : JSON.stringify(a)).join(" "))
107
+ };
108
+ const report = (extra) => {
109
+ stats.ms = Date.now() - started;
110
+ return {
111
+ ...extra,
112
+ kid,
113
+ mode,
114
+ args,
115
+ mutations,
116
+ warnings,
117
+ stats
118
+ };
119
+ };
120
+ try {
121
+ return report({
122
+ ok: true,
123
+ result: await script(ctx)
124
+ });
125
+ } catch (err) {
126
+ return report({
127
+ ok: false,
128
+ error: err instanceof Error ? err.message : String(err)
129
+ });
130
+ }
131
+ }
132
+
133
+ //#endregion
134
+ export { runScript as n, DEFAULT_MAX_WRITES as t };
@@ -3,7 +3,7 @@ import { n as txScopeIdFor } from "./src-CXKnqeTW.js";
3
3
  import { B as ROW_FILTER_FIELD, V as matchesRowFilter, W as inFlightError, Y as unresolvedRow, Z as cosineSimilarity, et as memberKey } from "./plugin-BG8E04wi.js";
4
4
 
5
5
  //#region ../../plugins/substrate-recall/package.json
6
- var version = "1.0.0-alpha.5";
6
+ var version = "1.0.0-alpha.6";
7
7
 
8
8
  //#endregion
9
9
  //#region ../../plugins/substrate-recall/src/in-memory-cluster-store.ts
@@ -1,5 +1,5 @@
1
1
  import { createRequire as __binCreateRequire } from 'node:module'; const require = __binCreateRequire(import.meta.url);
2
- import { n as trimTrailingSlashes } from "./env-utils-CGNazUNt.js";
2
+ import { c as makeTokenProvider, i as DEFAULT_CAPABILITIES, n as trimTrailingSlashes } from "./env-utils-CGNazUNt.js";
3
3
  import { D as isActiveAdminKeyRow, O as capabilitiesFor, T as SYSTEM_NAMESPACE } from "./row-DZ0Fnpc6.js";
4
4
  import { _ as decodeEnvelope, a as buildDecodePlan, g as SchemaDriftError, i as applyDecodePlanInPlace, o as decodeWsEnvelope, s as encodeWsFrame, t as WS_SUBPROTOCOL_SUBSTRATE_PACK, x as parseQualifiedKey } from "./src-BLgbLq2k.js";
5
5
  import { signal } from "@preact/signals-core";
@@ -2447,4 +2447,67 @@ function noRedirectFetch(fetchImpl = fetch) {
2447
2447
  }
2448
2448
 
2449
2449
  //#endregion
2450
- export { reconcileIdentities as S, currentStep as _, createDefaultDiagnosticsSink as a, DIAGNOSE_CHECKS as b, AuthError as c, AdminBackfillError as d, BACKFILL_CHUNK as f, STEP_MARKS as g, SKIPPABLE_STEPS as h, collectDiagnostics as i, NetworkError as l, ONBOARD_STEPS as m, tokenAudience as n, reduceSubscribeRows as o, CURRENT_MARK as p, SubstrateClient as r, watchRows as s, noRedirectFetch as t, SubscribeError as u, planOnboarding as v, diagnose as x, requiredOutstanding as y };
2450
+ //#region ../../packages/substrate-client/src/from-env.ts
2451
+ /**
2452
+ * The capabilities a client asks for, from `SUBSTRATE_AGENT_CAPABILITIES` (csv),
2453
+ * defaulting to `substrate-policy`'s default.
2454
+ *
2455
+ * Not `ADMIN_CAPABILITIES`: a dataset-registry key intersects the claim, but a
2456
+ * file-registry key takes it verbatim, so a wider default would promote every
2457
+ * agent on such a deployment to admin.
2458
+ */
2459
+ function resolveAgentCapabilities(env) {
2460
+ const raw = env.SUBSTRATE_AGENT_CAPABILITIES;
2461
+ if (raw === void 0 || raw.trim().length === 0) return DEFAULT_CAPABILITIES;
2462
+ const parsed = raw.split(",").map((c) => c.trim()).filter((c) => c.length > 0);
2463
+ return parsed.length > 0 ? parsed : DEFAULT_CAPABILITIES;
2464
+ }
2465
+ /**
2466
+ * Builds a client from `SUBSTRATE_URL` and `SUBSTRATE_AGENT_KEY_ID` +
2467
+ * `SUBSTRATE_AGENT_KEY_PATH`, signing every request as that kid.
2468
+ *
2469
+ * Redirects are refused and the token's audience is the endpoint's origin.
2470
+ *
2471
+ * @throws Error when `SUBSTRATE_URL` is unset or unsafe for a credential, when
2472
+ * only one of the key pair is set, when the key cannot be read, or when no
2473
+ * key is set and `allowAnonymous` is not.
2474
+ */
2475
+ function createClientFromEnv(opts = {}) {
2476
+ const { env = process.env, allowAnonymous = false, fetch: fetchImpl, ...rest } = opts;
2477
+ const endpoint = trimTrailingSlashes(env.SUBSTRATE_URL ?? "");
2478
+ if (endpoint === "") throw new Error("SUBSTRATE_URL is required");
2479
+ const keyPath = env.SUBSTRATE_AGENT_KEY_PATH ?? "";
2480
+ const kid = env.SUBSTRATE_AGENT_KEY_ID ?? "";
2481
+ if (keyPath === "" !== (kid === "")) throw new Error(`SUBSTRATE_AGENT_KEY_PATH and SUBSTRATE_AGENT_KEY_ID must be set together; only ${keyPath !== "" ? "SUBSTRATE_AGENT_KEY_PATH" : "SUBSTRATE_AGENT_KEY_ID"} is set`);
2482
+ const base = {
2483
+ ...rest,
2484
+ endpoint,
2485
+ fetch: noRedirectFetch(fetchImpl)
2486
+ };
2487
+ if (kid === "") {
2488
+ if (!allowAnonymous) throw new Error("no signing key: set SUBSTRATE_AGENT_KEY_ID and SUBSTRATE_AGENT_KEY_PATH, or pass allowAnonymous");
2489
+ return {
2490
+ client: new SubstrateClient(base),
2491
+ endpoint,
2492
+ kid: null
2493
+ };
2494
+ }
2495
+ const getToken = makeTokenProvider({
2496
+ keyPath,
2497
+ kid
2498
+ }, {
2499
+ capabilities: resolveAgentCapabilities(env),
2500
+ audience: tokenAudience(endpoint)
2501
+ });
2502
+ return {
2503
+ client: new SubstrateClient({
2504
+ ...base,
2505
+ getToken
2506
+ }),
2507
+ endpoint,
2508
+ kid
2509
+ };
2510
+ }
2511
+
2512
+ //#endregion
2513
+ export { diagnose as C, DIAGNOSE_CHECKS as S, SKIPPABLE_STEPS as _, SubstrateClient as a, planOnboarding as b, reduceSubscribeRows as c, NetworkError as d, SubscribeError as f, ONBOARD_STEPS as g, CURRENT_MARK as h, tokenAudience as i, watchRows as l, BACKFILL_CHUNK as m, resolveAgentCapabilities as n, collectDiagnostics as o, AdminBackfillError as p, noRedirectFetch as r, createDefaultDiagnosticsSink as s, createClientFromEnv as t, AuthError as u, STEP_MARKS as v, reconcileIdentities as w, requiredOutstanding as x, currentStep as y };
@@ -3,8 +3,8 @@ import { createRequire as __binCreateRequire } from 'node:module'; const require
3
3
  import { d as buildAuditRow, f as AUDIT_EVENT_TYPE } from "./src-CHp3QyqB.js";
4
4
  import { d as resolveDefaultKidPath, u as resolveDefaultKeyPath } from "./env-utils-CGNazUNt.js";
5
5
  import { E as describeGrant, I as decodeList, L as encodeList, M as grantEntryError, g as checkUpdatable, h as checkRevocable, y as newlyGranted } from "./row-DZ0Fnpc6.js";
6
- import { S as reconcileIdentities } from "./src-DMzc3HfW.js";
7
- import { A as describeAdminTarget, B as version, C as CLI_ACTOR_KID, D as listActiveAdminKeys, E as generateAdminKeypair, F as RESTART_NOTE, I as USAGE, L as argvError, M as resolveAdminTarget, N as ARGV_SPEC, O as readEd25519PublicKey, P as validateArgv, S as BootstrapError, T as forUpdate, _ as REVOKE_EXIT_CODES, a as formatRegisterOutput, b as runKeyPatchViaRoute, c as runRegisterViaRoute, d as formatDoctorReport, f as runDoctor, g as bootstrapKidPath, h as runBootstrap, i as runOnboard, j as resolveAdminAuth, k as readKeyById, l as grantLines, m as parseBootstrapArgs, n as formatChecklist, o as parseRegisterArgs, p as formatBootstrapOutput, r as onboardCommand, s as runRegister, t as openPgDataset, u as doctorCommand, v as UPDATE_EXIT_CODES, w as base64Url, x as ACTOR_HINT, y as runKeyListViaRoute, z as AdminCliError } from "./dataset-CWEms-iK.js";
6
+ import { w as reconcileIdentities } from "./src-Dk3Zlsgd.js";
7
+ import { A as describeAdminTarget, B as version, C as CLI_ACTOR_KID, D as listActiveAdminKeys, E as generateAdminKeypair, F as RESTART_NOTE, I as USAGE, L as argvError, M as resolveAdminTarget, N as ARGV_SPEC, O as readEd25519PublicKey, P as validateArgv, S as BootstrapError, T as forUpdate, _ as REVOKE_EXIT_CODES, a as formatRegisterOutput, b as runKeyPatchViaRoute, c as runRegisterViaRoute, d as formatDoctorReport, f as runDoctor, g as bootstrapKidPath, h as runBootstrap, i as runOnboard, j as resolveAdminAuth, k as readKeyById, l as grantLines, m as parseBootstrapArgs, n as formatChecklist, o as parseRegisterArgs, p as formatBootstrapOutput, r as onboardCommand, s as runRegister, t as openPgDataset, u as doctorCommand, v as UPDATE_EXIT_CODES, w as base64Url, x as ACTOR_HINT, y as runKeyListViaRoute, z as AdminCliError } from "./dataset-IfVlQQ4q.js";
8
8
  import { existsSync, mkdirSync, realpathSync, rmSync, writeFileSync } from "node:fs";
9
9
  import { dirname } from "node:path";
10
10
  import { createHash, randomUUID } from "node:crypto";
package/dist/substrate.js CHANGED
@@ -1,13 +1,14 @@
1
1
  #!/usr/bin/env node
2
2
  import { createRequire as __binCreateRequire } from 'node:module'; const require = __binCreateRequire(import.meta.url);
3
3
  import { B as saveSweepState, G as registerExtensionOperator, I as effectiveFilterOperators, N as MemoryEdgesStore, Q as buildContext, R as loadSweepState, W as getExtensionOperator, a as composeFromManifests, at as WS_REASON_SERVER_RESTART, bt as BridgeUnreachableError, c as MemoryDataset, d as buildAuditRow, f as AUDIT_EVENT_TYPE, i as PluginLoadError, n as kernelMigrationTracking, nt as parseAuthConfig, o as DEFAULT_NAMESPACE, p as INVITE_TYPE, r as mountKernelRoute, s as compose, t as composeKernelPlugins, u as runInviteSweep, yt as validateHardDeleteEnv, z as runSweep } from "./src-CHp3QyqB.js";
4
- import { i as DEFAULT_CAPABILITIES, n as trimTrailingSlashes, s as makeAuthorizationProvider, t as parsePositiveInt } from "./env-utils-CGNazUNt.js";
4
+ import { n as trimTrailingSlashes, s as makeAuthorizationProvider, t as parsePositiveInt } from "./env-utils-CGNazUNt.js";
5
5
  import { L as encodeList, T as SYSTEM_NAMESPACE, f as coversNamespace, m as grantedIn, p as grantOf } from "./row-DZ0Fnpc6.js";
6
- import { c as AuthError, d as AdminBackfillError, l as NetworkError, n as tokenAudience, r as SubstrateClient, t as noRedirectFetch } from "./src-DMzc3HfW.js";
6
+ import { a as SubstrateClient, d as NetworkError, i as tokenAudience, n as resolveAgentCapabilities, p as AdminBackfillError, r as noRedirectFetch, t as createClientFromEnv, u as AuthError } from "./src-Dk3Zlsgd.js";
7
+ import { n as runScript, t as DEFAULT_MAX_WRITES } from "./script-C6DSa_Na.js";
7
8
  import { a as runDerivedMigrations, o as runMigrations, r as deriveListIndexMigration, s as tryWithPgAdvisoryLock, t as PgDataset } from "./src-CXKnqeTW.js";
8
9
  import { t as PgEdgesStore } from "./pg-edges-store-DKPYyd8l.js";
9
- import { a as InMemoryLexicalStore, i as PgClusterStore, n as PgLexicalStore, o as InMemoryEmbeddingsStore, r as PgEmbeddingsStore, s as InMemoryClusterStore } from "./src-BobBNg4q.js";
10
- import { B as version, R as openSql, t as openPgDataset, z as AdminCliError } from "./dataset-CWEms-iK.js";
10
+ import { a as InMemoryLexicalStore, i as PgClusterStore, n as PgLexicalStore, o as InMemoryEmbeddingsStore, r as PgEmbeddingsStore, s as InMemoryClusterStore } from "./src-BNJW0F9B.js";
11
+ import { B as version, R as openSql, t as openPgDataset, z as AdminCliError } from "./dataset-IfVlQQ4q.js";
11
12
  import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
12
13
  import { homedir, hostname } from "node:os";
13
14
  import { basename, dirname, join, resolve } from "node:path";
@@ -347,60 +348,9 @@ var PgIdempotencyStore = class {
347
348
  }
348
349
  };
349
350
 
350
- //#endregion
351
- //#region src/mcp/agent-jwt.ts
352
- /**
353
- * Optional agent-identity JWT provider for the MCP client. When
354
- * SUBSTRATE_AGENT_KEY_PATH (path to an Ed25519 private PEM) + SUBSTRATE_AGENT_KEY_ID are
355
- * set, returns a cached short-TTL EdDSA JWT (refreshed before expiry) that the
356
- * stack verifies in attribute mode → createdBy:{kind:'agent', id:<kid>}.
357
- * Returns null when neither is set (the MCP client then sends no Authorization);
358
- * setting only one throws.
359
- *
360
- * Fail-loud by design: a SET-but-missing/malformed SUBSTRATE_AGENT_KEY_PATH
361
- * throws at provider construction, crashing MCP startup — misconfiguration
362
- * must not silently degrade to anonymous writes.
363
- */
364
- /**
365
- * The capabilities THIS CLIENT asks for, from `SUBSTRATE_AGENT_CAPABILITIES` (csv),
366
- * defaulting to `substrate-policy`'s own default rather than a second copy of it.
367
- *
368
- * Not simply `ADMIN_CAPABILITIES`: for a DATASET-registry key the row
369
- * intersects the claim, but a FILE-registry key takes the claim VERBATIM, so
370
- * a wider default would promote every MCP agent on such a deployment to
371
- * admin. Widen it only where an operator says so.
372
- */
373
- function resolveAgentCapabilities(env) {
374
- const raw = env.SUBSTRATE_AGENT_CAPABILITIES;
375
- if (raw === void 0 || raw.trim().length === 0) return DEFAULT_CAPABILITIES;
376
- const parsed = raw.split(",").map((c) => c.trim()).filter((c) => c.length > 0);
377
- return parsed.length > 0 ? parsed : DEFAULT_CAPABILITIES;
378
- }
379
- /**
380
- * Returns a provider that yields `Bearer <jwt>` (the full Authorization header
381
- * value) when SUBSTRATE_AGENT_KEY_PATH + SUBSTRATE_AGENT_KEY_ID are set, or null when
382
- * unconfigured so callers can skip the header entirely.
383
- */
384
- function makeAgentJwtProvider(env, audience) {
385
- const keyPath = env.SUBSTRATE_AGENT_KEY_PATH;
386
- const kid = env.SUBSTRATE_AGENT_KEY_ID;
387
- const hasPath = keyPath !== void 0 && keyPath !== "";
388
- const hasKid = kid !== void 0 && kid !== "";
389
- if (!hasPath && !hasKid) return () => null;
390
- if (!hasPath || !hasKid) throw new Error(`SUBSTRATE_AGENT_KEY_PATH and SUBSTRATE_AGENT_KEY_ID must be set together; only ${hasPath ? "SUBSTRATE_AGENT_KEY_PATH" : "SUBSTRATE_AGENT_KEY_ID"} is set`);
391
- const provider = makeAuthorizationProvider({
392
- keyPath,
393
- kid
394
- }, {
395
- capabilities: resolveAgentCapabilities(env),
396
- ...audience !== void 0 ? { audience } : {}
397
- });
398
- return () => provider();
399
- }
400
-
401
351
  //#endregion
402
352
  //#region src/cli/ask/main.ts
403
- const USAGE = "usage: substrate ask [--ns <namespace>] [--project <name>] [--json] <question…>\n";
353
+ const USAGE$1 = "usage: substrate ask [--ns <namespace>] [--project <name>] [--json] <question…>\n";
404
354
  async function runAsk(argv, options = {}) {
405
355
  const write = options.write ?? ((s) => process.stdout.write(s));
406
356
  const env = options.env ?? process.env;
@@ -418,41 +368,37 @@ async function runAsk(argv, options = {}) {
418
368
  else if (a === "--ns" || a === "--project") {
419
369
  const v = argv[++i];
420
370
  if (v === void 0 || v.startsWith("--")) {
421
- write(USAGE);
371
+ write(USAGE$1);
422
372
  return 2;
423
373
  }
424
374
  if (a === "--ns") ns = v;
425
375
  else project = v;
426
376
  } else words.push(a);
427
377
  }
428
- const endpoint = trimTrailingSlashes(env.SUBSTRATE_URL ?? "");
429
- if (endpoint === "") {
378
+ if ((env.SUBSTRATE_URL ?? "") === "") {
430
379
  write("SUBSTRATE_URL is required (e.g. https://substrate.example.com:3100)\n");
431
380
  return 2;
432
381
  }
433
382
  const question = words.join(" ").trim();
434
383
  if (question === "") {
435
- write(USAGE);
384
+ write(USAGE$1);
436
385
  return 2;
437
386
  }
438
387
  if (ns === void 0) {
439
388
  write("substrate ask: name the namespace with --ns or SUBSTRATE_NAMESPACE\n");
440
389
  return 2;
441
390
  }
442
- let bearer;
391
+ let client;
443
392
  try {
444
- bearer = makeAgentJwtProvider(env);
445
- if (bearer() !== null) bearer = makeAgentJwtProvider(env, tokenAudience(endpoint));
393
+ ({client} = createClientFromEnv({
394
+ env,
395
+ allowAnonymous: true,
396
+ ...options.fetchImpl !== void 0 ? { fetch: options.fetchImpl } : {}
397
+ }));
446
398
  } catch (err) {
447
- write(`substrate ask: agent identity: ${messageOf(err)}\n`);
399
+ write(`substrate ask: agent identity: ${messageOf$1(err)}\n`);
448
400
  return 2;
449
401
  }
450
- const signed = bearer() !== null;
451
- const client = new SubstrateClient({
452
- endpoint,
453
- ...signed ? { getToken: () => (bearer() ?? "").replace(/^Bearer /, "") } : {},
454
- fetch: noRedirectFetch(options.fetchImpl)
455
- });
456
402
  let result;
457
403
  try {
458
404
  result = await client.nl.askJson({
@@ -463,7 +409,7 @@ async function runAsk(argv, options = {}) {
463
409
  } catch (err) {
464
410
  if (err instanceof NetworkError && err.status === 404 && err.code !== "nl_unknown_namespace") write("substrate ask: the server has no NL route (is @mnmal-ai/substrate-nl installed?)\n");
465
411
  else if (err instanceof NetworkError && err.serverMessage !== void 0) write(`substrate ask: ${err.serverMessage}\n`);
466
- else write(`substrate ask: ${messageOf(err)}\n`);
412
+ else write(`substrate ask: ${messageOf$1(err)}\n`);
467
413
  return 1;
468
414
  }
469
415
  const outcome = result.outcome;
@@ -474,7 +420,7 @@ async function runAsk(argv, options = {}) {
474
420
  if (outcome.kind === "rows" && Array.isArray(outcome.errors) && outcome.errors.length > 0) return 1;
475
421
  return 0;
476
422
  }
477
- function messageOf(err) {
423
+ function messageOf$1(err) {
478
424
  return err instanceof Error ? err.message : String(err);
479
425
  }
480
426
  function render(o) {
@@ -4556,6 +4502,142 @@ async function runNormaliseVocab(argv, options = {}) {
4556
4502
  return 0;
4557
4503
  }
4558
4504
 
4505
+ //#endregion
4506
+ //#region src/cli/run/main.ts
4507
+ const USAGE = "usage: substrate run <script.mts> [--args <json>] [--dry-run | --write] [--max-writes <n>] [--out <file>]\n";
4508
+ /**
4509
+ * Runs a script's default export against a signed, guarded client and prints
4510
+ * one JSON report: the script's return value, every mutation, warnings, stats.
4511
+ */
4512
+ async function runRun(argv, options = {}) {
4513
+ const write = options.write ?? ((s) => process.stdout.write(s));
4514
+ let script;
4515
+ let mode = "read";
4516
+ let maxWrites = 50;
4517
+ let out;
4518
+ let args = {};
4519
+ for (let i = 0; i < argv.length; i++) {
4520
+ const a = argv[i];
4521
+ if (a === "--dry-run" || a === "--write") {
4522
+ const next = a === "--write" ? "write" : "dry-run";
4523
+ if (mode !== "read" && mode !== next) {
4524
+ write("substrate run: --dry-run and --write are exclusive\n");
4525
+ return 2;
4526
+ }
4527
+ mode = next;
4528
+ } else if (a === "--max-writes" || a === "--out" || a === "--args") {
4529
+ const v = argv[++i];
4530
+ if (v === void 0 || v.startsWith("--")) {
4531
+ write(USAGE);
4532
+ return 2;
4533
+ }
4534
+ if (a === "--out") out = v;
4535
+ else if (a === "--args") {
4536
+ let parsed;
4537
+ try {
4538
+ parsed = JSON.parse(v);
4539
+ } catch {
4540
+ parsed = void 0;
4541
+ }
4542
+ if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
4543
+ write("substrate run: --args takes a JSON object, e.g. '{\"project\":\"substrate\"}'\n");
4544
+ return 2;
4545
+ }
4546
+ args = parsed;
4547
+ } else {
4548
+ maxWrites = Number(v);
4549
+ if (!Number.isInteger(maxWrites) || maxWrites < 0) {
4550
+ write("substrate run: --max-writes takes a non-negative integer\n");
4551
+ return 2;
4552
+ }
4553
+ }
4554
+ } else if (script === void 0 && !a.startsWith("--")) script = a;
4555
+ else {
4556
+ write(USAGE);
4557
+ return 2;
4558
+ }
4559
+ }
4560
+ if (script === void 0) {
4561
+ write(USAGE);
4562
+ return 2;
4563
+ }
4564
+ let entry;
4565
+ try {
4566
+ entry = (await import(pathToFileURL(resolve(script)).href)).default;
4567
+ } catch (err) {
4568
+ write(`substrate run: cannot load ${script}: ${messageOf(err)}\n`);
4569
+ return 2;
4570
+ }
4571
+ if (typeof entry !== "function") {
4572
+ write(`substrate run: ${script} must default-export a function (s) => result\n`);
4573
+ return 2;
4574
+ }
4575
+ let client;
4576
+ let kid;
4577
+ try {
4578
+ ({client, kid} = createClientFromEnv({
4579
+ ...options.env !== void 0 ? { env: options.env } : {},
4580
+ ...options.fetchImpl !== void 0 ? { fetch: options.fetchImpl } : {}
4581
+ }));
4582
+ } catch (err) {
4583
+ write(`substrate run: agent identity: ${messageOf(err)}\n`);
4584
+ return 2;
4585
+ }
4586
+ const report = await runScript(entry, {
4587
+ client,
4588
+ kid,
4589
+ mode,
4590
+ args,
4591
+ maxWrites
4592
+ });
4593
+ await client.close();
4594
+ const json = `${JSON.stringify(report, null, 2)}\n`;
4595
+ if (out !== void 0) {
4596
+ writeFileSync(out, json);
4597
+ write(`${report.ok ? "ok" : `failed: ${report.error}`} · ${report.mutations.length} mutation(s) · ${report.warnings.length} warning(s) · report in ${out}\n`);
4598
+ } else write(json);
4599
+ return report.ok ? 0 : 1;
4600
+ }
4601
+ function messageOf(err) {
4602
+ return err instanceof Error ? err.message : String(err);
4603
+ }
4604
+
4605
+ //#endregion
4606
+ //#region src/mcp/agent-jwt.ts
4607
+ /**
4608
+ * Optional agent-identity JWT provider for the MCP client. When
4609
+ * SUBSTRATE_AGENT_KEY_PATH (path to an Ed25519 private PEM) + SUBSTRATE_AGENT_KEY_ID are
4610
+ * set, returns a cached short-TTL EdDSA JWT (refreshed before expiry) that the
4611
+ * stack verifies in attribute mode → createdBy:{kind:'agent', id:<kid>}.
4612
+ * Returns null when neither is set (the MCP client then sends no Authorization);
4613
+ * setting only one throws.
4614
+ *
4615
+ * Fail-loud by design: a SET-but-missing/malformed SUBSTRATE_AGENT_KEY_PATH
4616
+ * throws at provider construction, crashing MCP startup — misconfiguration
4617
+ * must not silently degrade to anonymous writes.
4618
+ */
4619
+ /**
4620
+ * Returns a provider that yields `Bearer <jwt>` (the full Authorization header
4621
+ * value) when SUBSTRATE_AGENT_KEY_PATH + SUBSTRATE_AGENT_KEY_ID are set, or null when
4622
+ * unconfigured so callers can skip the header entirely.
4623
+ */
4624
+ function makeAgentJwtProvider(env, audience) {
4625
+ const keyPath = env.SUBSTRATE_AGENT_KEY_PATH;
4626
+ const kid = env.SUBSTRATE_AGENT_KEY_ID;
4627
+ const hasPath = keyPath !== void 0 && keyPath !== "";
4628
+ const hasKid = kid !== void 0 && kid !== "";
4629
+ if (!hasPath && !hasKid) return () => null;
4630
+ if (!hasPath || !hasKid) throw new Error(`SUBSTRATE_AGENT_KEY_PATH and SUBSTRATE_AGENT_KEY_ID must be set together; only ${hasPath ? "SUBSTRATE_AGENT_KEY_PATH" : "SUBSTRATE_AGENT_KEY_ID"} is set`);
4631
+ const provider = makeAuthorizationProvider({
4632
+ keyPath,
4633
+ kid
4634
+ }, {
4635
+ capabilities: resolveAgentCapabilities(env),
4636
+ ...audience !== void 0 ? { audience } : {}
4637
+ });
4638
+ return () => provider();
4639
+ }
4640
+
4559
4641
  //#endregion
4560
4642
  //#region src/mcp/server.ts
4561
4643
  /**
@@ -5003,6 +5085,7 @@ async function runMcp() {
5003
5085
  * substrate normalise-vocab — rewrite stored vocabulary aliases to canonical values
5004
5086
  * substrate backfill-field — write per-row values of one field, metadata preserved
5005
5087
  * substrate ask — ask a natural-language question (./cli/ask)
5088
+ * substrate run — run a script against a signed, guarded client (./cli/run)
5006
5089
  * substrate federate — enroll / join / check bridges (./cli/federate)
5007
5090
  *
5008
5091
  * No flags-vs-subcommand ambiguity: subcommands are always argv[2].
@@ -5025,6 +5108,11 @@ Subcommands:
5025
5108
  Run \`substrate federate\` for the verb list.
5026
5109
  ask <question> Ask a natural-language question (needs the substrate-nl plugin).
5027
5110
  Flags: --ns, --project, --json. Reads SUBSTRATE_URL.
5111
+ run <script.mts> [--args <json>] [--dry-run | --write] [--max-writes <n>] [--out <file>]
5112
+ Run a script's default export (s) => result against a client
5113
+ signed from SUBSTRATE_URL + SUBSTRATE_AGENT_KEY_ID/_PATH, and
5114
+ print one JSON report. --args is a JSON object, read as s.args. Read-only unless --dry-run (records
5115
+ mutations) or --write (sends up to --max-writes frames, 50).
5028
5116
  check-enums [--json] [--record]
5029
5117
  Report stored values outside a field's declared enum.
5030
5118
  Read-only over HTTP (--record writes verdict rows); reads
@@ -5102,6 +5190,7 @@ async function runCli(argv) {
5102
5190
  case "normalise-vocab": return await runNormaliseVocab(rest);
5103
5191
  case "backfill-field": return await runBackfillField(rest);
5104
5192
  case "ask": return await runAsk(rest);
5193
+ case "run": return await runRun(rest);
5105
5194
  case "federate": return await runFederate(rest, process.env, (s) => process.stdout.write(s), (s) => process.stderr.write(s));
5106
5195
  default:
5107
5196
  process.stderr.write(`substrate: unknown subcommand '${subcommand}'\n\n`);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@mnmal-ai/substrate",
3
- "version": "1.0.0-alpha.5",
3
+ "version": "1.0.0-alpha.6",
4
4
  "description": "Substrate — an agent-first typed-data server: the substrate and substrate-admin binaries, the built-in plugins and the SDK subpaths.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -36,24 +36,24 @@
36
36
  },
37
37
  "devDependencies": {
38
38
  "@inquirer/prompts": "^8.7.2",
39
- "@mnmal-ai/substrate-bootstrap": "1.0.0-alpha.5",
40
- "@mnmal-ai/substrate-client": "1.0.0-alpha.5",
41
- "@mnmal-ai/substrate-compose": "1.0.0-alpha.5",
42
- "@mnmal-ai/substrate-config": "1.0.0-alpha.5",
43
- "@mnmal-ai/substrate-core": "1.0.0-alpha.5",
44
- "@mnmal-ai/substrate-dataset-memory": "1.0.0-alpha.5",
45
- "@mnmal-ai/substrate-dataset-pg": "1.0.0-alpha.5",
46
- "@mnmal-ai/substrate-embedder": "1.0.0-alpha.5",
47
- "@mnmal-ai/substrate-filter": "1.0.0-alpha.5",
48
- "@mnmal-ai/substrate-pack": "1.0.0-alpha.5",
49
- "@mnmal-ai/substrate-policy": "1.0.0-alpha.5",
50
- "@mnmal-ai/substrate-proposals": "1.0.0-alpha.5",
51
- "@mnmal-ai/substrate-recall": "1.0.0-alpha.5",
52
- "@mnmal-ai/substrate-sdk": "1.0.0-alpha.5",
53
- "@mnmal-ai/substrate-sentinel-client": "1.0.0-alpha.5",
54
- "@mnmal-ai/substrate-server-fastify": "1.0.0-alpha.5",
55
- "@mnmal-ai/substrate-server-memory": "1.0.0-alpha.5",
56
- "@mnmal-ai/substrate-types": "1.0.0-alpha.5",
39
+ "@mnmal-ai/substrate-bootstrap": "1.0.0-alpha.6",
40
+ "@mnmal-ai/substrate-client": "1.0.0-alpha.6",
41
+ "@mnmal-ai/substrate-compose": "1.0.0-alpha.6",
42
+ "@mnmal-ai/substrate-config": "1.0.0-alpha.6",
43
+ "@mnmal-ai/substrate-core": "1.0.0-alpha.6",
44
+ "@mnmal-ai/substrate-dataset-memory": "1.0.0-alpha.6",
45
+ "@mnmal-ai/substrate-dataset-pg": "1.0.0-alpha.6",
46
+ "@mnmal-ai/substrate-embedder": "1.0.0-alpha.6",
47
+ "@mnmal-ai/substrate-filter": "1.0.0-alpha.6",
48
+ "@mnmal-ai/substrate-pack": "1.0.0-alpha.6",
49
+ "@mnmal-ai/substrate-policy": "1.0.0-alpha.6",
50
+ "@mnmal-ai/substrate-proposals": "1.0.0-alpha.6",
51
+ "@mnmal-ai/substrate-recall": "1.0.0-alpha.6",
52
+ "@mnmal-ai/substrate-sdk": "1.0.0-alpha.6",
53
+ "@mnmal-ai/substrate-sentinel-client": "1.0.0-alpha.6",
54
+ "@mnmal-ai/substrate-server-fastify": "1.0.0-alpha.6",
55
+ "@mnmal-ai/substrate-server-memory": "1.0.0-alpha.6",
56
+ "@mnmal-ai/substrate-types": "1.0.0-alpha.6",
57
57
  "@types/node": "^26.6.4",
58
58
  "@types/semver": "^7.5.0",
59
59
  "@types/ws": "^8.18.1",