@almadar/core 9.6.0 → 9.7.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.
- package/dist/factory/index.d.ts +4 -398
- package/dist/index.d.ts +3 -3
- package/dist/index.js +6 -1
- package/dist/index.js.map +1 -1
- package/dist/types/index.d.ts +214 -8
- package/dist/types/index.js +6 -1
- package/dist/types/index.js.map +1 -1
- package/dist/types-CBb2iBAY.d.ts +454 -0
- package/package.json +1 -1
- package/dist/json-lCu3FWzv.d.ts +0 -57
|
@@ -0,0 +1,454 @@
|
|
|
1
|
+
import { bA as TraitEventListener, F as EntityField, K as EntityPersistence, bF as TraitReference } from './trait-BjSJtFXv.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
package/dist/json-lCu3FWzv.d.ts
DELETED
|
@@ -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 };
|