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

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.
@@ -63,7 +99,7 @@ set -a && source .env && set +a
63
99
  ./node_modules/.bin/substrate serve
64
100
  ```
65
101
 
66
- `substrate init` writes a `package.json` pinning `@mnmal-ai/substrate` and the chosen optional plugins, a `.npmrc` for the `@mnmal-ai` registry, a `.env` with `SUBSTRATE_PLUGIN_DIR=.`, a `substrate-recall.config.json` for the embedder, and, unless `--store=memory`, a `docker-compose.yml` running `pgvector/pgvector:pg17`. Flags: `--store=memory|postgres`, `--port`, `--pg-port`, `--plugins=<csv>` (from `cortext`, `substrate-nl`, `substrate-sentinel`; none by default), `--embedder=minilm|bge-base|ollama|none`, `--tls --tls-cert-path --tls-key-path`, `--substrate-url`, `--yes`, `--force`.
102
+ `substrate init` writes a `package.json` pinning `@mnmal-ai/substrate` and the chosen optional plugins, a `.npmrc` for the `@mnmal-ai` registry, a `.env` with `SUBSTRATE_PLUGIN_DIR=.`, a `substrate-recall.config.json` for the embedder, and, unless `--store=memory`, a `docker-compose.yml` running `pgvector/pgvector:pg17`. Flags: `--store=memory|postgres`, `--port`, `--pg-port`, `--plugins=<csv>` (from `cortext`, `substrate-nl`, `substrate-sentinel`; none by default), `--embedder=bge-base|minilm|ollama|none` (default `bge-base`), `--tls --tls-cert-path --tls-key-path`, `--substrate-url`, `--yes`, `--force`.
67
103
 
68
104
  `SUBSTRATE_PLUGIN_DIR` is the directory whose `node_modules/` holds the plugins; in a scaffolded runtime that is the runtime directory itself. Recall and proposals load from `@mnmal-ai/substrate` itself, so they are present whenever the binary is installed there. Kernel plugins (`substrate-recall`, `substrate-nl`) compose first, then coordinators (`substrate-proposals`, `substrate-sentinel`, …), alphabetical within each tier. Per-plugin overrides live at `<SUBSTRATE_PLUGIN_DIR>/<pkg-basename>.config.json`. With `SUBSTRATE_PLUGIN_DIR` unset the binary boots with only the `_system` admin namespace and `/health`.
69
105
 
@@ -82,7 +118,7 @@ cat > substrate-recall.config.json <<'EOF'
82
118
  EOF
83
119
  ```
84
120
 
85
- `kind: "onnx"` runs the model in-process and needs `fastembed` installed in the runtime (the embedder code itself ships in `@mnmal-ai/substrate`); `substrate init` adds it for `--embedder=minilm` (the default) and `--embedder=bge-base`. `kind: "ollama"` takes a `baseUrl` instead.
121
+ `kind: "onnx"` runs the model in-process and needs `fastembed` installed in the runtime (the embedder code itself ships in `@mnmal-ai/substrate`); `substrate init` adds it for `--embedder=bge-base` (the default) and `--embedder=minilm`. `kind: "ollama"` takes a `baseUrl` instead.
86
122
 
87
123
  ## Docker
88
124
 
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 };
@@ -1,9 +1,9 @@
1
1
  import { createRequire as __binCreateRequire } from 'node:module'; const require = __binCreateRequire(import.meta.url);
