@holoscript/core 8.0.8 → 8.0.9

package/dist/parser/PipelineParser.d.ts

@@ -0,0 +1,162 @@
+/**
+ * HoloScript Pipeline Parser
+ *
+ * Parses .hs pipeline definitions into a structured AST.
+ * Pipelines describe declarative data flows: source → transform → filter → sink.
+ *
+ * Compilation targets: Node.js, Python, Lambda, Cloudflare Worker, Docker, K8s CronJob.
+ *
+ * @module PipelineParser
+ */
+export interface PipelineDuration {
+    value: number;
+    unit: 's' | 'm' | 'h' | 'd';
+}
+export interface PipelineRetry {
+    max: number;
+    backoff: 'none' | 'linear' | 'exponential';
+}
+export interface PipelineAuth {
+    type: 'bearer' | 'oauth2' | 'api_key' | 'basic';
+    token?: string;
+    key?: string;
+    header?: string;
+}
+export interface PipelinePagination {
+    type: 'cursor' | 'offset';
+    param: string;
+    limit: number;
+}
+export interface PipelineBatch {
+    size: number;
+    parallel?: number;
+}
+export interface PipelineOnError {
+    action: 'log' | 'retry' | 'dead_letter';
+    continue: boolean;
+}
+export interface PipelineSource {
+    kind: 'source';
+    name: string;
+    type: 'rest' | 'webhook' | 'stream' | 'filesystem' | 'database' | 'mcp' | 'list' | 'stdout' | 'user_input';
+    endpoint?: string;
+    path?: string;
+    pattern?: string;
+    since?: string;
+    method?: string;
+    auth?: PipelineAuth;
+    pagination?: PipelinePagination;
+    items?: Record<string, unknown>[];
+    properties: Record<string, unknown>;
+}
+export interface FieldMapping {
+    from: string;
+    to: string;
+    transforms: string[];
+}
+export interface PipelineTransform {
+    kind: 'transform';
+    name: string;
+    type?: 'llm' | 'mcp' | 'http' | 'field_mapping';
+    mappings?: FieldMapping[];
+    model?: string;
+    prompt?: string;
+    input?: string;
+    output?: string | Record<string, unknown>;
+    server?: string;
+    tool?: string;
+    args?: Record<string, unknown>;
+    method?: string;
+    url?: string;
+    timeout?: PipelineDuration;
+    where?: string;
+    properties: Record<string, unknown>;
+}
+export interface PipelineFilter {
+    kind: 'filter';
+    name: string;
+    where: string;
+}
+export interface PipelineValidateField {
+    field: string;
+    rules: string[];
+}
+export interface PipelineValidate {
+    kind: 'validate';
+    name: string;
+    fields: PipelineValidateField[];
+}
+export interface PipelineMerge {
+    kind: 'merge';
+    name: string;
+    from: string[];
+    dedup?: {
+        key: string;
+        window: string;
+    };
+    strategy?: 'concat' | 'zip' | 'latest';
+}
+export interface BranchRoute {
+    condition: string | 'default';
+    sinkName: string;
+}
+export interface PipelineBranch {
+    kind: 'branch';
+    name: string;
+    routes: BranchRoute[];
+}
+export interface PipelineSink {
+    kind: 'sink';
+    name: string;
+    type: 'rest' | 'webhook' | 'mcp' | 'filesystem' | 'database' | 'stdout' | 'holo';
+    endpoint?: string;
+    path?: string;
+    method?: string;
+    auth?: PipelineAuth;
+    body?: Record<string, unknown>;
+    batch?: PipelineBatch;
+    onError?: PipelineOnError;
+    format?: 'json' | 'jsonl' | 'csv';
+    append?: boolean;
+    server?: string;
+    tool?: string;
+    args?: Record<string, unknown>;
+    then?: PipelineSink;
+    template?: string;
+    hash?: string;
+    properties: Record<string, unknown>;
+}
+export type PipelineStep = PipelineSource | PipelineTransform | PipelineFilter | PipelineValidate | PipelineMerge | PipelineBranch | PipelineSink;
+export interface Pipeline {
+    name: string;
+    schedule?: string;
+    timeout?: PipelineDuration;
+    retry?: PipelineRetry;
+    params?: Record<string, string>;
+    steps: PipelineStep[];
+    sources: PipelineSource[];
+    transforms: PipelineTransform[];
+    filters: PipelineFilter[];
+    validates: PipelineValidate[];
+    merges: PipelineMerge[];
+    branches: PipelineBranch[];
+    sinks: PipelineSink[];
+}
+export interface PipelineParseResult {
+    success: boolean;
+    pipeline?: Pipeline;
+    errors: PipelineParseError[];
+}
+export interface PipelineParseError {
+    message: string;
+    line?: number;
+    block?: string;
+}
+/**
+ * Parse a .hs pipeline source string into a structured Pipeline AST.
+ */
+export declare function parsePipeline(source: string): PipelineParseResult;
+/**
+ * Check if source content contains a pipeline definition.
+ */
+export declare function isPipelineSource(source: string): boolean;

