@holoscript/core 8.0.8 → 8.0.9

package/dist/parameter-envelope/ParameterEnvelope.d.ts

@@ -0,0 +1,128 @@
+/**
+ * ParameterEnvelope — first-class valid-parameter domain for simulation receipts.
+ *
+ * ## Purpose (H1 roadmap §ParameterEnvelope)
+ *
+ * A simulation run proves an instance. A *parameter envelope* names the SPACE
+ * the instance lives in. Within-envelope remixes inherit the proof automatically;
+ * out-of-envelope remixes either re-discharge (re-run the proof for the new
+ * params) or emit an honest error rather than silently inheriting a stale receipt.
+ *
+ * This closes the "prove the space, not the instance" gap identified in the
+ * simulation-as-proof north star.
+ *
+ * ## Design constraints
+ *
+ * - DOMAIN-NEUTRAL. No domain nouns (no "Young's modulus", "dose", "temperature").
+ *   Physical units go via DimensionalTypeSystem; envelope records carry an
+ *   optional `unit` string for human display only.
+ * - NEVER hardcodes domain vocabulary. Retires `UNIT_RANGES` hardcodes in plugins.
+ * - Records are DATA (JSON-serializable). The envelope itself is carried into the
+ *   DomainSimulationReceipt as `parameterEnvelope` so it is part of the proof.
+ *
+ * ## `onViolation` semantics
+ *
+ *   'warn'        — record the violation but keep `passed: true`; the run can
+ *                   proceed but the receipt notes the out-of-envelope param.
+ *   'error'       — record the violation and set `passed: false`; callers should
+ *                   refuse to run or mark the receipt as invalid.
+ *   'redischarge' — special: the run is OUT of the envelope but a RE-RUN with the
+ *                   new params is required to inherit the proof. The receipt
+ *                   carries `redischarge: true`; callers must trigger re-proof.
+ *
+ * Default `onViolation` when absent from a record is `'error'`.
+ */
+/** Action to take when a parameter is outside its declared envelope. */
+export type EnvelopeViolationAction = 'warn' | 'error' | 'redischarge';
+/**
+ * A single parameter's valid domain declaration.
+ *
+ * Exactly one of the following must be provided:
+ *   - `min` / `max` — for numeric ranges (either or both may be present)
+ *   - `allowed`     — for discrete allowed values (any primitive type)
+ *
+ * If neither is provided the record is a no-op (the param is always in-envelope).
+ * `param` is the name of the config key this record guards.
+ */
+export interface ParameterEnvelopeRecord {
+    /** Config key this record guards. Used as the display name in violations. */
+    param: string;
+    /**
+     * Inclusive lower bound (numeric params only).
+     * Absent → no lower bound.
+     */
+    min?: number;
+    /**
+     * Inclusive upper bound (numeric params only).
+     * Absent → no upper bound.
+     */
+    max?: number;
+    /**
+     * Explicit set of allowed values (any primitive).
+     * When provided together with min/max, a value must satisfy BOTH the
+     * range constraint AND appear in this set.
+     */
+    allowed?: ReadonlyArray<string | number | boolean | null>;
+    /**
+     * Human-readable unit label for this parameter (e.g. "m/s", "kg").
+     * Pure display; not machine-validated by this module.
+     */
+    unit?: string;
+    /**
+     * Action when the param value is outside this envelope.
+     * Default: `'error'`.
+     */
+    onViolation?: EnvelopeViolationAction;
+}
+/** A recorded violation from `checkParameterEnvelope`. */
+export interface EnvelopeViolation {
+    /** The parameter name (= `record.param`). */
+    param: string;
+    /** The actual value that was checked. */
+    value: unknown;
+    /** The record that declared the envelope. */
+    record: ParameterEnvelopeRecord;
+    /** The action triggered by this violation. */
+    verdict: EnvelopeViolationAction;
+    /** Human-readable description of the violation. */
+    message: string;
+}
+/** Result of `checkParameterEnvelope`. */
+export interface EnvelopeCheckResult {
+    /**
+     * `true` when there are no `'error'`-verdict violations (warn and
+     * redischarge violations are present in `violations` but do not
+     * set `passed: false`).
+     */
+    passed: boolean;
+    /**
+     * `true` when ANY violation has verdict `'redischarge'`.
+     * Callers must re-run the proof before the receipt can be inherited.
+     */
+    redischarge: boolean;
+    /** All recorded violations, regardless of verdict. */
+    violations: EnvelopeViolation[];
+}
+/** An array of envelope records forming a complete parameter envelope. */
+export type ParameterEnvelope = ParameterEnvelopeRecord[];
+/**
+ * Check whether a single numeric or discrete value falls within a record's envelope.
+ *
+ * Returns `true` when the value satisfies all constraints declared in `record`.
+ * A record with no constraints (no min, no max, no allowed) always returns `true`.
+ */
+export declare function isInEnvelope(value: unknown, record: ParameterEnvelopeRecord): boolean;
+/**
+ * Check a flat params map against a ParameterEnvelope.
+ *
+ * For each record in `envelope`:
+ *   1. If the param key is absent from `params`, the record is skipped (no
+ *      violation — the absence itself may be intentional, checked elsewhere).
+ *   2. Otherwise, `isInEnvelope(params[record.param], record)` is called.
+ *      On failure, a violation is recorded with the declared `onViolation` action.
+ *
+ * @param params  Flat key→value map of the run's config parameters.
+ * @param envelope  Array of `ParameterEnvelopeRecord` declarations.
+ * @returns `EnvelopeCheckResult` with `passed`, `redischarge`, and `violations`.
+ */
+export declare function checkParameterEnvelope(params: Record<string, unknown>, envelope: ParameterEnvelope): EnvelopeCheckResult;

package/dist/parameter-envelope/index.cjs

@@ -0,0 +1,17 @@
+'use strict';
+
+var chunk6ZCCLKS2_cjs = require('../chunk-6ZCCLKS2.cjs');
+require('../chunk-ZHPMP447.cjs');
+
+
+
+Object.defineProperty(exports, "checkParameterEnvelope", {
+  enumerable: true,
+  get: function () { return chunk6ZCCLKS2_cjs.checkParameterEnvelope; }
+});
+Object.defineProperty(exports, "isInEnvelope", {
+  enumerable: true,
+  get: function () { return chunk6ZCCLKS2_cjs.isInEnvelope; }
+});
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/parameter-envelope/index.d.ts

@@ -0,0 +1,2 @@
+export { isInEnvelope, checkParameterEnvelope, } from './ParameterEnvelope';
+export type { EnvelopeViolationAction, ParameterEnvelopeRecord, EnvelopeViolation, EnvelopeCheckResult, ParameterEnvelope, } from './ParameterEnvelope';

package/dist/parameter-envelope/index.js

@@ -0,0 +1,4 @@
+export { checkParameterEnvelope, isInEnvelope } from '../chunk-HIDEIEFG.js';
+import '../chunk-W4GABFCR.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map