@almadar/core 9.6.1 → 9.8.0

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.
@@ -0,0 +1,454 @@
1
+ import { d as TraitEventListener, f as EntityField, g as EntityPersistence, j as TraitReference } from './trait-C61Wxi3a.js';
2
+
3
+ /**
4
+ * JSON primitives — the universal "data crossed a boundary" type.
5
+ *
6
+ * Every value that arrives over the wire from an LLM (tool-call args),
7
+ * from disk (workspace files), or from an HTTP body before
8
+ * domain-specific validation is a `JsonValue`. Narrow with a typed
9
+ * predicate (`is`-guard) at the boundary; don't widen back to `unknown`.
10
+ *
11
+ * `JsonObject` and `ToolArgs` are aliases for the common
12
+ * `Record<string, JsonValue>` shape. `ToolArgs` is the name the
13
+ * agent surface uses for LLM-emitted tool-call arguments; `JsonObject`
14
+ * is the general-purpose alias. They are the same type — the alias
15
+ * exists so call sites read at the right semantic level.
16
+ *
17
+ * Why not `Record<string, unknown>`? Two reasons. (1) `unknown` widens
18
+ * back to anything, which defeats the purpose of typing the boundary.
19
+ * (2) The `@almadar/eslint-plugin/no-record-string-unknown` rule blocks
20
+ * the wider form — `JsonValue`-based records are the typed answer.
21
+ *
22
+ * @packageDocumentation
23
+ */
24
+ /**
25
+ * Recursive JSON value union — every shape JSON can carry.
26
+ */
27
+ type JsonValue = string | number | boolean | null | JsonValue[] | {
28
+ [key: string]: JsonValue;
29
+ };
30
+ /**
31
+ * JSON object — keyed string→JsonValue. The wire form of arbitrary
32
+ * structured data. Replaces `Record<string, unknown>` at typed
33
+ * boundaries (LLM emits, file reads, HTTP bodies).
34
+ */
35
+ type JsonObject = {
36
+ [key: string]: JsonValue;
37
+ };
38
+ /**
39
+ * LLM tool-call arguments — same shape as `JsonObject`, named for the
40
+ * agent-surface call site. Each tool's `execute(args: ToolArgs)`
41
+ * receives this and narrows via an `is`-guard predicate before any
42
+ * field access.
43
+ */
44
+ type ToolArgs = JsonObject;
45
+ /**
46
+ * Type guard: is the given value a JSON primitive (non-array,
47
+ * non-object)? Used by walkers that decide whether to recurse.
48
+ */
49
+ declare function isJsonPrimitive(value: JsonValue): value is string | number | boolean | null;
50
+ /**
51
+ * Type guard: is the given value a JSON object (non-array, non-null)?
52
+ */
53
+ declare function isJsonObject(value: JsonValue): value is JsonObject;
54
+ /**
55
+ * Type guard: is the given value a JSON array?
56
+ */
57
+ declare function isJsonArray(value: JsonValue): value is JsonValue[];
58
+
59
+ /**
60
+ * Cross-cutting presentation knobs that don't live per orbital
61
+ * because they're factory-layer concerns (nav items live on a layout
62
+ * trait; theme is a separate `ThemeRef`). The translator reads these
63
+ * and threads them into the matching factory params.
64
+ */
65
+ interface PresentationOverlay {
66
+ /** Nav items to add to the orbital's layout trait. The translator
67
+ * looks for a `signature.traits[i]` with `overridableConfigKeys`
68
+ * including `navItems` and writes into `traitOverrides[name].config.navItems`. */
69
+ navAdditions?: ReadonlyArray<PresentationNavItem>;
70
+ /** Optional theme ref override for the orbital. */
71
+ themeRef?: string;
72
+ }
73
+ interface PresentationNavItem {
74
+ label: string;
75
+ path: string;
76
+ icon?: string;
77
+ }
78
+ /**
79
+ * LLM-authored trait-level overrides keyed by trait name (matches
80
+ * `signature.traits[].name`). Each entry's `config` keys are validated
81
+ * against `signature.traits[i].overridableConfigKeys`.
82
+ */
83
+ type TraitOverlay = Readonly<Record<string, TraitOverlayEntry>>;
84
+ interface TraitOverlayEntry {
85
+ config?: Readonly<Record<string, FactoryParamValue>>;
86
+ linkedEntity?: string;
87
+ events?: Readonly<Record<string, string>>;
88
+ name?: string;
89
+ emitsScope?: 'internal' | 'external';
90
+ listens?: ReadonlyArray<TraitEventListener>;
91
+ }
92
+ type TraitOverlayListener = TraitEventListener;
93
+ /**
94
+ * Rules carry a free-form `capability: string` that the translator
95
+ * matches against `signature.traits[].capabilities` (source-tagged
96
+ * in `.lolo`).
97
+ */
98
+ interface RuleOverlay {
99
+ rules: ReadonlyArray<RuleOverlayEntry>;
100
+ /** Entity-level ownership signal. The translator threads it into
101
+ * the matched trait's `config.ownerField` (when the matched trait
102
+ * advertises that key in `overridableConfigKeys`). */
103
+ ownership?: ReadonlyArray<OwnershipOverlayEntry>;
104
+ }
105
+ interface RuleOverlayEntry {
106
+ id: string;
107
+ /** Free-form capability label, matched against
108
+ * `signature.traits[].capabilities` by exact set membership. */
109
+ capability: string;
110
+ description: string;
111
+ /** Entity names this rule binds to. Empty array = cross-cutting. */
112
+ appliesTo: ReadonlyArray<string>;
113
+ /** Optional role name (e.g. `"admin"`) when the rule is role-scoped. */
114
+ role?: string;
115
+ /** Optional extra config knobs threaded into the matched trait's
116
+ * `config`. Validated against the trait's `overridableConfigKeys`. */
117
+ config?: Readonly<Record<string, FactoryParamValue>>;
118
+ }
119
+ interface OwnershipOverlayEntry {
120
+ /** Entity name (matches the orbital's bound entity name). */
121
+ entity: string;
122
+ /** Field name on the entity that carries the owner identifier. */
123
+ ownerField: string;
124
+ }
125
+
126
+ /**
127
+ * Recursive JSON Schema. Intentionally narrow — only the keywords V2's
128
+ * signature → schema generator emits. Custom `x-*` extensions carry
129
+ * descriptive metadata (synonyms, label) that doesn't shape validation
130
+ * but stays in the schema for prompt rendering / studio UIs.
131
+ */
132
+ interface JsonSchema {
133
+ type?: JsonSchemaType | ReadonlyArray<JsonSchemaType>;
134
+ description?: string;
135
+ properties?: Readonly<{
136
+ [key: string]: JsonSchema;
137
+ }>;
138
+ required?: ReadonlyArray<string>;
139
+ additionalProperties?: boolean | JsonSchema;
140
+ items?: JsonSchema;
141
+ enum?: ReadonlyArray<string | number | boolean>;
142
+ oneOf?: ReadonlyArray<JsonSchema>;
143
+ anyOf?: ReadonlyArray<JsonSchema>;
144
+ default?: JsonValue;
145
+ /**
146
+ * Reference to a shared definition under `$defs` at the schema root.
147
+ * Lets consumers DRY large repeated subschemas (e.g. a 300-entry enum
148
+ * of std-behavior paths reused across every orbital branch of a tool
149
+ * schema). Per JSON Schema 2020-12: absolute reference starting with
150
+ * `#`. Standard OpenAI / DeepSeek strict-mode tool calling resolves
151
+ * `$ref` against `$defs` defined on the tool's parameters root.
152
+ */
153
+ $ref?: string;
154
+ /**
155
+ * Inline subschema definitions referenced from elsewhere via `$ref`.
156
+ * Lives at the schema root so all `$ref` paths can resolve. Values are
157
+ * full `JsonSchema` (can be referenced recursively).
158
+ */
159
+ $defs?: Readonly<{
160
+ [key: string]: JsonSchema;
161
+ }>;
162
+ /** Knob's `@synonyms` from the source `.lolo`. */
163
+ 'x-synonyms'?: string;
164
+ /** Knob's `@label` from the source `.lolo`. */
165
+ 'x-label'?: string;
166
+ /** Knob's `@tier` from the source `.lolo` (`domain`/`presentation`/`internal`). */
167
+ 'x-tier'?: string;
168
+ }
169
+ type JsonSchemaType = 'string' | 'number' | 'integer' | 'boolean' | 'array' | 'object' | 'null';
170
+ /**
171
+ * OrbitalSchema field type tags. The factory-signature extractor lifts
172
+ * these directly from the resolved `.orb`; consumers narrow further at
173
+ * dispatch time.
174
+ */
175
+ type SchemaFieldType = 'string' | 'number' | 'boolean' | 'date' | 'timestamp' | 'datetime' | 'array' | 'object' | 'enum' | 'relation';
176
+ interface FactorySignatureEntityField {
177
+ name: string;
178
+ type: SchemaFieldType;
179
+ required: boolean;
180
+ /** Runtime-managed widget state (`@intrinsic`). A composer must NOT remap an
181
+ * intrinsic slot onto a domain field — it rides along via `extends`. */
182
+ intrinsic?: boolean;
183
+ /** Human/semantic description (`@description "..."`). Slot-side signal for the
184
+ * curation field matcher + catalog search. */
185
+ description?: string;
186
+ /** User-vocabulary synonyms (`@synonyms "..."`). */
187
+ synonyms?: string;
188
+ }
189
+ /**
190
+ * The canonical entity a factory produces. Almost always one entity
191
+ * per orbital; modeled as an array to keep the door open for orbitals
192
+ * that compose multiple entities.
193
+ */
194
+ interface FactoryEntitySignature {
195
+ /** Canonical entity name the factory's params build (e.g. `"ChatMessage"`). */
196
+ name: string;
197
+ /** Fields the factory emits, post-auto-field stripping. */
198
+ fields: ReadonlyArray<FactorySignatureEntityField>;
199
+ /** Persistence mode declared on the canonical entity in the `.orb`. */
200
+ persistence: EntityPersistence;
201
+ }
202
+ /**
203
+ * One overridable config knob a trait advertises. Lifted directly from
204
+ * the source `.lolo` `config { }` block (which carries typed
205
+ * declarations + defaults). Consumers (the questionnaire generator,
206
+ * the studio) pick a widget from `type` and pre-fill from `default`.
207
+ *
208
+ * `label` is reserved for a future `.lolo` grammar extension that
209
+ * lets atom authors author a human-friendly question prompt; today
210
+ * it's always undefined and the questionnaire derives a fallback
211
+ * from the key name.
212
+ */
213
+ interface FactoryConfigParam {
214
+ /** Key name as advertised by the trait. Matches the override path
215
+ * `traitOverrides.<traitName>.config.<key>`. */
216
+ key: string;
217
+ /** Type tag lifted from the `.lolo` config declaration. Drives the
218
+ * question widget selection. Free-form to admit array/object
219
+ * brackets (`[object]`, `[string]`) and atom-defined custom tags. */
220
+ type: string;
221
+ /** Canonical default value the factory uses when no override is
222
+ * supplied. Pre-fills the form widget so users see what they're
223
+ * about to change. */
224
+ default?: FactoryParamValue;
225
+ /** Optional human-friendly question prompt. Lifted from the source
226
+ * `.lolo` `@label "..."` annotation. */
227
+ label?: string;
228
+ /** Optional help-text. Lifted from `.lolo` `@description "..."`. */
229
+ description?: string;
230
+ /** Optional closed-enum value set. Lifted from `.lolo` enum syntax. */
231
+ enumValues?: ReadonlyArray<string>;
232
+ /** Array element schema when the slot's type is `[T]`. Mirrors the
233
+ * `.orb` `ConfigField.items` carrier (`FieldDefinition`-shaped). Lets
234
+ * consumers see the per-element typing — e.g. `metrics : [MetricSpec]`
235
+ * exposes `items.properties` with every MetricSpec field + its own
236
+ * `values: [...]` enum constraints. */
237
+ items?: EntityField;
238
+ /** Object property schemas keyed by property name when the slot's type
239
+ * is an inline `{ ... }` or a named struct alias. Mirrors the `.orb`
240
+ * `ConfigField.properties` carrier. */
241
+ properties?: Readonly<Record<string, EntityField>>;
242
+ /** Comma-separated user-vocabulary synonyms. Authored in `.lolo` as
243
+ * `@synonyms "..."` next to the knob declaration. Used by the agent's
244
+ * catalog-summary prompt (so the LLM connects user phrases to knob
245
+ * names) and by the publish-time knob-embeddings bake (so cosine
246
+ * narrowing recalls knobs voiced via synonym).
247
+ *
248
+ * Example for the `height` knob on `std-graphs`:
249
+ * `@synonyms "taller, shorter, vertical size, pixel height"`
250
+ *
251
+ * Stays a single free-form string; consumers decide their own
252
+ * splitting/formatting policy. */
253
+ synonyms?: string;
254
+ /** Decision-kind tier authored in `.lolo` as `@tier "..."` next to the
255
+ * knob declaration. Drives the studio Questionnaire's filter +
256
+ * disclosure: `internal` knobs are hidden entirely, `presentation`
257
+ * knobs collapse under the "Polish wording" panel, `domain` knobs
258
+ * render inline. Untagged knobs are treated as `presentation` by the
259
+ * studio (safe default — most un-audited knobs are presentation polish). */
260
+ tier?: FactoryConfigTier;
261
+ }
262
+ /**
263
+ * Decision-kind tier for a `FactoryConfigParam`. Source-tagged via the
264
+ * `@tier "..."` annotation in `.lolo` — no heuristic inference on the
265
+ * consumer side. Missing tag = author did not tag = treat as
266
+ * `presentation` at render time.
267
+ *
268
+ * - `domain` — changes how the BUSINESS behaves (currency, retention
269
+ * days, approver roles, SLA hours, lifecycle rules, recipient map,
270
+ * GDPR erasure window). The user MUST own these decisions.
271
+ * - `presentation` — changes how the same business meaning is RENDERED
272
+ * (labels, placeholders, titles, copy, column lists, action lists,
273
+ * layout fidelity like cols/gap/chartType). LLM picks defaults;
274
+ * user can edit post-generation.
275
+ * - `internal` — framework primitives (trait/slot/pattern types,
276
+ * *Event keys, layoutMode); the studio never surfaces these.
277
+ */
278
+ type FactoryConfigTier = 'domain' | 'presentation' | 'internal';
279
+ /**
280
+ * One trait the factory composes into the orbital. The projector reads
281
+ * these to determine which factory's trait stack covers a given
282
+ * orbital + which override knobs a presentation overlay can target.
283
+ */
284
+ interface FactoryTraitSignature {
285
+ /** Canonical trait name post-rename (e.g. `"ChatMessageList"`). */
286
+ name: string;
287
+ /** Upstream trait reference path when this trait is a call-site override
288
+ * of an imported atom — e.g. `"Stats.traits.StatsItemStats"`. Absent
289
+ * when the trait is inline-defined (atom-tier traits). The catalog
290
+ * inheritance pass uses this to resolve the upstream atom signature
291
+ * so each call-site `overridableConfigKeys` entry gets `type` /
292
+ * `items` / `properties` filled in from the canonical declaration. */
293
+ ref?: string;
294
+ /** Event keys this trait emits (post-rename). */
295
+ emittedEvents: ReadonlyArray<string>;
296
+ /** Event keys this trait listens for. */
297
+ listenedEvents: ReadonlyArray<string>;
298
+ /** Structured emit + listen events with their `@description`/`@synonyms`/`@tier`
299
+ * annotations. Parallel to `emittedEvents`/`listenedEvents` (kept as bare-key
300
+ * back-compat); the curation event matcher reads this. */
301
+ events?: ReadonlyArray<FactoryEventSignature>;
302
+ /** Config knobs overridable via `traitOverrides.<name>.config.<key>`.
303
+ * Each entry carries the key name plus the typed declaration lifted
304
+ * from the source `.lolo` `config { }` block. */
305
+ overridableConfigKeys: ReadonlyArray<FactoryConfigParam>;
306
+ /** Capability tags lifted directly from the source `.lolo` trait's
307
+ * header annotations. Free-form strings — the translator overlay
308
+ * matches rules to traits by exact set membership. */
309
+ capabilities: ReadonlyArray<string>;
310
+ /** `true` when the source trait's entity binding was authored
311
+ * `-> @rebindable Entity`. Only then may a consumer rebind it via
312
+ * `traitOverrides.<name>.linkedEntity`; rabit enum-constrains that
313
+ * override to the organism's entities and the validator enforces the
314
+ * field contract. Absent/false = fixed binding. */
315
+ entityRebindable?: boolean;
316
+ /** Inferred field contract a rebind target must satisfy. `requires` =
317
+ * fields the trait reads via `@entity.X`; `provides` = fields it writes.
318
+ * Present only alongside `entityRebindable`. */
319
+ entityContract?: {
320
+ requires: ReadonlyArray<string>;
321
+ provides: ReadonlyArray<string>;
322
+ };
323
+ /** `@description` / `@synonyms` authored on the `@rebindable` binding —
324
+ * fed to catalog prose + knob-embeddings for binding-discovery. */
325
+ entityBindingDescription?: string;
326
+ entityBindingSynonyms?: string;
327
+ }
328
+ /** One event a trait emits or listens for, with its authored annotations — the
329
+ * per-event analogue of `FactorySignatureEntityField` / `FactoryConfigParam`.
330
+ * Feeds the curation event matcher (embedding-wire a composed style atom's
331
+ * actions to a domain lifecycle's events). */
332
+ interface FactoryEventSignature {
333
+ /** Event key (post-rename). */
334
+ name: string;
335
+ /** Whether the trait emits the event or listens for it. */
336
+ direction: 'emit' | 'listen';
337
+ /** Authored `@description` on the emit/listen. */
338
+ description?: string;
339
+ /** Authored `@synonyms` (comma-separated user vocabulary). */
340
+ synonyms?: string;
341
+ /** Authoring `@tier` (`essential`/`customization`/`advanced`/`internal`). */
342
+ tier?: string;
343
+ }
344
+ /** One page the factory emits. The path is the factory default; the
345
+ * projector may override via `params.pagePaths`. */
346
+ interface FactoryPageSignature {
347
+ name: string;
348
+ defaultPath: string;
349
+ primaryEntity: string;
350
+ }
351
+ interface FactorySignature {
352
+ /** Organism the factory belongs to (e.g. `"std-realtime-chat"`). */
353
+ organism: string;
354
+ /** Orbital this factory builds within that organism. */
355
+ orbital: string;
356
+ /** Tier the factory sits in (informational). */
357
+ tier: 'atoms' | 'molecules' | 'organisms';
358
+ /** Path of the generated factory source (relative to the std root). */
359
+ factoryPath: string;
360
+ /** Canonical entity surface(s) the factory produces. */
361
+ entities: ReadonlyArray<FactoryEntitySignature>;
362
+ /** Trait stack the factory composes. */
363
+ traits: ReadonlyArray<FactoryTraitSignature>;
364
+ /** Pages the factory emits. */
365
+ pages: ReadonlyArray<FactoryPageSignature>;
366
+ /** Union of all `traits[].emittedEvents`. */
367
+ emittedEvents: ReadonlyArray<string>;
368
+ /** Union of all `traits[].listenedEvents`. */
369
+ listenedEvents: ReadonlyArray<string>;
370
+ /**
371
+ * JSON Schema for the orbital's `AnalysisOrbitalParams` shape. Walks
372
+ * `traitOverrides.<TraitName>.config.<knob>` with the exact type
373
+ * (string/number/boolean/array/object) lifted from each knob's
374
+ * declaration, `enum` from `enumValues`, recursive `items` for array
375
+ * slots, recursive `properties` for struct slots. Every level carries
376
+ * `additionalProperties: false` so the LLM cannot emit unknown trait
377
+ * names, invented knob keys, or out-of-set enum values.
378
+ *
379
+ * Pre-computed at signature extraction time by
380
+ * `tools/almadar-pattern-sync/src/std-ts/signatures/`. V2 tool-calling
381
+ * (`@almadar-io/agent`'s coordinator + per-orbital subagent) feeds this
382
+ * directly to OpenAI's `tool.parameters` with `strict: true` — the
383
+ * LLM is physically constrained by the schema instead of relying on
384
+ * post-hoc validation.
385
+ *
386
+ * Optional for backward compatibility: signatures emitted by older
387
+ * pattern-sync versions don't carry it, in which case V2 tools fall
388
+ * back to a loose schema + post-hoc validation.
389
+ */
390
+ paramsSchema?: JsonSchema;
391
+ }
392
+ /**
393
+ * Aggregate catalog written to
394
+ * `packages/almadar-std/behaviors/registry/factory-signatures.json`.
395
+ * Sorted by organism then orbital.
396
+ */
397
+ interface FactorySignatureCatalog {
398
+ /** Generated-by version stamp (the `@almadar/std` minor it shipped in). */
399
+ generatedFromStdVersion: string;
400
+ /** Sorted list of factory signatures. */
401
+ signatures: ReadonlyArray<FactorySignature>;
402
+ }
403
+ /**
404
+ * A single factory invocation, as the typed result of the translator.
405
+ * Lower into runtime by calling the factory at `factoryPath` with
406
+ * these `params`. Stable identity for downstream diffing is
407
+ * `(organism, orbital)`.
408
+ */
409
+ interface FactoryCallSite {
410
+ organism: string;
411
+ orbital: string;
412
+ factoryPath: string;
413
+ params: FactoryCallSiteParams;
414
+ }
415
+ /**
416
+ * The typed param surface every factory's call site populates. Each
417
+ * field corresponds to one row in the translator's overlay → factory
418
+ * mapping table.
419
+ */
420
+ interface FactoryCallSiteParams {
421
+ /** Override `signature.entities[0].name` (entity rename). */
422
+ entityName?: string;
423
+ /** Additional or overriding entity fields. Caller wins on collision. */
424
+ entityFields?: ReadonlyArray<EntityField>;
425
+ /** Override `signature.entities[0].persistence`. */
426
+ persistence?: EntityPersistence;
427
+ /** Override the entity's storage collection key. */
428
+ collection?: string;
429
+ /** Per-page path overrides keyed by `signature.pages[i].name`. */
430
+ pagePaths?: Readonly<Record<string, string>>;
431
+ /** Trait-level overrides keyed by `signature.traits[i].name`. Each value
432
+ * is a {@link TraitOverlayEntry} — the canonical override surface that
433
+ * admits the full documented set (`config`, `linkedEntity`, `events`,
434
+ * `name`, `emitsScope`, `listens`) and mirrors what `TraitOverlay` (the
435
+ * LLM-facing input) and {@link MakeTraitRefOpts} (the builder input)
436
+ * both accept. The translator threads each field from the overlay
437
+ * through to here verbatim; the factory applies them via the same
438
+ * `TraitReference` override semantics the inliner uses on hand-authored
439
+ * `.orb` traits. Pre-unification this carried only `{ config? }`, which
440
+ * silently dropped every other override field even though both the
441
+ * overlay layer above and the factory builders below accepted them. */
442
+ traitOverrides?: Readonly<Record<string, TraitOverlayEntry>>;
443
+ /** Extra traits to compose into the orbital that aren't part of the
444
+ * canonical signature trait stack. */
445
+ extraTraits?: ReadonlyArray<TraitReference>;
446
+ }
447
+ /**
448
+ * Allowed leaf values for the typed factory-param surface.
449
+ */
450
+ type FactoryParamValue = string | number | boolean | ReadonlyArray<FactoryParamValue> | {
451
+ readonly [key: string]: FactoryParamValue;
452
+ };
453
+
454
+ export { type FactoryCallSite as F, type JsonObject as J, type OwnershipOverlayEntry as O, type PresentationNavItem as P, type RuleOverlay as R, type SchemaFieldType as S, type ToolArgs as T, type FactoryCallSiteParams as a, type FactoryConfigParam as b, type FactoryConfigTier as c, type FactoryEntitySignature as d, type FactoryEventSignature as e, type FactoryPageSignature as f, type FactoryParamValue as g, type FactorySignature as h, type FactorySignatureCatalog as i, type FactorySignatureEntityField as j, type FactoryTraitSignature as k, type JsonSchema as l, type JsonSchemaType as m, type JsonValue as n, type PresentationOverlay as o, type RuleOverlayEntry as p, type TraitOverlay as q, type TraitOverlayEntry as r, type TraitOverlayListener as s, isJsonArray as t, isJsonObject as u, isJsonPrimitive as v };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@almadar/core",
3
- "version": "9.6.1",
3
+ "version": "9.8.0",
4
4
  "description": "Core schema types and definitions for Almadar",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -1,57 +0,0 @@