package/dist/parser.cjs

@@ -1,61 +1,77 @@
 'use strict';
 
-var chunk4YNYPHH3_cjs = require('./chunk-4YNYPHH3.cjs');
+var chunkNFFHLX37_cjs = require('./chunk-NFFHLX37.cjs');
+var chunkX75H75UY_cjs = require('./chunk-X75H75UY.cjs');
 require('./chunk-3VBO3IYQ.cjs');
-var chunkKOUAQL2B_cjs = require('./chunk-KOUAQL2B.cjs');
-require('./chunk-6PRZIHGL.cjs');
-require('./chunk-3SKLAUDD.cjs');
-require('./chunk-X3GJPRVK.cjs');
-require('./chunk-DTGBOSEM.cjs');
-require('./chunk-YKGPCZEE.cjs');
-require('./chunk-6EX3I5P4.cjs');
-require('./chunk-HCCQLAA4.cjs');
+var chunkCANAL6CT_cjs = require('./chunk-CANAL6CT.cjs');
+require('./chunk-OV6HHKLE.cjs');
+require('./chunk-YP5CHEYU.cjs');
+require('./chunk-OMNHTCS4.cjs');
+require('./chunk-EI3J6LTW.cjs');
+require('./chunk-36NPLOI4.cjs');
+require('./chunk-AWXFEAQL.cjs');
+require('./chunk-4FIBOJW6.cjs');
+require('./chunk-N74QRJGP.cjs');
+require('./chunk-NTQRFOPP.cjs');
+require('./chunk-ZHPMP447.cjs');
 
 
 
+Object.defineProperty(exports, "GrammarModuleRegistry", {
+  enumerable: true,
+  get: function () { return chunkNFFHLX37_cjs.GrammarModuleRegistry; }
+});
+Object.defineProperty(exports, "TypeScriptHsplusGrammar", {
+  enumerable: true,
+  get: function () { return chunkNFFHLX37_cjs.TypeScriptHsplusGrammar; }
+});
+Object.defineProperty(exports, "normalizeHsplusGrammarErrors", {
+  enumerable: true,
+  get: function () { return chunkNFFHLX37_cjs.normalizeHsplusGrammarErrors; }
+});
 Object.defineProperty(exports, "HoloCompositionParser", {
   enumerable: true,
-  get: function () { return chunk4YNYPHH3_cjs.HoloCompositionParser; }
+  get: function () { return chunkX75H75UY_cjs.HoloCompositionParser; }
 });
 Object.defineProperty(exports, "parseHolo", {
   enumerable: true,
-  get: function () { return chunk4YNYPHH3_cjs.parseHolo; }
+  get: function () { return chunkX75H75UY_cjs.parseHolo; }
 });
 Object.defineProperty(exports, "parseHoloPartial", {
   enumerable: true,
-  get: function () { return chunk4YNYPHH3_cjs.parseHoloPartial; }
+  get: function () { return chunkX75H75UY_cjs.parseHoloPartial; }
 });
 Object.defineProperty(exports, "parseHoloStrict", {
   enumerable: true,
-  get: function () { return chunk4YNYPHH3_cjs.parseHoloStrict; }
+  get: function () { return chunkX75H75UY_cjs.parseHoloStrict; }
 });
 Object.defineProperty(exports, "ChunkBasedIncrementalParser", {
   enumerable: true,
-  get: function () { return chunkKOUAQL2B_cjs.ChunkBasedIncrementalParser; }
+  get: function () { return chunkCANAL6CT_cjs.ChunkBasedIncrementalParser; }
 });
 Object.defineProperty(exports, "HoloScriptPlusParser", {
   enumerable: true,
-  get: function () { return chunkKOUAQL2B_cjs.HoloScriptPlusParser; }
+  get: function () { return chunkCANAL6CT_cjs.HoloScriptPlusParser; }
 });
 Object.defineProperty(exports, "ParseCache", {
   enumerable: true,
-  get: function () { return chunkKOUAQL2B_cjs.ParseCache; }
+  get: function () { return chunkCANAL6CT_cjs.ParseCache; }
 });
 Object.defineProperty(exports, "createParser", {
   enumerable: true,
-  get: function () { return chunkKOUAQL2B_cjs.createParser; }
+  get: function () { return chunkCANAL6CT_cjs.createParser; }
 });
 Object.defineProperty(exports, "globalParseCache", {
   enumerable: true,
-  get: function () { return chunkKOUAQL2B_cjs.globalParseCache; }
+  get: function () { return chunkCANAL6CT_cjs.globalParseCache; }
 });
 Object.defineProperty(exports, "parse", {
   enumerable: true,
-  get: function () { return chunkKOUAQL2B_cjs.parse; }
+  get: function () { return chunkCANAL6CT_cjs.parse; }
 });
 Object.defineProperty(exports, "parseIncrementalChunks", {
   enumerable: true,
-  get: function () { return chunkKOUAQL2B_cjs.parseIncrementalChunks; }
+  get: function () { return chunkCANAL6CT_cjs.parseIncrementalChunks; }
 });
 //# sourceMappingURL=parser.cjs.map
 //# sourceMappingURL=parser.cjs.map