2
- import { d as buildAuditRow, f as AUDIT_EVENT_TYPE } from "./src-CHp3QyqB.js";
2
+ import { d as buildAuditRow, f as AUDIT_EVENT_TYPE } from "./src-B0BJcyKb.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";
6
- import { i as pendingMigrations, o as runMigrations, t as PgDataset } from "./src-CXKnqeTW.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
+ import { i as pendingMigrations, o as runMigrations, t as PgDataset } from "./src-CBV88iyK.js";
7
7
  import { existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
8
8
  import { homedir } from "node:os";
9
9
  import { dirname, join } from "node:path";
@@ -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.7";
15
15
 
16
16
  //#endregion
17
17
  //#region src/admin/errors.ts
@@ -1,5 +1,5 @@
1
1
  import { createRequire as __binCreateRequire } from 'node:module'; const require = __binCreateRequire(import.meta.url);
2
- import { n as txScopeIdFor } from "./src-CXKnqeTW.js";
2
+ import { n as txScopeIdFor } from "./src-CBV88iyK.js";
3
3
  import { randomUUID } from "node:crypto";
4
4
 
5
5
  //#region ../../packages/substrate-dataset-pg/src/pg-edges-store.ts
@@ -1,5 +1,5 @@
1
1
  import { createRequire as __binCreateRequire } from 'node:module'; const require = __binCreateRequire(import.meta.url);
2
- import { L as applyObligations, Q as buildContext, et as jsonResponse, wt as ResolverFrameError } from "./src-CHp3QyqB.js";
2
+ import { L as applyObligations, Q as buildContext, et as jsonResponse, wt as ResolverFrameError } from "./src-B0BJcyKb.js";
3
3
  import { Worker } from "node:worker_threads";
4
4
 
5
5
  //#region ../../plugins/substrate-recall/src/candidate-selection.ts
@@ -1,6 +1,6 @@
1
1
  import { createRequire as __binCreateRequire } from 'node:module'; const require = __binCreateRequire(import.meta.url);
2
- import { Pt as defineBootstrap } from "./src-CHp3QyqB.js";
3
- import { n as createNoopPubSub, t as createProposalsPlugin } from "./src-CG7giuHr.js";
2
+ import { Pt as defineBootstrap } from "./src-B0BJcyKb.js";
3
+ import { n as createNoopPubSub, t as createProposalsPlugin } from "./src-DgLqCklp.js";
4
4
  import { z } from "zod";
5
5
 
6
6
  //#region ../../plugins/substrate-proposals/src/bootstrap.ts
package/dist/proposals.js CHANGED
@@ -1,4 +1,4 @@
1
1
  import { createRequire as __binCreateRequire } from 'node:module'; const require = __binCreateRequire(import.meta.url);
2
- import { n as createNoopPubSub, r as ProposalError, t as createProposalsPlugin } from "./src-CG7giuHr.js";
2
+ import { n as createNoopPubSub, r as ProposalError, t as createProposalsPlugin } from "./src-DgLqCklp.js";
3
3
 
4
4
  export { ProposalError, createNoopPubSub, createProposalsPlugin };
@@ -1,7 +1,7 @@
1
1
  import { createRequire as __binCreateRequire } from 'node:module'; const require = __binCreateRequire(import.meta.url);
2
- import { Pt as defineBootstrap } from "./src-CHp3QyqB.js";
2
+ import { Pt as defineBootstrap } from "./src-B0BJcyKb.js";
3
3
  import { t as FakeEmbedder } from "./fake-DUVtKVSE.js";
4
- import { t as createRecallPlugin } from "./plugin-BG8E04wi.js";
4
+ import { t as createRecallPlugin } from "./plugin-0dPAYAEm.js";
5
5
  import { z } from "zod";
6
6
 
7
7
  //#region ../../packages/substrate-embedder/src/types.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";
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";
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-C9pC-AKI.js";
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-0dPAYAEm.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 };
@@ -2146,18 +2146,18 @@ async function runRepl(seed) {
2146
2146
  }));