1
- /**
2
- * JSON primitives — the universal "data crossed a boundary" type.
3
- *
4
- * Every value that arrives over the wire from an LLM (tool-call args),
5
- * from disk (workspace files), or from an HTTP body before
6
- * domain-specific validation is a `JsonValue`. Narrow with a typed
7
- * predicate (`is`-guard) at the boundary; don't widen back to `unknown`.
8
- *
9
- * `JsonObject` and `ToolArgs` are aliases for the common
10
- * `Record<string, JsonValue>` shape. `ToolArgs` is the name the
11
- * agent surface uses for LLM-emitted tool-call arguments; `JsonObject`
12
- * is the general-purpose alias. They are the same type — the alias
13
- * exists so call sites read at the right semantic level.
14
- *
15
- * Why not `Record<string, unknown>`? Two reasons. (1) `unknown` widens
16
- * back to anything, which defeats the purpose of typing the boundary.
17
- * (2) The `@almadar/eslint-plugin/no-record-string-unknown` rule blocks
18
- * the wider form — `JsonValue`-based records are the typed answer.
19
- *
20
- * @packageDocumentation
21
- */
22
- /**
23
- * Recursive JSON value union — every shape JSON can carry.
24
- */
25
- type JsonValue = string | number | boolean | null | JsonValue[] | {
26
- [key: string]: JsonValue;
27
- };
28
- /**
29
- * JSON object — keyed string→JsonValue. The wire form of arbitrary
30
- * structured data. Replaces `Record<string, unknown>` at typed
31
- * boundaries (LLM emits, file reads, HTTP bodies).
32
- */
33
- type JsonObject = {
34
- [key: string]: JsonValue;
35
- };
36
- /**
37
- * LLM tool-call arguments — same shape as `JsonObject`, named for the
38
- * agent-surface call site. Each tool's `execute(args: ToolArgs)`
39
- * receives this and narrows via an `is`-guard predicate before any
40
- * field access.
41
- */
42
- type ToolArgs = JsonObject;
43
- /**
44
- * Type guard: is the given value a JSON primitive (non-array,
45
- * non-object)? Used by walkers that decide whether to recurse.
46
- */
47
- declare function isJsonPrimitive(value: JsonValue): value is string | number | boolean | null;
48
- /**
49
- * Type guard: is the given value a JSON object (non-array, non-null)?
50
- */
51
- declare function isJsonObject(value: JsonValue): value is JsonObject;
52
- /**
53
- * Type guard: is the given value a JSON array?
54
- */
55
- declare function isJsonArray(value: JsonValue): value is JsonValue[];
56
-
57
- export { type JsonObject as J, type ToolArgs as T, type JsonValue as a, isJsonObject as b, isJsonPrimitive as c, isJsonArray as i };