package/dist/parser.js

@@ -1,12 +1,16 @@
-export { HoloCompositionParser, parseHolo, parseHoloPartial, parseHoloStrict } from './chunk-OABEO6HH.js';
+export { GrammarModuleRegistry, TypeScriptHsplusGrammar, normalizeHsplusGrammarErrors } from './chunk-SE7ANBGN.js';
+export { HoloCompositionParser, parseHolo, parseHoloPartial, parseHoloStrict } from './chunk-SZOLTWWD.js';
 import './chunk-SYTRBGDS.js';
-export { ChunkBasedIncrementalParser, HoloScriptPlusParser, ParseCache, createParser, globalParseCache, parse, parseIncrementalChunks } from './chunk-FNHJRI32.js';
-import './chunk-VSACG2AR.js';
-import './chunk-GASCWJK5.js';
-import './chunk-WRNEH5MO.js';
-import './chunk-WKX5AMOY.js';
-import './chunk-SIEXCILW.js';
-import './chunk-CBJY23VL.js';
-import './chunk-OL46QLBJ.js';
+export { ChunkBasedIncrementalParser, HoloScriptPlusParser, ParseCache, createParser, globalParseCache, parse, parseIncrementalChunks } from './chunk-DBH3D2MU.js';
+import './chunk-Z6LZUYZF.js';
+import './chunk-UNMVGZVW.js';
+import './chunk-JBYBMBMW.js';
+import './chunk-2EGGAZT3.js';
+import './chunk-YW3I2FQL.js';
+import './chunk-7I74JWPW.js';
+import './chunk-2I3XAGMF.js';
+import './chunk-MD4IVS42.js';
+import './chunk-63AUAIL6.js';
+import './chunk-W4GABFCR.js';
 //# sourceMappingURL=parser.js.map
 //# sourceMappingURL=parser.js.map

package/dist/plugin-manifest/ManifestAutoLoader.d.ts

@@ -0,0 +1,35 @@
+/**
+ * ManifestAutoLoader — scan a plugins directory and auto-register every
+ * plugin whose `plugin.manifest.json` declares `autoRegister: true`.
+ *
+ * Resolution order for the register function inside `runtimeEntry`:
+ *   1. `module.registerTraitHandlers` — canonical name (preferred).
+ *   2. First export matching `/^register\w+TraitHandlers$/` — backward-
+ *      compat with older plugins that use a domain-specific name (e.g.
+ *      `registerRoboticsTraitHandlers`).
+ *
+ * This is intentionally a runtime utility (Node.js `fs` + dynamic `import`)
+ * and must NOT be bundled into browser builds. Tree-shake it out or use a
+ * server-side entry that imports from `@holoscript/core/plugin-manifest/auto-loader`.
+ */
+import type { TraitRegistrarTarget } from '../runtime/plugin-trait-registrar';
+export interface AutoLoadResult {
+    /** Plugin ids successfully registered. */
+    loaded: string[];
+    /** Plugin ids with `autoRegister: false` — intentionally skipped. */
+    skipped: string[];
+    /** Plugins that encountered an error during load or registration. */
+    failed: Array<{
+        id: string;
+        error: string;
+    }>;
+}
+/**
+ * Scan `pluginsDir` for subdirectories containing `plugin.manifest.json` and
+ * auto-register all plugins whose manifest has `autoRegister: true`.
+ *
+ * @param pluginsDir  Absolute path to the plugins root (e.g. `packages/plugins`).
+ * @param registrar   Runtime registrar to call each plugin's register function with.
+ * @returns           Summary of what was loaded, skipped, and failed.
+ */
+export declare function autoLoadPluginsFromManifests(pluginsDir: string, registrar: TraitRegistrarTarget): Promise<AutoLoadResult>;

