@mnmal-ai/substrate 0.0.0 → 1.0.0-alpha.1

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.
Files changed (46) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +118 -1
  3. package/dist/agent-token-BIboWOU0.js +200 -0
  4. package/dist/client.d.ts +782 -0
  5. package/dist/client.js +7 -0
  6. package/dist/cluster-worker.js +35 -0
  7. package/dist/content-type-C7T28xNb.js +25 -0
  8. package/dist/dataset-DOXGRz50.js +1535 -0
  9. package/dist/env-utils-B7SGmoeJ.js +21 -0
  10. package/dist/errors-D4vKuwz8.d.ts +130 -0
  11. package/dist/fake-DUVtKVSE.js +36 -0
  12. package/dist/index-D7mSOFlM.d.ts +69 -0
  13. package/dist/pack.d.ts +192 -0
  14. package/dist/pack.js +5 -0
  15. package/dist/plugin-BuQQEzL-.js +3844 -0
  16. package/dist/plugin-t2g2wX0b.d.ts +1568 -0
  17. package/dist/proposals-bootstrap.js +37 -0
  18. package/dist/proposals.config.schema.json +20 -0
  19. package/dist/proposals.d.ts +118 -0
  20. package/dist/proposals.default-config.json +4 -0
  21. package/dist/proposals.js +4 -0
  22. package/dist/recall-bootstrap.js +451 -0
  23. package/dist/recall.config.schema.json +232 -0
  24. package/dist/recall.d.ts +1981 -0
  25. package/dist/recall.default-config.json +4 -0
  26. package/dist/recall.js +5 -0
  27. package/dist/repl-C52wyfMs.js +2213 -0
  28. package/dist/row-ByLFE2Wx.d.ts +719 -0
  29. package/dist/row-DK7lPZVe.js +732 -0
  30. package/dist/runtime-metrics-DwpDJ8vz.d.ts +159 -0
  31. package/dist/schema-g4FQLr0V.d.ts +433 -0
  32. package/dist/sdk.d.ts +694 -0
  33. package/dist/sdk.js +112 -0
  34. package/dist/src-5hVbeiAu.js +1797 -0
  35. package/dist/src-C4DzaIQZ.js +837 -0
  36. package/dist/src-CjEwiKXw.js +2327 -0
  37. package/dist/src-DuopV8u7.js +2408 -0
  38. package/dist/src-YXlv_RyL.js +13524 -0
  39. package/dist/src-zcyUofMJ.js +1015 -0
  40. package/dist/substrate-admin.js +808 -0
  41. package/dist/substrate.js +5482 -0
  42. package/dist/testing.d.ts +1240 -0
  43. package/dist/testing.js +702 -0
  44. package/dist/types-8c0gtnd2.d.ts +35 -0
  45. package/dist/ws-C72iVS5T.d.ts +143 -0
  46. package/package.json +117 -4