2147
2147
  const embedder = seed.embedder ?? await dist_default({
2148
2148
  message: "Semantic recall embedder:",
2149
- default: "minilm",
2149
+ default: "bge-base",
2150
2150
  choices: [
2151
2151
  {
2152
- name: "minilm — all-MiniLM-L6-v2, in-process (recommended)",
2153
- value: "minilm"
2152
+ name: "bge-base — bge-base-en-v1.5, in-process (recommended)",
2153
+ value: "bge-base"
2154
2154
  },
2155
2155
  {
2156
- name: "bge-base — bge-base-en-v1.5, in-process, slower and stronger",
2157
- value: "bge-base"
2156
+ name: "minilm — all-MiniLM-L6-v2, in-process, smaller and faster",
2157
+ value: "minilm"
2158
2158
  },
2159
2159
  {
2160
- name: "ollama — bge-m3 via local Ollama",
2160
+ name: "ollama — bge-base-en-v1.5 via local Ollama",
2161
2161
  value: "ollama"
2162
2162
  },
2163
2163
  {
@@ -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 };
package/dist/sdk.js CHANGED
@@ -1,5 +1,5 @@
1
1
  import { createRequire as __binCreateRequire } from 'node:module'; const require = __binCreateRequire(import.meta.url);
2
- import { $ as error400, A as resolveIdentity, At as CLIENT_SUPPLIED_SERVER_FIELD, C as purgeResolver, Ct as ReservedField, D as deleteRow, Dt as isAuthCause, E as deleteResolver, Et as UnsupportedFilterError, M as resolveEntityRow, Mt as canonicalize, Nt as BootstrapConfigError, O as createResolver, Ot as isResolverFrameError, Pt as defineBootstrap, S as updateResolver, St as NamespaceMismatch, T as getResolver, Tt as RestrictViolation, Z as JSON_HEADERS, _ as field, _t as createKeyedMutex, at as WS_REASON_SERVER_RESTART, b as installAutoCrud, bt as BridgeUnreachableError, ct as normaliseVocabValues, dt as vocabImplication, et as jsonResponse, ft as RegistryBase, g as RESERVED_AUTOCRUD_FIELD_NAMES, gt as normaliseMetadataWhere, h as RESERVED_AUTOCRUD_FIELDS, ht as normaliseMetadataOrderBy, it as WS_CODE_SUBSCRIPTION_UNSUPPORTED_FRAME, j as resolveEntityId, jt as ROW_METADATA_FIELDS, k as UnattributedWriteError, kt as isRestrictViolation, lt as normaliseVocabWhere, m as defineNamespace, mt as METADATA_FILTER_FIELDS, ot as WS_REASON_SUBSCRIPTION_OVERLOADED, pt as METADATA_AUTHOR_FIELDS, st as canonicalVocabValue, tt as parseJsonBody, ut as storedVocabSpellings, v as autoCrudOptionsOf, vt as assertHardDeleteAllowed, w as listResolver, wt as ResolverFrameError, x as applyUpdatePatch, xt as MissingReferentError, y as createResolverWithEdges, yt as validateHardDeleteEnv } from "./src-CHp3QyqB.js";
2
+ import { $ as error400, A as resolveIdentity, At as CLIENT_SUPPLIED_SERVER_FIELD, C as purgeResolver, Ct as ReservedField, D as deleteRow, Dt as isAuthCause, E as deleteResolver, Et as UnsupportedFilterError, M as resolveEntityRow, Mt as canonicalize, Nt as BootstrapConfigError, O as createResolver, Ot as isResolverFrameError, Pt as defineBootstrap, S as updateResolver, St as NamespaceMismatch, T as getResolver, Tt as RestrictViolation, Z as JSON_HEADERS, _ as field, _t as createKeyedMutex, at as WS_REASON_SERVER_RESTART, b as installAutoCrud, bt as BridgeUnreachableError, ct as normaliseVocabValues, dt as vocabImplication, et as jsonResponse, ft as RegistryBase, g as RESERVED_AUTOCRUD_FIELD_NAMES, gt as normaliseMetadataWhere, h as RESERVED_AUTOCRUD_FIELDS, ht as normaliseMetadataOrderBy, it as WS_CODE_SUBSCRIPTION_UNSUPPORTED_FRAME, j as resolveEntityId, jt as ROW_METADATA_FIELDS, k as UnattributedWriteError, kt as isRestrictViolation, lt as normaliseVocabWhere, m as defineNamespace, mt as METADATA_FILTER_FIELDS, ot as WS_REASON_SUBSCRIPTION_OVERLOADED, pt as METADATA_AUTHOR_FIELDS, st as canonicalVocabValue, tt as parseJsonBody, ut as storedVocabSpellings, v as autoCrudOptionsOf, vt as assertHardDeleteAllowed, w as listResolver, wt as ResolverFrameError, x as applyUpdatePatch, xt as MissingReferentError, y as createResolverWithEdges, yt as validateHardDeleteEnv } from "./src-B0BJcyKb.js";
3
3
  import { a as adminClaimCapabilities, c as makeTokenProvider, d as resolveDefaultKidPath, i as DEFAULT_CAPABILITIES, l as resolveAdminCredential, n as trimTrailingSlashes, o as isEncryptedKey, r as ADMIN_CAPABILITIES, s as makeAuthorizationProvider, t as parsePositiveInt, u as resolveDefaultKeyPath } from "./env-utils-CGNazUNt.js";
4
4
  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, d as confersAnywhere, f as coversNamespace, g as checkUpdatable, h as checkRevocable, i as allowVerbs, j as flattenGrant, k as encodeGrant, l as requireNamespace, m as grantedIn, n as row, o as denyVerbs, p as grantOf, r as allowAll, s as requireCapability, t as applyRowFilters, u as allCapabilities, v as grantEntriesConfer, w as or, x as revokedAtIso, y as newlyGranted } from "./row-DZ0Fnpc6.js";
5
5
  import { S as assertNever, b as formatQualifiedKey, x as parseQualifiedKey } from "./src-BLgbLq2k.js";
@@ -924,7 +924,8 @@ function authenticateBearer(token, cfg) {
924
924
  if (maxLifetime > 0 && payload.exp > nowSeconds + maxLifetime + leeway) return reject("lifetime_exceeds_max");
925
925
  }
926
926
  if (typeof payload.nbf === "number" && payload.nbf > nowSeconds + leeway) return reject("not_yet_valid");
927
- if (cfg.audiences !== void 0 && payload.aud !== void 0) {
927
+ if (cfg.audiences !== void 0) {
928
+ if (payload.aud === void 0) return reject("missing_audience");
928
929
  if (!(Array.isArray(payload.aud) ? payload.aud : [payload.aud]).some((a) => cfg.audiences?.includes(a))) return reject("wrong_audience");
929
930
  }
930
931
  const claimedCapabilities = Array.isArray(payload.capabilities) ? payload.capabilities.filter((c) => typeof c === "string") : [];
@@ -963,6 +964,7 @@ function authenticateBearer(token, cfg) {
963
964
  /** What a 401 should add for a reason whose fix is a server knob, not the token. */
964
965
  function rejectionDetail(reason) {
965
966
  if (reason === "lifetime_exceeds_max") return "the token expires further ahead than this server accepts; mint a shorter-lived token or raise SUBSTRATE_JWT_MAX_TTL_SECONDS";
967
+ if (reason === "missing_audience") return "the token has no aud; mint it with aud set to this server's origin (e.g. https://host:3100)";
966
968
  if (reason === "wrong_audience") return "the token's aud is not one of this server's origins; connect through an origin listed in SUBSTRATE_PUBLIC_ORIGIN, or add this one there";
967
969
  }
968
970
  /**
@@ -1,9 +1,9 @@
1
1
  import { createRequire as __binCreateRequire } from 'node:module'; const require = __binCreateRequire(import.meta.url);
2
- import { n as txScopeIdFor } from "./src-CXKnqeTW.js";
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";
2
+ import { n as txScopeIdFor } from "./src-CBV88iyK.js";
3
+ import { B as ROW_FILTER_FIELD, V as matchesRowFilter, W as inFlightError, Y as unresolvedRow, Z as cosineSimilarity, et as memberKey } from "./plugin-0dPAYAEm.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.7";
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 { Ct as ReservedField, Et as UnsupportedFilterError, H as assertJsonPathPredicate, J as fullBuiltinOperators, K as decodeCursor, St as NamespaceMismatch, U as isJsonPathPredicate, V as preResolveExtensionOperatorsDetailed, X as fieldRequested, Y as applyExtensionResultMeta, _t as createKeyedMutex, q as encodeCursor } from "./src-CHp3QyqB.js";
2
+ import { Ct as ReservedField, Et as UnsupportedFilterError, H as assertJsonPathPredicate, J as fullBuiltinOperators, K as decodeCursor, St as NamespaceMismatch, U as isJsonPathPredicate, V as preResolveExtensionOperatorsDetailed, X as fieldRequested, Y as applyExtensionResultMeta, _t as createKeyedMutex, q as encodeCursor } from "./src-B0BJcyKb.js";
3
3
  import { createHash, randomUUID } from "node:crypto";
4
4
 
5
5
  //#region ../../packages/substrate-dataset-pg/src/advisory-lock.ts
@@ -1,5 +1,5 @@
1
1
  import { createRequire as __binCreateRequire } from 'node:module'; const require = __binCreateRequire(import.meta.url);
2
- import { A as resolveIdentity, F as publishSchema, Z as JSON_HEADERS, _ as field, b as installAutoCrud, h as RESERVED_AUTOCRUD_FIELDS, l as migrateFieldValues, m as defineNamespace, v as autoCrudOptionsOf, wt as ResolverFrameError } from "./src-CHp3QyqB.js";
2
+ import { A as resolveIdentity, F as publishSchema, Z as JSON_HEADERS, _ as field, b as installAutoCrud, h as RESERVED_AUTOCRUD_FIELDS, l as migrateFieldValues, m as defineNamespace, v as autoCrudOptionsOf, wt as ResolverFrameError } from "./src-B0BJcyKb.js";
3
3
  import { s as requireCapability } from "./row-DZ0Fnpc6.js";
4
4
  import { randomUUID } from "node:crypto";
5
5
 
@@ -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 };
@@ -1,10 +1,10 @@
1
1
  #!/usr/bin/env node
2
2
  import { createRequire as __binCreateRequire } from 'node:module'; const require = __binCreateRequire(import.meta.url);
3
- import { d as buildAuditRow, f as AUDIT_EVENT_TYPE } from "./src-CHp3QyqB.js";
3
+ import { d as buildAuditRow, f as AUDIT_EVENT_TYPE } from "./src-B0BJcyKb.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-DuPv47JG.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
- 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";
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-B0BJcyKb.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";
7
- import { a as runDerivedMigrations, o as runMigrations, r as deriveListIndexMigration, s as tryWithPgAdvisoryLock, t as PgDataset } from "./src-CXKnqeTW.js";
8
- 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";
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";
8
+ import { a as runDerivedMigrations, o as runMigrations, r as deriveListIndexMigration, s as tryWithPgAdvisoryLock, t as PgDataset } from "./src-CBV88iyK.js";
9
+ import { t as PgEdgesStore } from "./pg-edges-store-CKu6M8PU.js";
10
+ import { a as InMemoryLexicalStore, i as PgClusterStore, n as PgLexicalStore, o as InMemoryEmbeddingsStore, r as PgEmbeddingsStore, s as InMemoryClusterStore } from "./src-C9pC-AKI.js";
11
+ import { B as version, R as openSql, t as openPgDataset, z as AdminCliError } from "./dataset-DuPv47JG.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) {
@@ -1516,7 +1462,10 @@ function startSentinelClient(opts) {
1516
1462
  });
1517
1463
  return;
1518
1464
  }
1519
- const auth = makeAuthorizationProvider(cred, { lazyKey: true });
1465
+ const auth = makeAuthorizationProvider(cred, {
1466
+ lazyKey: true,
1467
+ audience: cred.origin
1468
+ });
1520
1469
  for (const nsValue of namespaces) {
1521
1470
  if (stopped) return;
1522
1471
  if (typeof nsValue !== "string" || nsValue.length === 0) continue;
@@ -1771,7 +1720,7 @@ function buildBridgeRegistry(specs, creds) {
1771
1720
  throw new Error(`bridge '${spec.name}' has a malformed url '${spec.url}'`);
1772
1721
  }
1773
1722
  if (specOrigin !== cred.origin) throw new Error(`bridge '${spec.name}' url origin '${specOrigin}' does not match its credential origin '${cred.origin}'`);
1774
- const auth = makeAuthorizationProvider(cred);
1723
+ const auth = makeAuthorizationProvider(cred, { audience: cred.origin });
1775
1724
  const client = new HttpBridgeClient({
1776
1725
  name: spec.name,
1777
1726
  baseUrl: spec.url,
@@ -2406,7 +2355,7 @@ function startBackground(args) {
2406
2355
  bridges: bridgeRegistry,
2407
2356
  engine,
2408
2357
  creds: config.bridgeCreds,
2409
- auth: makeAuthorizationProvider(sentinelClientConfig.cred),
2358
+ auth: makeAuthorizationProvider(sentinelClientConfig.cred, { audience: new URL(sentinelClientConfig.url.replace(/^ws/, "http")).origin }),
2410
2359
  metric: (name, payload) => {
2411
2360
  process.stdout.write(`sentinel-client.${name} ${JSON.stringify(payload ?? null)}\n`);
2412
2361
  },
@@ -4028,8 +3977,8 @@ async function runFederate(argv, env, out, errOut) {
4028
3977
  //#endregion
4029
3978
  //#region src/cli/init/config.ts
4030
3979
  const EMBEDDER_MODES = [
4031
- "minilm",
4032
3980
  "bge-base",
3981
+ "minilm",
4033
3982
  "ollama",
4034
3983
  "none"
4035
3984
  ];
@@ -4220,8 +4169,8 @@ function recallConfigTemplate(embedder, runtimeDir) {
4220
4169
  const config = embedder === "ollama" ? { embedder: {
4221
4170
  kind: "ollama",
4222
4171
  baseUrl: "http://localhost:11434",
4223
- model: "bge-m3",
4224
- dimension: 1024
4172
+ model: "hf.co/CompendiumLabs/bge-base-en-v1.5-gguf:F16",
4173
+ dimension: 768
4225
4174
  } } : { embedder: {
4226
4175
  kind: "onnx",
4227
4176
  ...ONNX_MODELS[embedder],
@@ -4383,7 +4332,7 @@ function readmeTemplate(ctx) {
4383
4332
  return `${lines.join("\n")}\n`;
4384
4333
  }
4385
4334
  function recallReadmeLines(embedder) {
4386
- const lines = embedder === "ollama" ? ["`substrate-recall.config.json` points at Ollama on `localhost:11434` with `bge-m3`. Pull the model first: `ollama pull bge-m3`."] : [`\`substrate-recall.config.json\` runs \`${ONNX_MODELS[embedder].model}\` in-process through \`fastembed\`, which \`pnpm install\` adds (about 540MB, most of it ONNX Runtime). The first write downloads the model into \`models/\`.`];
4335
+ const lines = embedder === "ollama" ? ["`substrate-recall.config.json` points at Ollama on `localhost:11434` with bge-base-en-v1.5. Pull the model first: `ollama pull hf.co/CompendiumLabs/bge-base-en-v1.5-gguf:F16`."] : [`\`substrate-recall.config.json\` runs \`${ONNX_MODELS[embedder].model}\` in-process through \`fastembed\`, which \`pnpm install\` adds (about 540MB, most of it ONNX Runtime). The first write downloads the model into \`models/\`.`];
4387
4336
  lines.push("", "Recall also ranks by keyword, so a small model loses little. Changing model later means emptying the stored vectors and embedding every row again, through the admin route `POST /substrate/v1/embed/reindex`.");
4388
4337
  return lines;
4389
4338
  }
@@ -4407,7 +4356,7 @@ async function runInit(argv) {
4407
4356
  return 1;
4408
4357
  }
4409
4358
  if (!config.yes) try {
4410
- const { runRepl } = await import("./repl-C52wyfMs.js");
4359
+ const { runRepl } = await import("./repl-DiBeGwIW.js");
4411
4360
  config = await runRepl(config);
4412
4361
  } catch (err) {
4413
4362
  if (err.message?.includes("User force closed")) return 130;
@@ -4434,7 +4383,7 @@ async function runInit(argv) {
4434
4383
  port: config.port ?? 3100,
4435
4384
  pgPort: config.pgPort ?? 5433,
4436
4385
  plugins: [...config.plugins ?? []],
4437
- embedder: config.embedder ?? "minilm",
4386
+ embedder: config.embedder ?? "bge-base",
4438
4387
  substrateUrl: config.substrateUrl ?? `${config.tls ? "https" : "http"}://localhost:${config.port ?? 3100}`,
4439
4388
  tls: config.tls,
4440
4389
  tlsCertPath: config.tlsCertPath,
@@ -4556,6 +4505,142 @@ async function runNormaliseVocab(argv, options = {}) {
4556
4505
  return 0;
4557
4506
  }
4558
4507
 
4508
+ //#endregion
4509
+ //#region src/cli/run/main.ts
4510
+ const USAGE = "usage: substrate run <script.mts> [--args <json>] [--dry-run | --write] [--max-writes <n>] [--out <file>]\n";
4511
+ /**
4512
+ * Runs a script's default export against a signed, guarded client and prints
4513
+ * one JSON report: the script's return value, every mutation, warnings, stats.
4514
+ */
4515
+ async function runRun(argv, options = {}) {
4516
+ const write = options.write ?? ((s) => process.stdout.write(s));
4517
+ let script;
4518
+ let mode = "read";
4519
+ let maxWrites = 50;
4520
+ let out;
4521
+ let args = {};
4522
+ for (let i = 0; i < argv.length; i++) {
4523
+ const a = argv[i];
4524
+ if (a === "--dry-run" || a === "--write") {
4525
+ const next = a === "--write" ? "write" : "dry-run";
4526
+ if (mode !== "read" && mode !== next) {
4527
+ write("substrate run: --dry-run and --write are exclusive\n");
4528
+ return 2;
4529
+ }
4530
+ mode = next;
4531
+ } else if (a === "--max-writes" || a === "--out" || a === "--args") {
4532
+ const v = argv[++i];
4533
+ if (v === void 0 || v.startsWith("--")) {
4534
+ write(USAGE);
4535
+ return 2;
4536
+ }
4537
+ if (a === "--out") out = v;
4538
+ else if (a === "--args") {
4539
+ let parsed;
4540
+ try {
4541
+ parsed = JSON.parse(v);
4542
+ } catch {
4543
+ parsed = void 0;
4544
+ }
4545
+ if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
4546
+ write("substrate run: --args takes a JSON object, e.g. '{\"project\":\"substrate\"}'\n");
4547
+ return 2;
4548
+ }
4549
+ args = parsed;
4550
+ } else {
4551
+ maxWrites = Number(v);
4552
+ if (!Number.isInteger(maxWrites) || maxWrites < 0) {
4553
+ write("substrate run: --max-writes takes a non-negative integer\n");
4554
+ return 2;
4555
+ }
4556
+ }
4557
+ } else if (script === void 0 && !a.startsWith("--")) script = a;
4558
+ else {
4559
+ write(USAGE);
4560
+ return 2;
4561
+ }
4562
+ }
4563
+ if (script === void 0) {
4564
+ write(USAGE);
4565
+ return 2;
4566
+ }
4567
+ let entry;
4568
+ try {
4569
+ entry = (await import(pathToFileURL(resolve(script)).href)).default;
4570
+ } catch (err) {
4571
+ write(`substrate run: cannot load ${script}: ${messageOf(err)}\n`);
4572
+ return 2;
4573
+ }
4574
+ if (typeof entry !== "function") {
4575
+ write(`substrate run: ${script} must default-export a function (s) => result\n`);
4576
+ return 2;
4577
+ }
4578
+ let client;
4579
+ let kid;
4580
+ try {
4581
+ ({client, kid} = createClientFromEnv({
4582
+ ...options.env !== void 0 ? { env: options.env } : {},
4583
+ ...options.fetchImpl !== void 0 ? { fetch: options.fetchImpl } : {}
4584
+ }));
4585
+ } catch (err) {
4586
+ write(`substrate run: agent identity: ${messageOf(err)}\n`);
4587
+ return 2;
4588
+ }
4589
+ const report = await runScript(entry, {
4590
+ client,
4591
+ kid,
4592
+ mode,
4593
+ args,
4594
+ maxWrites
4595
+ });
4596
+ await client.close();
4597
+ const json = `${JSON.stringify(report, null, 2)}\n`;
4598
+ if (out !== void 0) {
4599
+ writeFileSync(out, json);
4600
+ write(`${report.ok ? "ok" : `failed: ${report.error}`} · ${report.mutations.length} mutation(s) · ${report.warnings.length} warning(s) · report in ${out}\n`);
4601
+ } else write(json);
4602
+ return report.ok ? 0 : 1;
4603
+ }
4604
+ function messageOf(err) {
4605
+ return err instanceof Error ? err.message : String(err);
4606
+ }
4607
+
4608
+ //#endregion
4609
+ //#region src/mcp/agent-jwt.ts
4610
+ /**
4611
+ * Optional agent-identity JWT provider for the MCP client. When
4612
+ * SUBSTRATE_AGENT_KEY_PATH (path to an Ed25519 private PEM) + SUBSTRATE_AGENT_KEY_ID are
4613
+ * set, returns a cached short-TTL EdDSA JWT (refreshed before expiry) that the
4614
+ * stack verifies in attribute mode → createdBy:{kind:'agent', id:<kid>}.
4615
+ * Returns null when neither is set (the MCP client then sends no Authorization);
4616
+ * setting only one throws.
4617
+ *
4618
+ * Fail-loud by design: a SET-but-missing/malformed SUBSTRATE_AGENT_KEY_PATH
4619
+ * throws at provider construction, crashing MCP startup — misconfiguration
4620
+ * must not silently degrade to anonymous writes.
4621
+ */
4622
+ /**
4623
+ * Returns a provider that yields `Bearer <jwt>` (the full Authorization header
4624
+ * value) when SUBSTRATE_AGENT_KEY_PATH + SUBSTRATE_AGENT_KEY_ID are set, or null when
4625
+ * unconfigured so callers can skip the header entirely.
4626
+ */
4627
+ function makeAgentJwtProvider(env, audience) {
4628
+ const keyPath = env.SUBSTRATE_AGENT_KEY_PATH;
4629
+ const kid = env.SUBSTRATE_AGENT_KEY_ID;
4630
+ const hasPath = keyPath !== void 0 && keyPath !== "";
4631
+ const hasKid = kid !== void 0 && kid !== "";
4632
+ if (!hasPath && !hasKid) return () => null;
4633
+ 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`);
4634
+ const provider = makeAuthorizationProvider({
4635
+ keyPath,
4636
+ kid
4637
+ }, {
4638
+ capabilities: resolveAgentCapabilities(env),
4639
+ ...audience !== void 0 ? { audience } : {}
4640
+ });
4641
+ return () => provider();
4642
+ }
4643
+
4559
4644
  //#endregion
4560
4645
  //#region src/mcp/server.ts
4561
4646
  /**
@@ -5003,6 +5088,7 @@ async function runMcp() {
5003
5088
  * substrate normalise-vocab — rewrite stored vocabulary aliases to canonical values
5004
5089
  * substrate backfill-field — write per-row values of one field, metadata preserved
5005
5090
  * substrate ask — ask a natural-language question (./cli/ask)
5091
+ * substrate run — run a script against a signed, guarded client (./cli/run)
5006
5092
  * substrate federate — enroll / join / check bridges (./cli/federate)
5007
5093
  *
5008
5094
  * No flags-vs-subcommand ambiguity: subcommands are always argv[2].
@@ -5025,6 +5111,11 @@ Subcommands:
5025
5111
  Run \`substrate federate\` for the verb list.
5026
5112
  ask <question> Ask a natural-language question (needs the substrate-nl plugin).
5027
5113
  Flags: --ns, --project, --json. Reads SUBSTRATE_URL.
5114
+ run <script.mts> [--args <json>] [--dry-run | --write] [--max-writes <n>] [--out <file>]
5115
+ Run a script's default export (s) => result against a client
5116
+ signed from SUBSTRATE_URL + SUBSTRATE_AGENT_KEY_ID/_PATH, and
5117
+ print one JSON report. --args is a JSON object, read as s.args. Read-only unless --dry-run (records
5118
+ mutations) or --write (sends up to --max-writes frames, 50).
5028
5119
  check-enums [--json] [--record]
5029
5120
  Report stored values outside a field's declared enum.
5030
5121
  Read-only over HTTP (--record writes verdict rows); reads
@@ -5058,9 +5149,9 @@ Environment for \`serve\` (the load-bearing ones; the full reference is in the d
5058
5149
  outstanding ticket, which is the only revocation
5059
5150
  mechanism.
5060
5151
  SUBSTRATE_PUBLIC_ORIGIN This server's origins, comma-separated (e.g.
5061
- https://host:3100,https://alias). A token carrying
5062
- 'aud' must name one; a token with no 'aud' is still
5063
- accepted for now. Required with auth on a non-loopback
5152
+ https://host:3100,https://alias). A token must carry
5153
+ 'aud' naming one; a token with no 'aud' is refused.
5154
+ Required with auth on a non-loopback
5064
5155
  HOST; on loopback it defaults to the loopback origins.
5065
5156
  SUBSTRATE_TLS_KEY_PATH Serve HTTPS. Both are required together — setting one
5066
5157
  SUBSTRATE_TLS_CERT_PATH without the other refuses to boot.
@@ -5102,6 +5193,7 @@ async function runCli(argv) {
5102
5193
  case "normalise-vocab": return await runNormaliseVocab(rest);
5103
5194
  case "backfill-field": return await runBackfillField(rest);
5104
5195
  case "ask": return await runAsk(rest);
5196
+ case "run": return await runRun(rest);
5105
5197
  case "federate": return await runFederate(rest, process.env, (s) => process.stdout.write(s), (s) => process.stderr.write(s));
5106
5198
  default:
5107
5199
  process.stderr.write(`substrate: unknown subcommand '${subcommand}'\n\n`);
package/dist/testing.d.ts CHANGED
@@ -56,8 +56,8 @@ interface AuthConfig {
56
56
  maxTokenLifetimeSeconds?: number;
57
57
  /**
58
58
  * The origins this server answers as (`SUBSTRATE_PUBLIC_ORIGIN`). When set, a
59
- * token carrying `aud` must name one of them; a token with no `aud` is still
60
- * accepted. Absent → `aud` is not checked.
59
+ * token must carry `aud` naming one of them, or it is refused. Absent → `aud`
60
+ * is not checked.
61
61
  */
62
62
  audiences?: ReadonlyArray<string>;
63
63
  /**
package/dist/testing.js CHANGED
@@ -1,7 +1,7 @@
1
1
  import { createRequire as __binCreateRequire } from 'node:module'; const require = __binCreateRequire(import.meta.url);
2
- import { N as MemoryEdgesStore, P as loadPlugins, at as WS_REASON_SERVER_RESTART, c as MemoryDataset, rt as signHs256, s as compose } from "./src-CHp3QyqB.js";
3
- import { a as runDerivedMigrations, o as runMigrations, r as deriveListIndexMigration, t as PgDataset } from "./src-CXKnqeTW.js";
4
- import { t as PgEdgesStore } from "./pg-edges-store-DKPYyd8l.js";
2
+ import { N as MemoryEdgesStore, P as loadPlugins, at as WS_REASON_SERVER_RESTART, c as MemoryDataset, rt as signHs256, s as compose } from "./src-B0BJcyKb.js";
3
+ import { a as runDerivedMigrations, o as runMigrations, r as deriveListIndexMigration, t as PgDataset } from "./src-CBV88iyK.js";
4
+ import { t as PgEdgesStore } from "./pg-edges-store-CKu6M8PU.js";
5
5
  import { t as FakeEmbedder } from "./fake-DUVtKVSE.js";
6
6
  import { randomUUID } from "node:crypto";
7
7
  import postgres from "postgres";
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.7",
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.7",
40
+ "@mnmal-ai/substrate-client": "1.0.0-alpha.7",
41
+ "@mnmal-ai/substrate-compose": "1.0.0-alpha.7",
42
+ "@mnmal-ai/substrate-config": "1.0.0-alpha.7",
43
+ "@mnmal-ai/substrate-core": "1.0.0-alpha.7",
44
+ "@mnmal-ai/substrate-dataset-memory": "1.0.0-alpha.7",
45
+ "@mnmal-ai/substrate-dataset-pg": "1.0.0-alpha.7",
46
+ "@mnmal-ai/substrate-embedder": "1.0.0-alpha.7",
47
+ "@mnmal-ai/substrate-filter": "1.0.0-alpha.7",
48
+ "@mnmal-ai/substrate-pack": "1.0.0-alpha.7",
49
+ "@mnmal-ai/substrate-policy": "1.0.0-alpha.7",
50
+ "@mnmal-ai/substrate-proposals": "1.0.0-alpha.7",
51
+ "@mnmal-ai/substrate-recall": "1.0.0-alpha.7",
52
+ "@mnmal-ai/substrate-sdk": "1.0.0-alpha.7",
53
+ "@mnmal-ai/substrate-sentinel-client": "1.0.0-alpha.7",
54
+ "@mnmal-ai/substrate-server-fastify": "1.0.0-alpha.7",
55
+ "@mnmal-ai/substrate-server-memory": "1.0.0-alpha.7",
56
+ "@mnmal-ai/substrate-types": "1.0.0-alpha.7",
57
57
  "@types/node": "^26.6.4",
58
58
  "@types/semver": "^7.5.0",
59
59
  "@types/ws": "^8.18.1",