package/dist/plugin-manifest/PluginManifest.d.ts

@@ -0,0 +1,156 @@
+/**
+ * PluginManifest — declarative plugin descriptor (H1 proof machinery).
+ *
+ * Every plugin declares a `plugin.manifest.json` at its package root that
+ * conforms to this schema. The runtime reads manifests to:
+ *   1. Auto-register trait handlers (when `autoRegister: true`) so no
+ *      hand-written `registerXxxTraitHandlers` call is needed in user code.
+ *   2. Introspect plugins from LSP / marketplace / Brittney without importing
+ *      plugin TypeScript — the manifest is machine-readable data, not code.
+ *   3. Gate `StdlibPolicy` capability scoping at the declared plugin boundary.
+ *   4. Provide the anchor point for `PluginSolverContract` in H2.
+ *
+ * ## Design constraints
+ *
+ * - DOMAIN-NEUTRAL. No domain nouns. Traits are registered by name strings;
+ *   the manifest carries no domain-specific vocabulary.
+ * - JSON-serializable. All fields are primitives or arrays of primitives.
+ * - Additive. Optional fields may be absent; the runtime ignores unknown fields
+ *   so manifests can carry H2 fields (`solverContract`, `receiptSchema`) before
+ *   the engine is ready to consume them.
+ *
+ * ## Combination support
+ *
+ * `combinePluginRegistrations` (this module) accepts an array of
+ * `PluginRegistration` objects — each pairing a manifest with a set of
+ * `TraitRegistrarTarget` calls — and registers all traits into a single
+ * registrar. This is the proto-composition primitive: it gives the caller
+ * a flat list of plugin IDs that can be fed into a future `ComposedReceipt`
+ * (H2 ProofCompositionLaw) without changing the calling convention.
+ */
+/**
+ * A single trait entry in the manifest's `traits` array.
+ * Carries the trait name plus optional human-readable metadata.
+ */
+export interface PluginTraitEntry {
+    /** Trait name as registered in the runtime (e.g. `"eoq"`, `"menu"`). */
+    name: string;
+    /** Optional short description for tooling/LSP display. */
+    description?: string;
+    /** SI unit of the primary output field (if numeric). Pure display; not validated here. */
+    outputUnit?: string;
+}
+/**
+ * Declarative plugin manifest (`plugin.manifest.json`).
+ *
+ * Required fields: `id`, `version`, `traits`.
+ * All other fields are optional additive metadata.
+ */
+export interface PluginManifest {
+    /**
+     * Stable plugin identifier. Used by the runtime collision guard
+     * (`__pluginOwner`) and as the anchor for `PluginSolverContract` in H2.
+     * Convention: kebab-case, no `@holoscript/` prefix (e.g. `"retail-ecommerce"`).
+     */
+    id: string;
+    /** Semver version string. */
+    version: string;
+    /**
+     * Array of traits this plugin registers. The runtime uses this list to
+     * validate that every declared trait has a corresponding handler when
+     * `autoRegister: true`.
+     */
+    traits: Array<string | PluginTraitEntry>;
+    /**
+     * Human-readable display name (e.g. `"Retail / E-commerce"`).
+     * Used by marketplace and LSP hover.
+     */
+    name?: string;
+    /** Short description of what this plugin provides. */
+    description?: string;
+    /**
+     * When `true`, the runtime automatically calls the plugin's default
+     * registration export (`registerTraitHandlers`) at scene init without
+     * the user explicitly calling it. Default: `false`.
+     *
+     * This is the activation path that converts dead-wired plugins into
+     * live-wired ones via manifest-only config — no code change at the
+     * call site.
+     */
+    autoRegister?: boolean;
+    /**
+     * Minimum `@holoscript/core` semver required.
+     * Used by the loader to refuse incompatible plugins cleanly.
+     */
+    coreVersion?: string;
+    /**
+     * Entry-point path (relative to package root) for the runtime registration
+     * module. Defaults to `"./src/runtime.ts"` (or `"./dist/runtime.js"` post-build).
+     * The auto-register loader resolves this path to invoke the registration export.
+     */
+    runtimeEntry?: string;
+    /**
+     * Optional H2 placeholder: reference to a `PluginSolverContract` declaration.
+     * Absent until H2 ships; the loader ignores unknown fields, so manifests can
+     * carry this early for tooling forward-compat.
+     */
+    solverContract?: string;
+    /**
+     * Optional H2 placeholder: identifier for a registered receipt schema.
+     * When present, the runtime validates solver output against this schema
+     * before issuing a receipt. Absent → freeform resultSummary (today's behavior).
+     */
+    receiptSchema?: string;
+}
+/** Extract the plain trait name from a manifest trait entry. */
+export declare function traitName(entry: string | PluginTraitEntry): string;
+/** Return all trait names declared in a manifest. */
+export declare function manifestTraitNames(manifest: PluginManifest): string[];
+/**
+ * A single plugin's runtime registration bundle.
+ * Pair a `PluginManifest` with a `register` function that calls
+ * `registerPluginTraits(target, …)` for this plugin's handlers.
+ *
+ * ## Usage
+ * ```ts
+ * const result = combinePluginRegistrations(registrar, [
+ *   { manifest: aerospaceManifest, register: registerAerospaceTraitHandlers },
+ *   { manifest: medicalManifest,   register: registerMedicalTraitHandlers   },
+ * ]);
+ * // result.pluginIds → ['aerospace', 'medical']
+ * // result.traitNames → ['delta_v', 'orbit', 'diagnosis', 'treatment', …]
+ * ```
+ */
+export interface PluginRegistration<TRegistrar = unknown> {
+    manifest: PluginManifest;
+    /** Call `registerPluginTraits(registrar, …)` inside this function. */
+    register: (registrar: TRegistrar) => void;
+}
+/** Summary returned by `combinePluginRegistrations`. */
+export interface CombinedPluginResult {
+    /** Ordered list of plugin IDs that were registered. */
+    pluginIds: string[];
+    /** Flat union of all trait names declared across all plugins. */
+    traitNames: string[];
+}
+/**
+ * Register multiple plugins into a single trait registrar.
+ *
+ * This is the proto-composition primitive — the bridge between today's
+ * independent plugin receipts and H2's `ComposedReceipt`. Call it at scene
+ * init instead of calling each plugin's `register*TraitHandlers` individually.
+ *
+ * The caller supplies a `registrar` (any object with `registerTrait(name, handler)`),
+ * and for each `PluginRegistration`, this function calls `registration.register(registrar)`.
+ * After all registrations complete, the returned `CombinedPluginResult` carries
+ * the flat union of IDs and trait names for use in receipt construction.
+ *
+ * Trait name collision (two plugins declaring the same name) is not checked
+ * here — the underlying `registerPluginTraits` stamps `__pluginOwner` on each
+ * handler, so the runtime's collision guard handles it at dispatch time.
+ *
+ * @param registrar  The runtime registrar to register all traits into.
+ * @param plugins    Array of plugin registration bundles.
+ * @returns          `{ pluginIds, traitNames }` — the union across all plugins.
+ */
+export declare function combinePluginRegistrations<TRegistrar>(registrar: TRegistrar, plugins: ReadonlyArray<PluginRegistration<TRegistrar>>): CombinedPluginResult;