@@ -0,0 +1,719 @@
1
+ import { E as Row, s as FieldInput } from "./schema-g4FQLr0V.js";
2
+ import { l as BridgeCredential } from "./runtime-metrics-DwpDJ8vz.js";
3
+ import { J as AutoCrudVerb, Q as PolicyDecision, Z as Policy, et as RequestContext } from "./plugin-t2g2wX0b.js";
4
+ //#region ../../packages/substrate-types/src/nl.d.ts
5
+ /**
6
+ * The engine-dispatchable frame a successful NL translation produces. Keys
7
+ * are qualified (`<ns>/<TypeName>` or `<ns>/<mutationName>`) so the caller can
8
+ * pass it straight to `engine.query({ frame })`.
9
+ */
10
+ type Query = Record<string, {
11
+ params?: Record<string, unknown>;
12
+ fields: FieldInput;
13
+ }>;
14
+ /**
15
+ * In-context exemplar the NL agent embeds in the system prompt. Pairs the raw
16
+ * user prompt with the target Query for few-shot grounding.
17
+ */
18
+ interface NLBase {
19
+ prompt: string;
20
+ query: Query;
21
+ explanation?: string;
22
+ }
23
+ /**
24
+ * The shape returned by `NLQueryAgent.translate`. `rawOutput` is the provider's
25
+ * verbatim text (used for debugging + `_nl` diagnostics on the route response).
26
+ */
27
+ interface NLResult {
28
+ query: Query;
29
+ rawOutput: string;
30
+ explanation?: string;
31
+ }
32
+ /**
33
+ * Optional vocabulary hint block — maps a user-visible term (`"mellow"`) to a
34
+ * concrete field/operator/value triple. The prompt builder renders it, but the
35
+ * `POST /substrate/v1/nl` body does not expose it.
36
+ */
37
+ interface NLVocabularyHint {
38
+ term: string;
39
+ field: string;
40
+ operator: string;
41
+ value: unknown;
42
+ notes?: string;
43
+ }
44
+ //#endregion
45
+ //#region ../../packages/substrate-types/src/nl-wire.d.ts
46
+ interface NlAskRequest {
47
+ namespace: string;
48
+ question: string;
49
+ project?: string;
50
+ /** Force the reading to this type; resubmit a clarify option's `type`. Must name a type of the namespace. */
51
+ type?: string;
52
+ }
53
+ type NlParseStatus = 'resolved' | 'ambiguous' | 'partial' | 'clarify' | 'refuse' | 'unparsed';
54
+ interface NlEvidence {
55
+ span: string;
56
+ role: 'id' | 'type' | 'value' | 'time' | 'order' | 'count' | 'scope' | 'field' | 'author' | 'history';
57
+ detail: string;
58
+ }
59
+ type NlJudgeAction = 'pick' | 'type' | 'bind' | 'recall' | 'clarify' | 'refuse' | 'escalate';
60
+ interface NlJudgeChoice {
61
+ action: NlJudgeAction;
62
+ candidate?: number;
63
+ type?: string;
64
+ word?: string;
65
+ /** `Type.field`. */
66
+ field?: string;
67
+ op?: 'eq' | 'startsWith' | 'contains';
68
+ }
69
+ interface NlJudgeStep {
70
+ parse: {
71
+ status: NlParseStatus;
72
+ reason?: string;
73
+ };
74
+ choice?: NlJudgeChoice;
75
+ /** Why the reply was not applied. */
76
+ rejected?: string;
77
+ }
78
+ /** What an ask answered. The four kinds are exhaustive. */
79
+ type NlOutcome = {
80
+ kind: 'rows';
81
+ frame: Query;
82
+ answer: string;
83
+ /** Absent on the wire when the engine rejected the frame; `errors` then says why. */
84
+ data: unknown;
85
+ errors?: unknown[];
86
+ source: 'parser' | 'judge' | 'handoff';
87
+ handoff?: string;
88
+ } | {
89
+ kind: 'recall';
90
+ query: string;
91
+ /** Absent on the wire when the engine rejected the frame. */
92
+ hits: unknown[] | undefined;
93
+ errors?: unknown[];
94
+ } | {
95
+ kind: 'clarify';
96
+ question: string;
97
+ reason: string;
98
+ options: {
99
+ label: string;
100
+ question: string;
101
+ type: string;
102
+ }[];
103
+ } | {
104
+ kind: 'refuse';
105
+ reason: string;
106
+ };
107
+ interface NlParsedData {
108
+ status: NlParseStatus;
109
+ frame?: Query;
110
+ evidence: NlEvidence[];
111
+ residual: string[];
112
+ reason?: string;
113
+ }
114
+ type NlJudgedStatus = 'resolved' | 'recall' | 'clarify' | 'refuse' | 'escalated';
115
+ /**
116
+ * One SSE event, discriminated by the SSE event name. The terminal answer is
117
+ * named by its outcome kind (`rows` | `recall` | `clarify` | `refuse`) and
118
+ * carries the whole outcome; `done` always follows. An in-band `error` event
119
+ * is not in this union: the client throws on it.
120
+ */
121
+ type NlWireEvent = {
122
+ event: 'parsed';
123
+ data: NlParsedData;
124
+ } | {
125
+ event: 'judging';
126
+ data: {
127
+ reason: string;
128
+ };
129
+ } | {
130
+ event: 'judged';
131
+ data: {
132
+ status: NlJudgedStatus;
133
+ trail: NlJudgeStep[];
134
+ };
135
+ } | {
136
+ event: 'rows';
137
+ data: Extract<NlOutcome, {
138
+ kind: 'rows';
139
+ }>;
140
+ } | {
141
+ event: 'recall';
142
+ data: Extract<NlOutcome, {
143
+ kind: 'recall';
144
+ }>;
145
+ } | {
146
+ event: 'clarify';
147
+ data: Extract<NlOutcome, {
148
+ kind: 'clarify';
149
+ }>;
150
+ } | {
151
+ event: 'refuse';
152
+ data: Extract<NlOutcome, {
153
+ kind: 'refuse';
154
+ }>;
155
+ } | {
156
+ event: 'done';
157
+ data: Record<string, never>;
158
+ };
159
+ /**
160
+ * The JSON encoding's trail spells the terminal event `outcome`, where SSE
161
+ * names it by the outcome kind.
162
+ */
163
+ type NlTrailEvent = ({
164
+ event: 'parsed';
165
+ } & NlParsedData) | {
166
+ event: 'judging';
167
+ reason: string;
168
+ } | {
169
+ event: 'judged';
170
+ status: NlJudgedStatus;
171
+ trail: NlJudgeStep[];
172
+ } | {
173
+ event: 'outcome';
174
+ outcome: NlOutcome;
175
+ } | {
176
+ event: 'done';
177
+ };
178
+ /** The JSON encoding of `POST /substrate/v1/nl`. `outcome` is null only when the run was aborted. */
179
+ interface NlAskResult {
180
+ outcome: NlOutcome | null;
181
+ trail: NlTrailEvent[];
182
+ }
183
+ interface NlPackField {
184
+ name: string;
185
+ /** `metadata` marks a server-managed virtual (createdAt, createdById, ...). */
186
+ kind: 'scalar' | 'crossRef' | 'list' | 'struct' | 'metadata';
187
+ valueType?: string;
188
+ /** crossRef target type. */
189
+ target?: string;
190
+ indexed: boolean;
191
+ operators: string[];
192
+ phrases: string[];
193
+ enum?: string[];
194
+ /** Vocabulary aliases from the schema (alias -> canonical). The server applies them. */
195
+ aliases?: Record<string, string>;
196
+ /** Distinct values in the profile when the field is vocabulary. */
197
+ distinct?: number;
198
+ }
199
+ interface NlPackType {
200
+ name: string;
201
+ /** Lower-case phrases that name the type: singular, plural, head noun. */
202
+ phrases: string[];
203
+ fields: Record<string, NlPackField>;
204
+ }
205
+ interface NlPackValueRef {
206
+ type: string;
207
+ field: string;
208
+ /** The value as stored, original casing. */
209
+ value: string;
210
+ }
211
+ interface NlNamespacePack {
212
+ namespace: string;
213
+ schemaVersion: string;
214
+ types: Record<string, NlPackType>;
215
+ /** Lower-cased value -> every (type, field) it occurs in, sorted. */
216
+ values: Record<string, NlPackValueRef[]>;
217
+ }
218
+ interface NlValueAlias {
219
+ type: string;
220
+ field: string;
221
+ /** Exactly one of these. */
222
+ in?: string[];
223
+ eq?: string;
224
+ startsWith?: string;
225
+ contains?: string;
226
+ }
227
+ interface NlNamespaceRulings {
228
+ /** Types never scoped to the asking project (their `project` means "belongs to", not "applies to"). */
229
+ unscopedTypes?: string[];
230
+ /** Extra phrases naming a type, e.g. `backlog` -> Task. Win over the generated phrases. */
231
+ typeAliases?: Record<string, string>;
232
+ /** Extra phrases naming a field, e.g. `repo` -> project. */
233
+ fieldAliases?: Record<string, string>;
234
+ /**
235
+ * The status value that means "live" for a type, e.g. `Task` -> `open`
236
+ * ("the tasks" are the open ones). A list question about
237
+ * the type defaults to it, and a bare live word ("what's open") picks the
238
+ * types it is the live state of. Types not named here get no default.
239
+ */
240
+ liveStatus?: Record<string, string>;
241
+ /**
242
+ * The date a type is "when" by, where it is not `createdAt`: a Meeting
243
+ * happened at `startedAt`, whenever its row was written. A field named in
244
+ * the question, or a closing/updating verb, still wins.
245
+ */
246
+ timeField?: Record<string, string>;
247
+ /** What a type records, in a phrase. Shown to the judge only; the parser never reads it. */
248
+ typeNotes?: Record<string, string>;
249
+ /** A phrase that means a predicate, e.g. `accepted` -> Decision.status in [active, accepted]. */
250
+ valueAliases?: Record<string, NlValueAlias[]>;
251
+ }
252
+ /** The body of `GET /substrate/v1/nl/pack/:ns`. */
253
+ interface NlServedPack extends NlNamespacePack {
254
+ rulings: NlNamespaceRulings;
255
+ warnings: string[];
256
+ }
257
+ //#endregion
258
+ //#region ../../packages/substrate-policy/src/admin-credential.d.ts
259
+ /** The admin-identity env both `substrate-admin` and substrate-tui read. */
260
+ interface AdminEnv {
261
+ SUBSTRATE_ADMIN_TOKEN?: string;
262
+ SUBSTRATE_ADMIN_KEY_PATH?: string;
263
+ SUBSTRATE_ADMIN_KEY_ID?: string;
264
+ /** The capability that means admin; default `admin`. Read by the diagnosers, not the resolver. */
265
+ SUBSTRATE_ADMIN_CAPABILITY?: string;
266
+ HOME?: string;
267
+ }
268
+ /** Where the admin identity is: a ready bearer, a key to sign with, or why neither. */
269
+ type AdminCredential = {
270
+ readonly kind: 'token';
271
+ readonly authorization: string;
272
+ } | {
273
+ readonly kind: 'key';
274
+ readonly keyPath: string;
275
+ readonly kid: string;
276
+ } | {
277
+ readonly kind: 'error';
278
+ readonly error: string;
279
+ };
280
+ /**
281
+ * Where `bootstrap` writes the admin private key, and where
282
+ * {@link resolveAdminCredential} looks for it.
283
+ */
284
+ declare function resolveDefaultKeyPath(env: AdminEnv): string;
285
+ /** Companion to {@link resolveDefaultKeyPath}, for the kid file. */
286
+ declare function resolveDefaultKidPath(env: AdminEnv): string;
287
+ /**
288
+ * Locate the admin credential, or explain what to set. Signing is the caller's
289
+ * job: it may need a passphrase for the key first.
290
+ *
291
+ * Fail-loud: a message naming the missing key is more use than the 401 an
292
+ * unauthenticated admin call would get.
293
+ */
294
+ declare function resolveAdminCredential(env: AdminEnv): AdminCredential;
295
+ //#endregion
296
+ //#region ../../packages/substrate-policy/src/admin-key.d.ts
297
+ /** The kernel namespace holding Key, Invite and the admin routes' rows. */
298
+ declare const SYSTEM_NAMESPACE = "_system";
299
+ /**
300
+ * Does this row count as an ACTIVE ADMIN key? True when unrevoked, with a kid,
301
+ * and its grant confers `adminCapability` in `_system` (explicit entry, else the
302
+ * wildcard) — the same question `requireCapability` asks at dispatch, through
303
+ * the same parser. Admin scoped to another namespace (e.g. `tasks`) does not
304
+ * count.
305
+ */
306
+ declare function isActiveAdminKeyRow(row: Row, adminCapability: string): boolean;
307
+ /**
308
+ * The grant, one line per namespace, in the SAME syntax `--ns` accepts.
309
+ *
310
+ * `tasks:read+mutate` round-trips: paste a rendered line back into `--ns` and
311
+ * it means what it says here.
312
+ *
313
+ * TOTAL, and it has to be: this runs inside a formatter, after the write has
314
+ * already committed. `parseGrantEntries` throws on a malformed entry, and a
315
+ * throw here would lose the operator the record of an operation that SUCCEEDED.
316
+ * An unparseable grant falls back to naming the raw columns and saying so.
317
+ */
318
+ declare function describeGrant(namespaces: string, capabilities: string): string[];
319
+ //#endregion
320
+ //#region ../../packages/substrate-policy/src/agent-token.d.ts
321
+ /**
322
+ * What a token claims when the caller says nothing. Least privilege: `admin` is
323
+ * opt-in, never a default. Exported so consumers name it rather than copy it.
324
+ */
325
+ declare const DEFAULT_CAPABILITIES: ReadonlyArray<string>;
326
+ /**
327
+ * What an ADMIN caller should claim.
328
+ *
329
+ * The claim is narrowed by the registry row it is checked against
330
+ * (`substrate-compose/src/auth.ts`, via `intersectGrants(claim, row)`), so
331
+ * claiming a superset is safe — the row is the authority and the token only
332
+ * asks. What is NOT safe is claiming a SUBSET: anything the row grants and the
333
+ * claim omits is intersected away. That is the whole defect this constant
334
+ * exists for, so it lists every capability an admin row might carry rather than
335
+ * `admin` alone. A capability the ROW does not grant stays unreachable; no
336
+ * claim fixes that.
337
+ *
338
+ * Deliberately an enumeration, not `['*']`: the capability gates (`withAuth`,
339
+ * `requireCapability`) do a bare membership test with no wildcard case, so a
340
+ * `'*'` claim is refused everything. `substrate-compose`'s
341
+ * `agent-token-capability-intersection` suite pins this list against the
342
+ * `Capability` union.
343
+ */
344
+ declare const ADMIN_CAPABILITIES: ReadonlyArray<string>;
345
+ /**
346
+ * What an admin flow CLAIMS on a deployment: {@link ADMIN_CAPABILITIES} plus
347
+ * `SUBSTRATE_ADMIN_CAPABILITY` when that names something else.
348
+ *
349
+ * A deployment whose admin capability is not `admin` seeds its admin row with
350
+ * that name, so a claim of {@link ADMIN_CAPABILITIES} alone intersects it away
351
+ * and the admin gate answers no. Unset or empty means the default, as every
352
+ * other reader of the variable treats it.
353
+ */
354
+ declare function adminClaimCapabilities(env: {
355
+ SUBSTRATE_ADMIN_CAPABILITY?: string;
356
+ }): ReadonlyArray<string>;
357
+ interface TokenProviderOpts {
358
+ /**
359
+ * Defer reading and parsing the key to the first mint instead of doing it at
360
+ * construction.
361
+ *
362
+ * For callers constructed inside an event handler or a discovery callback,
363
+ * where a throw becomes an unhandled rejection rather than a startup failure
364
+ * a supervisor can see.
365
+ */
366
+ lazyKey?: boolean;
367
+ /**
368
+ * Capabilities to CLAIM. Defaults to `['read', 'mutate']`.
369
+ *
370
+ * A dataset-backed key's registry row narrows this by intersection, so the
371
+ * claim is a request and the row is the authority — a token can never widen
372
+ * itself. The hazard runs the other way: a claim that omits what the row
373
+ * grants intersects it AWAY: an `admin` identity claiming only the default
374
+ * ends up with no capabilities. Pass {@link adminClaimCapabilities} for admin flows.
375
+ */
376
+ capabilities?: ReadonlyArray<string>;
377
+ /** Namespaces to CLAIM. Defaults to `['*']`. Narrowed by the row the same way. */
378
+ namespaces?: ReadonlyArray<string>;
379
+ /**
380
+ * Passphrase for an encrypted PKCS#8 PEM (`substrate-admin bootstrap --encrypt`). Without it an
381
+ * encrypted key cannot be read at all. Held only inside the provider.
382
+ */
383
+ passphrase?: string;
384
+ /** The `aud` claim: the origin the token is minted for. Omitted when unset. */
385
+ audience?: string;
386
+ }
387
+ /**
388
+ * Returns a provider yielding the BARE JWT. Re-signs once the cached token is
389
+ * within {@link REFRESH_SKEW} of expiry.
390
+ *
391
+ * Bare, not `Bearer <jwt>`: the prefix is a transport concern. Callers that
392
+ * want the header value use {@link makeAuthorizationProvider}.
393
+ *
394
+ * Throws at construction on an unreadable or malformed key unless
395
+ * {@link TokenProviderOpts.lazyKey} is set. Signing itself stays lazy either
396
+ * way — only the read moves.
397
+ *
398
+ * Takes only the signing half of a {@link BridgeCredential}: `origin` binds a
399
+ * credential to a destination, which is the caller's gate to enforce before it
400
+ * ever reaches a signer, and the MCP env wrapper has no origin to supply.
401
+ */
402
+ declare function makeTokenProvider(cred: Pick<BridgeCredential, 'keyPath' | 'kid'>, opts?: TokenProviderOpts): () => string;
403
+ /** Is the PEM at `keyPath` an encrypted PKCS#8 key, which needs a passphrase to read? */
404
+ declare function isEncryptedKey(keyPath: string): boolean;
405
+ /**
406
+ * Returns a provider yielding the full `Authorization` header value,
407
+ * `Bearer <jwt>`, over {@link makeTokenProvider}.
408
+ *
409
+ * Keeps the `Bearer ` literal in one place.
410
+ */
411
+ declare function makeAuthorizationProvider(cred: Pick<BridgeCredential, 'keyPath' | 'kid'>, opts?: TokenProviderOpts): () => string;
412
+ //#endregion
413
+ //#region ../../packages/substrate-policy/src/combinators.d.ts
414
+ /**
415
+ * AND combinator. Allow iff every policy allows; short-circuits on first deny.
416
+ * Empty `and()` is the identity element and returns allow (per §4.4).
417
+ */
418
+ declare function and(...policies: Policy[]): Policy;
419
+ /**
420
+ * OR combinator. Allow iff any policy allows; short-circuits on first allow.
421
+ * When all deny, the LAST deny's reason is returned — EXCEPT a caught
422
+ * `'policy error'` from any position always wins over sibling deny reasons
423
+ * (invariant #2).
424
+ */
425
+ declare function or(...policies: Policy[]): Policy;
426
+ /**
427
+ * NOT combinator. Inverts allow/deny, EXCEPT caught errors propagate through
428
+ * unchanged (invariant #2). Preserves the inner decision's `reason` on the
429
+ * returned deny so callers can see it; omits `reason` entirely when the inner
430
+ * allow had no reason (invariant #5).
431
+ */
432
+ declare function not(p: Policy): Policy;
433
+ //#endregion
434
+ //#region ../../packages/substrate-policy/src/encoding.d.ts
435
+ /**
436
+ * Comma-separated string-list encoding. Spec §5.12.
437
+ *
438
+ * The `_system` namespace stores `Key.namespaces`, `Key.capabilities`,
439
+ * `Invite.namespaces`, and `Invite.capabilities` as comma-separated
440
+ * scalar strings rather than list-typed fields. The two helpers below are the
441
+ * only allowed encode/decode path — use sites must NOT hand-roll `.split(',')`
442
+ * because the empty-input → `[]` rule lives here.
443
+ */
444
+ /**
445
+ * Canonicalise a string array for persistence. Trims each entry, rejects
446
+ * embedded commas (no quoting in the substrate column), and joins with `,`.
447
+ * Empty input returns `''` — keeping the column non-null and trivially
448
+ * round-trippable through `decodeList`.
449
+ */
450
+ declare function encodeList(items: Array<string>): string;
451
+ /**
452
+ * Inverse of `encodeList`. Accepts the stored scalar (possibly `''` for an
453
+ * empty list), splits on `,`, trims, drops empties. Non-string inputs — the
454
+ * dataset shouldn't emit these, but defence-in-depth — yield `[]`.
455
+ */
456
+ declare function decodeList(raw: unknown): Array<string>;
457
+ //#endregion
458
+ //#region ../../packages/substrate-policy/src/grant.d.ts
459
+ /**
460
+ * Per-namespace capability grants (spec §5): a namespace → capabilities map.
461
+ *
462
+ * A flat `(namespaces × capabilities)` grant must expand and intersect exactly
463
+ * as the two independent list intersections did, since stored keys are flat;
464
+ * `test/_system/grant.test.ts` asserts that equivalence.
465
+ *
466
+ * Stored in the comma-separated `Key.namespaces` column as entries like
467
+ * `notes:read` or `tasks:read+mutate`. `+` separates capabilities because `,`
468
+ * is taken by the column and `:` by the namespace separator.
469
+ */
470
+ /** A namespace → capabilities map. `'*'` is a legal key: the wildcard grant. */
471
+ type Grant = ReadonlyMap<string, ReadonlySet<string>>;
472
+ /**
473
+ * The capabilities this grant confers in `ns`.
474
+ *
475
+ * An EXPLICIT entry beats the wildcard, which is what makes
476
+ * `--ns '*:read,tasks:read+mutate'` mean the obvious thing — read everywhere,
477
+ * and also write tasks — rather than being ambiguous about which entry wins.
478
+ */
479
+ declare function capabilitiesFor(grant: Grant, ns: string): ReadonlySet<string>;
480
+ /** The flat form, expanded. This is the cross product, stated as a map. */
481
+ declare function expandFlat(namespaces: readonly string[], capabilities: readonly string[]): Grant;
482
+ /**
483
+ * Parses the CLI/route entry list. An entry without `:` takes
484
+ * `defaultCapabilities`, so a bare `--ns notes` keeps its flat meaning.
485
+ *
486
+ * @throws Error naming the entry when one has an empty namespace or no
487
+ * capabilities.
488
+ */
489
+ declare function parseGrantEntries(entries: readonly string[], defaultCapabilities: readonly string[]): Grant;
490
+ /**
491
+ * The reason this entry list will not parse, or `null` when it will.
492
+ *
493
+ * Validates by calling {@link parseGrantEntries} so the rules cannot drift
494
+ * from the parser. The message is the parser's own and carries no fix
495
+ * instruction; each caller appends its own vocabulary.
496
+ */
497
+ declare function grantEntryError(entries: readonly string[], defaultCapabilities: readonly string[]): string | null;
498
+ /**
499
+ * Back to entry form for storage. An entry whose capabilities equal
500
+ * `defaultCapabilities` emits BARE, so a flat grant round-trips to the exact
501
+ * csv it came from and an operator reading `substrate-admin list` sees no new
502
+ * syntax until someone actually uses it.
503
+ */
504
+ declare function encodeGrant(grant: Grant, defaultCapabilities: readonly string[]): string[];
505
+ /**
506
+ * Claim ∩ row, per namespace.
507
+ *
508
+ * A wildcard claim (`ns: ['*']`, what agent tokens send) yields the row's
509
+ * grant, via `capabilitiesFor` resolving `'*'` for every namespace the row
510
+ * names.
511
+ */
512
+ declare function intersectGrants(claim: Grant, row: Grant): Grant;
513
+ /**
514
+ * The flat compatibility view.
515
+ *
516
+ * `namespaces` is every namespace held at ANY level (§8.1) and
517
+ * `capabilities` is the UNION — which is what `withAuth`'s any-namespace
518
+ * pre-check needs. It is deliberately NOT the answer to "what am I granted";
519
+ * `grant` is. Consumers that render this to a human must consult
520
+ * {@link grantIsUniform} first.
521
+ */
522
+ declare function flattenGrant(grant: Grant): {
523
+ namespaces: string[];
524
+ capabilities: string[];
525
+ };
526
+ /**
527
+ * Does every namespace in this grant carry the same capabilities?
528
+ *
529
+ * When false, no single flat capability list is honest, and §8.1 renders
530
+ * `null` rather than picking one.
531
+ */
532
+ declare function grantIsUniform(grant: Grant): boolean;
533
+ //#endregion
534
+ //#region ../../packages/substrate-policy/src/key-guards.d.ts
535
+ /**
536
+ * Shared refusal rules for mutating a `_system/Key`, used by both the
537
+ * `substrate-admin` CLI and the key routes so the lockout guard cannot drift.
538
+ *
539
+ * The READ is deliberately not shared: the CLI reads inside its own
540
+ * `withTransaction`; the route reads through `engine.query` so the registry
541
+ * interceptor fires. Each caller gathers the facts and hands them here.
542
+ *
543
+ * Refusals are RETURNED, not thrown. The CLI maps them to its exit codes and
544
+ * the route maps them to HTTP statuses; a shared thrower would force one
545
+ * caller's error vocabulary onto the other.
546
+ */
547
+ /** Why a key mutation is refused. `null` from a check means "allowed". */
548
+ type KeyMutationRefusal = {
549
+ code: 'unknown_kid';
550
+ message: string;
551
+ } | {
552
+ code: 'already_revoked';
553
+ message: string;
554
+ revokedAt: string;
555
+ } | {
556
+ code: 'last_active_admin';
557
+ message: string;
558
+ };
559
+ /** Normalise a `revokedAt` cell to an ISO string, or null when the key is live. */
560
+ declare function revokedAtIso(value: unknown): string | null;
561
+ /**
562
+ * The revoke verdict.
563
+ *
564
+ * `activeAdminKids` is every kid that {@link isActiveAdminKeyRow} accepts,
565
+ * gathered by the caller. Passing an INCOMPLETE list silently weakens the
566
+ * lockout guard, so callers must read the whole key table, never a page of it.
567
+ */
568
+ declare function checkRevocable(input: {
569
+ kid: string;
570
+ /** The row's `revokedAt`, or `null` when live. Pass `undefined` for "no such row". */
571
+ existingRevokedAt: unknown | undefined;
572
+ exists: boolean;
573
+ activeAdminKids: ReadonlyArray<string>;
574
+ }): KeyMutationRefusal | null;
575
+ /** Does `granted` already cover `item`? A `*` grant covers everything. */
576
+ declare function grantCovers(granted: ReadonlyArray<string>, item: string): boolean;
577
+ /**
578
+ * Entries in `next` that `prev` did not already grant.
579
+ *
580
+ * This — not "is the new set a strict superset" — is the test that matters. A
581
+ * lateral change like `tasks` -> `notes` is neither a superset nor a subset,
582
+ * yet it hands the key an authority it did not hold. Empty result means the
583
+ * change grants nothing new, i.e. it narrows, and narrowing needs no flag.
584
+ */
585
+ declare function newlyGranted(prev: ReadonlyArray<string>, next: ReadonlyArray<string>): Array<string>;
586
+ /**
587
+ * Entries in `next` that `prev` did not already grant, as `(ns, cap)` PAIRS
588
+ * (spec §6). A wildcard entry in `prev` covers any namespace at the
589
+ * capabilities it conferred. A pure narrowing yields the empty set.
590
+ *
591
+ * Returns entries GROUPED BY NAMESPACE in the CLI's own spelling —
592
+ * `recall:read+mutate`, not `recall:read, recall:mutate` — for the operator-
593
+ * facing refusal message.
594
+ */
595
+ declare function newlyGrantedPairs(prev: Readonly<Record<string, ReadonlyArray<string>>>, next: Readonly<Record<string, ReadonlyArray<string>>>): Array<string>;
596
+ /**
597
+ * Does this entry list confer `capability` in any namespace?
598
+ *
599
+ * The shared predicate behind the `--allow-admin` / `allowAdmin` opt-in, so
600
+ * `register` (CLI and route) and `update` cannot answer it differently. Reads
601
+ * the parsed grant, not the flat list, so `--ns '_system:admin' --caps read`
602
+ * still trips it.
603
+ *
604
+ * Returns `true` on an unparseable list: this is a confirmation gate, so the
605
+ * safe failure is asking for confirmation, never handing a privilege over
606
+ * unasked.
607
+ */
608
+ declare function grantEntriesConfer(entries: ReadonlyArray<string>, defaultCapabilities: ReadonlyArray<string>, capability: string): boolean;
609
+ /** Why an in-place key update is refused. `null` means allowed. */
610
+ type KeyUpdateRefusal = KeyMutationRefusal | {
611
+ code: 'last_admin_deadmin';
612
+ message: string;
613
+ } | {
614
+ code: 'requires_widen';
615
+ message: string;
616
+ namespacesGranted: Array<string>;
617
+ capabilitiesGranted: Array<string>;
618
+ } | {
619
+ code: 'requires_allow_admin';
620
+ message: string;
621
+ } | {
622
+ code: 'invalid_grant';
623
+ message: string;
624
+ };
625
+ /**
626
+ * The in-place update verdict. Returns the first refusal, or `null` if allowed.
627
+ *
628
+ * ORDER IS PART OF THE RULE: **unconditional refusals outrank confirmable
629
+ * ones.** One request can trip both the lockout and the widen gate; reporting
630
+ * the confirmable one first sends the operator to add the flag, re-run, and
631
+ * dead-end on the lockout.
632
+ */
633
+ declare function checkUpdatable(input: {
634
+ kid: string;
635
+ exists: boolean;
636
+ existingRevokedAt: unknown | undefined;
637
+ prevNamespaces: ReadonlyArray<string>;
638
+ prevCapabilities: ReadonlyArray<string>;
639
+ nextNamespaces: ReadonlyArray<string>;
640
+ nextCapabilities: ReadonlyArray<string>;
641
+ /** Every kid that {@link isActiveAdminKeyRow} accepts. Must be the WHOLE set. */
642
+ activeAdminKids: ReadonlyArray<string>;
643
+ adminCapability: string;
644
+ widen: boolean;
645
+ allowAdmin: boolean;
646
+ }): KeyUpdateRefusal | null;
647
+ //#endregion
648
+ //#region ../../packages/substrate-policy/src/primitives.d.ts
649
+ /**
650
+ * Always allows. Useful as an explicit identity element for `and(...)` and as a
651
+ * default for resolvers that have no access constraints.
652
+ */
653
+ declare function allowAll(): Policy;
654
+ /**
655
+ * Always denies. Reason defaults to `'denyAll'` when none is supplied so the
656
+ * caller surface always has something to log.
657
+ */
658
+ declare function denyAll(reason?: string): Policy;
659
+ /**
660
+ * Allow when the request has a verified identity attached. The most common
661
+ * minimum bar for authenticated resolvers; composes with role / rate / row
662
+ * policies via `and(...)`.
663
+ */
664
+ declare function requireIdentity(): Policy;
665
+ /**
666
+ * Allow when the identity carries the named capability in its
667
+ * `capabilities: string[]` claim. Admin gates on `purge<T>` and other
668
+ * sensitive mutations compose with this. Per §5.12, the capability name
669
+ * comes from `SUBSTRATE_ADMIN_CAPABILITY` (default `'admin'`).
670
+ *
671
+ * Rejects both when no identity is attached and when identity lacks the
672
+ * capability — callers don't need to stack `requireIdentity()` first.
673
+ */
674
+ declare function requireCapability(name: string): Policy;
675
+ /**
676
+ * Allow when the identity's grant covers `ns` — explicit entry or wildcard.
677
+ * Resolved through `grantOf`, the same function the engine gate uses, so the
678
+ * two cannot disagree.
679
+ *
680
+ * Rejects when no identity is attached or when the grant does not cover `ns`;
681
+ * composes with `requireCapability` via `and` for resolver policies that need
682
+ * both a capability and a namespace grant.
683
+ */
684
+ declare function requireNamespace(ns: string): Policy;
685
+ /**
686
+ * Deny dispatches whose autoCRUD verb is in `verbs`; allow everything else.
687
+ * Keys on `ctx.verb` — the semantic verb the engine threads from
688
+ * the registry entry — so the intent survives entry renames. Entries WITHOUT
689
+ * a verb (type entries, custom mutations) are allowed by this primitive;
690
+ * gate those by `ctx.entry` name or compose additional policies.
691
+ *
692
+ * `purge<T>` is stamped `verb: 'delete'` by autoCRUD, so `denyVerbs(['delete'])`
693
+ * covers both soft- and hard-delete surfaces.
694
+ */
695
+ declare function denyVerbs(verbs: ReadonlyArray<AutoCrudVerb>, reason?: string): Policy;
696
+ /**
697
+ * Allow ONLY dispatches whose autoCRUD verb is in `verbs`.
698
+ * Stricter complement of `denyVerbs`: entries WITHOUT a verb (type entries,
699
+ * custom mutations) are DENIED — an allow-list should not silently pass
700
+ * surfaces it cannot classify. Compose with `or(...)` if reads-via-type-entry
701
+ * must also pass: `or(allowVerbs(['get']), <type-entry policy>)`.
702
+ */
703
+ declare function allowVerbs(verbs: ReadonlyArray<AutoCrudVerb>, reason?: string): Policy;
704
+ //#endregion
705
+ //#region ../../packages/substrate-policy/src/row.d.ts
706
+ /**
707
+ * Build a collection-time allow decision carrying a single row-filter
708
+ * obligation. Composes with `and`/`or` like any other policy.
709
+ */
710
+ declare function row<T>(predicate: (ctx: RequestContext, row: T) => boolean): Policy;
711
+ /**
712
+ * Apply every row-filter obligation on `decision` to `rows`, in insertion
713
+ * order. Per §4.4, row-scoped denies are silent — returning false OR throwing
714
+ * drops the row without surfacing a reason. A decision without obligations
715
+ * returns `rows` unchanged.
716
+ */
717
+ declare function applyRowFilters<T>(decision: PolicyDecision, rows: T[], ctx: RequestContext): T[];
718
+ //#endregion
719
+ export { NlJudgeStep as $, and as A, SYSTEM_NAMESPACE as B, flattenGrant as C, parseGrantEntries as D, intersectGrants as E, TokenProviderOpts as F, resolveAdminCredential as G, isActiveAdminKeyRow as H, adminClaimCapabilities as I, NlAskRequest as J, resolveDefaultKeyPath as K, isEncryptedKey as L, or as M, ADMIN_CAPABILITIES as N, decodeList as O, DEFAULT_CAPABILITIES as P, NlJudgeChoice as Q, makeAuthorizationProvider as R, expandFlat as S, grantIsUniform as T, AdminCredential as U, describeGrant as V, AdminEnv as W, NlEvidence as X, NlAskResult as Y, NlJudgeAction as Z, newlyGrantedPairs as _, denyAll as a, NlPackType as at, capabilitiesFor as b, requireIdentity as c, NlParsedData as ct, KeyUpdateRefusal as d, NlValueAlias as dt, NlJudgedStatus as et, checkRevocable as f, NlWireEvent as ft, newlyGranted as g, Query as gt, grantEntriesConfer as h, NLVocabularyHint as ht, allowVerbs as i, NlPackField as it, not as j, encodeList as k, requireNamespace as l, NlServedPack as lt, grantCovers as m, NLResult as mt, row as n, NlNamespaceRulings as nt, denyVerbs as o, NlPackValueRef as ot, checkUpdatable as p, NLBase as pt, resolveDefaultKidPath as q, allowAll as r, NlOutcome as rt, requireCapability as s, NlParseStatus as st, applyRowFilters as t, NlNamespacePack as tt, KeyMutationRefusal as u, NlTrailEvent as ut, revokedAtIso as v, grantEntryError as w, encodeGrant as x, Grant as y, makeTokenProvider as z };