package/dist/plugin-manifest/index.cjs

@@ -0,0 +1,25 @@
+'use strict';
+
+var chunkSR73L5ZP_cjs = require('../chunk-SR73L5ZP.cjs');
+require('../chunk-ZHPMP447.cjs');
+
+
+
+Object.defineProperty(exports, "autoLoadPluginsFromManifests", {
+  enumerable: true,
+  get: function () { return chunkSR73L5ZP_cjs.autoLoadPluginsFromManifests; }
+});
+Object.defineProperty(exports, "combinePluginRegistrations", {
+  enumerable: true,
+  get: function () { return chunkSR73L5ZP_cjs.combinePluginRegistrations; }
+});
+Object.defineProperty(exports, "manifestTraitNames", {
+  enumerable: true,
+  get: function () { return chunkSR73L5ZP_cjs.manifestTraitNames; }
+});
+Object.defineProperty(exports, "traitName", {
+  enumerable: true,
+  get: function () { return chunkSR73L5ZP_cjs.traitName; }
+});
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/plugin-manifest/index.d.ts

@@ -0,0 +1,2 @@
+export * from './PluginManifest';
+export * from './ManifestAutoLoader';

package/dist/plugin-manifest/index.js

@@ -0,0 +1,4 @@
+export { autoLoadPluginsFromManifests, combinePluginRegistrations, manifestTraitNames, traitName } from '../chunk-RKGUZBOC.js';
+import '../chunk-W4GABFCR.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map