@zodal/dials-core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,457 @@
+import { z } from 'zod';
+import { CollectionConfig, CollectionDefinition } from '@zodal/core';
+
+/**
+ * Core model types for zodal-dials: settings, layers, scopes, the cascade result, and provenance.
+ *
+ * A SETTING is a typed named parameter identified by a stable dotted-path KEY. A LAYER is a partial
+ * map of key -> value (or the UNSET sentinel) from one source. A SCOPE names an ordered source of
+ * layers; the CASCADE merges an ordered stack of scoped layers into an EFFECTIVE value per key,
+ * paired with PROVENANCE (which scope won, what it shadowed, whether it is policy-managed).
+ *
+ * UNSET is the explicit deletion/reset sentinel — never raw `null` — so a layer can declare "I do
+ * not contribute this key" (re-exposing a lower scope) without colliding with a legitimate `null`
+ * value. See `docs/zodal-dials-concept.md` and `docs/dev-plan.md` §4.
+ */
+/** A setting's stable, serialization-independent identity (a dotted path, e.g. "editor.fontSize"). */
+type SettingKey = string;
+/** A setting value: a scalar, an array, or an irreducible nested object. */
+type SettingValue = unknown;
+/**
+ * The deletion/reset sentinel. In a layer, `UNSET` marks a key as explicitly not contributed by
+ * that scope, re-exposing the value from a lower-precedence scope (or its absence). Distinct from
+ * `null`/`undefined`, which are legitimate setting values. Uses a registered symbol so it survives
+ * realm boundaries and bundler duplication.
+ */
+declare const UNSET: unique symbol;
+type Unset = typeof UNSET;
+/** Type guard for the UNSET sentinel. */
+declare function isUnset(v: unknown): v is Unset;
+/** A partial/sparse set of setting values from one source — the unit that gets merged. */
+type Layer = Record<SettingKey, SettingValue | Unset>;
+/**
+ * A named layer in the cascade. Scopes are DATA, not constants: the resolver is handed an ordered
+ * stack (lowest precedence first) and never hardcodes the ladder. `managed: true` elevates a layer
+ * into the policy band — it wins over every non-managed layer regardless of position and marks the
+ * resulting value as non-overridable (the UI should lock the control).
+ */
+interface ScopedLayer {
+    /** The scope id this layer comes from (e.g. "default", "preset", "profile", "user", "policy"). */
+    scope: string;
+    /** The (sparse) layer of values. */
+    layer: Layer;
+    /** Policy/managed band: wins over all non-managed layers and marks the value non-overridable. */
+    managed?: boolean;
+}
+/** Per-key merge strategy. Type-directed by default; `.meta({ mergeStrategy })`-overridable. */
+type MergeStrategy = 'replace' | 'deep-merge' | 'append';
+/** A lower layer that set a key but did not win (or that explicitly UNSET it). */
+interface ShadowedLayer {
+    scope: string;
+    /** The shadowed value, or 'UNSET' if that layer reset the key. */
+    value: SettingValue | 'UNSET';
+    managed: boolean;
+}
+/**
+ * The cascade's first-class explanation of an effective value: which scope won, how the value was
+ * produced, what it shadowed, whether it is policy-managed, and (for deep-merged objects) which
+ * scopes contributed. This is the deliberate differentiator — provenance is never a debug
+ * afterthought.
+ */
+interface KeyProvenance {
+    key: SettingKey;
+    /** The scope id that supplied the effective value. */
+    winningScope: string;
+    /** The resolved value (also present in `effective`). */
+    value: SettingValue;
+    /** True when the winning scope is in the managed/policy band (control should be locked). */
+    managed: boolean;
+    /** How the value was produced from the contributing layers. */
+    mergeStrategy: MergeStrategy;
+    /** Other layers that set this key, highest precedence first (each value or 'UNSET'). */
+    shadowed: ShadowedLayer[];
+    /** For deep-merged object values: the scope ids whose objects were merged, low -> high. */
+    mergedFrom?: string[];
+}
+/** A key set to differing values by more than one layer (surfaced for the UI). */
+interface Conflict {
+    key: SettingKey;
+    /** Contributing scopes (highest precedence first) with their values. */
+    contributors: Array<{
+        scope: string;
+        value: SettingValue | 'UNSET';
+        managed: boolean;
+    }>;
+    /** True when a managed/policy scope overrode a differing non-managed value. */
+    overriddenByPolicy: boolean;
+}
+/** The complete result of resolving a cascade. */
+interface EffectiveResult {
+    /** The resolved value per key (keys that resolve to UNSET/absent are omitted). */
+    effective: Record<SettingKey, SettingValue>;
+    /** Provenance per resolved key. */
+    provenance: Record<SettingKey, KeyProvenance>;
+    /** Keys set by multiple layers to differing values (informational). */
+    conflicts: Conflict[];
+}
+/** Sensitivity classification of a setting. */
+type Sensitivity = 'public' | 'sensitive' | 'secret';
+/**
+ * A masked reference to a secret value — mirrors zodal's `ContentRef`. Reads of a secret setting
+ * return a `SecretRef`, never plaintext; the plaintext is fetched via an explicit reveal call.
+ */
+interface SecretRef {
+    readonly _tag: 'SecretRef';
+    /** The setting key this secret belongs to. */
+    key: SettingKey;
+    /** Whether a value is set (without revealing it). */
+    isSet: boolean;
+    /** A display mask, e.g. "•••• (set)" or "not set". */
+    masked: string;
+}
+/** Type guard for SecretRef. */
+declare function isSecretRef(v: unknown): v is SecretRef;
+
+/**
+ * The cascade resolver: merge an ordered stack of scoped layers (lowest precedence first) into an
+ * effective value per key, paired with provenance.
+ *
+ * Precedence is the stack order, with managed/policy layers elevated into a top band that wins over
+ * every non-managed layer regardless of position (and marks the value non-overridable). The UNSET
+ * sentinel is a fall-through: a layer that UNSETs a key ABSTAINS (contributes nothing for it),
+ * re-exposing the next lower scope — at the top of a stack this is exactly "reset to default". Under
+ * `deep-merge`/`append`, an abstaining (UNSET) layer simply does not participate in the merge; it
+ * does NOT sever the contributors below it — to override a lower object wholesale, use the `replace`
+ * strategy or set the full value. Provenance reports the winning scope, the shadowed layers
+ * (including higher resets), the merge strategy used, and — for merges — only the scopes that
+ * actually changed the result (`mergedFrom`, computed by leave-one-out, so fully-shadowed scopes are
+ * not falsely claimed).
+ */
+
+interface ResolveOptions {
+    /** Per-key merge strategy resolver. Default: 'replace' for every key. */
+    strategyFor?: (key: SettingKey) => MergeStrategy;
+}
+/** Resolve a stack of scoped layers (lowest precedence first) into effective values + provenance. */
+declare function resolve(stack: ScopedLayer[], options?: ResolveOptions): EffectiveResult;
+
+/**
+ * Value combination under a merge strategy. Given an ordered (low -> high precedence) list of
+ * contributing values for one key, produce the merged value: `replace` (highest wins), `deep-merge`
+ * (structural merge of object contributors), or `append` (concatenate array contributors). Pure.
+ */
+
+/** Combine an ordered (low -> high precedence) list of contributing values under a strategy. */
+declare function mergeValues(values: SettingValue[], strategy: MergeStrategy): SettingValue;
+
+/**
+ * Patch & serialization utilities for layers.
+ *
+ * - RFC 7386 JSON Merge Patch (`applyMergePatch`) — the ergonomic, mirror-shaped delta format.
+ * - Lossless layer serialization (`serializeLayer`/`deserializeLayer`) — encodes the UNSET sentinel
+ *   separately from values so a layer round-trips with zero drift (UNSET is NOT conflated with a
+ *   literal `null`, the standard RFC 7386 footgun).
+ * - `layerToMergePatch` — a layer AS a standard RFC 7386 patch (UNSET -> null) for interop (lossy
+ *   only for the rare literal-`null` value).
+ * - RFC 6902 JSON Patch (`applyJsonPatch`) + `diffJsonPatch` + `invertJsonPatch` — for history/undo.
+ *
+ * All functions are pure; inputs are never mutated. Pointer traversal rejects the prototype-polluting
+ * keys `__proto__`/`constructor`/`prototype`, and array indices are validated per RFC 6902 §4.
+ */
+
+/** Apply an RFC 7386 JSON Merge Patch to a target. `null` in the patch deletes a member. Pure. */
+declare function applyMergePatch(target: unknown, patch: unknown): unknown;
+/** The on-disk/wire shape of a layer: values plus an explicit list of reset (UNSET) keys. */
+interface SerializedLayer {
+    values: Record<string, unknown>;
+    unset: string[];
+}
+/** Serialize a layer losslessly (UNSET keys recorded separately from values). */
+declare function serializeLayer(layer: Layer): SerializedLayer;
+/** Deserialize a layer produced by `serializeLayer` (the inverse; round-trips with zero drift). */
+declare function deserializeLayer(s: SerializedLayer): Layer;
+/**
+ * Express a layer as a standard RFC 7386 merge patch (UNSET -> null). Lossy ONLY for the rare case
+ * of a setting whose legitimate value is `null` (indistinguishable from a reset under RFC 7386); use
+ * `serializeLayer` when that distinction must be preserved.
+ */
+declare function layerToMergePatch(layer: Layer): Record<string, unknown>;
+/** An RFC 6902 JSON Patch operation. */
+type JsonPatchOp = {
+    op: 'add';
+    path: string;
+    value: unknown;
+} | {
+    op: 'remove';
+    path: string;
+} | {
+    op: 'replace';
+    path: string;
+    value: unknown;
+} | {
+    op: 'move';
+    from: string;
+    path: string;
+} | {
+    op: 'copy';
+    from: string;
+    path: string;
+} | {
+    op: 'test';
+    path: string;
+    value: unknown;
+};
+/** Apply an ordered RFC 6902 JSON Patch to a document. Pure; throws on a failed `test` or bad path. */
+declare function applyJsonPatch(doc: unknown, ops: JsonPatchOp[]): unknown;
+/**
+ * Compute an RFC 6902 patch turning `before` into `after`, at object-member granularity (recursing
+ * into nested plain objects; arrays and scalars are replaced wholesale). The patches we generate are
+ * always add/remove/replace, which `invertJsonPatch` inverts exactly — ideal for settings history.
+ */
+declare function diffJsonPatch(before: unknown, after: unknown, basePath?: string): JsonPatchOp[];
+/**
+ * Produce the inverse of a patch (relative to the document it was applied to), so applying the
+ * inverse undoes it. Exact for add/remove/replace/test/copy; `move` is inverted as a reverse move.
+ */
+declare function invertJsonPatch(ops: JsonPatchOp[], before: unknown): JsonPatchOp[];
+
+/**
+ * Zod v4 introspection helpers for settings schemas: reading the object shape, per-field `.meta()`
+ * (unwrapping wrappers so wrapped metadata survives), extracting declared defaults (robustly, by
+ * parsing `undefined` — no reliance on private internals), the type-directed merge strategy, and the
+ * sensitivity classification (name heuristics + `.meta()` override). Uses `@zodal/core` helpers
+ * where they apply and stable `instanceof` checks for base typing.
+ */
+
+/** Get the field map of a Zod object schema. Prefers `_zod.def.shape` (the workspace Zod-v4 rule),
+ *  falling back to the public `.shape`. */
+declare function getObjectShape(schema: z.ZodObject<z.ZodRawShape>): Record<string, z.ZodType>;
+/** Read a field's `.meta()` metadata, unwrapping wrappers so metadata on the inner schema is found. */
+declare function readMeta(schema: z.ZodType): Record<string, unknown>;
+/** The stable base type of a field (after unwrapping optional/default/nullable). */
+declare function baseType(field: z.ZodType): string;
+/** Extract the per-key default values declared in the schema (the lowest cascade layer). */
+declare function extractDefaults(schema: z.ZodObject<z.ZodRawShape>): Record<string, unknown>;
+/** The type-directed default merge strategy for a field, overridable via `.meta({ mergeStrategy })`. */
+declare function keyMergeStrategy(field: z.ZodType): MergeStrategy;
+/**
+ * Classify a setting's sensitivity: `.meta()` override first, then field-name heuristics, then — for
+ * a container-valued setting (object/array/record/tuple/union) — a fail-safe recursion: if any
+ * nested field is secret, the WHOLE setting is classified `secret`, so masking/redaction protects
+ * the nested value (an irreducible nested value cannot be masked field-by-field). `field` is optional
+ * so out-of-schema (ad-hoc) layer keys are still name-classified rather than defaulting to `public`.
+ */
+declare function classifySensitivity(key: string, field?: z.ZodType): Sensitivity;
+
+/**
+ * Secret handling — the model-side of zodal's content/metadata bifurcation applied to settings.
+ *
+ * A setting classified `secret` (by name heuristic or `.meta({ secret: true })`) must never appear
+ * in the queryable config store, an exported layer/patch, or an audit log as plaintext. These pure
+ * helpers enforce that: `splitBySensitivity` routes secret values out of the config layer to a
+ * secret backend; `redactSecretsFromLayer` strips them from anything serialized for export/audit;
+ * `maskSecrets` replaces secret effective values with a masked `SecretRef`. The concrete secret
+ * backend (OS keychain / Vault / encrypted store) is a satellite store package; here we define the
+ * seam and the guarantees.
+ */
+
+/** Build a masked reference to a secret value (never carries the plaintext). */
+declare function makeSecretRef(key: SettingKey, isSet: boolean): SecretRef;
+/**
+ * Replace the effective values of secret settings with a masked `SecretRef`. Pure. The plaintext is
+ * never copied into the output — reveal is an explicit, separate operation against the secret backend.
+ */
+declare function maskSecrets(effective: Record<SettingKey, SettingValue>, sensitivityFor: (key: SettingKey) => Sensitivity): Record<SettingKey, SettingValue>;
+/**
+ * Mask EVERY surface of a resolved result that could carry a secret as plaintext: `effective`,
+ * `provenance[key].value`, every `provenance[key].shadowed[].value`, and `conflicts[].contributors[].value`.
+ * This is the function `defineDials.resolve({ maskSecrets: true })` and `explain()` go through — so
+ * the audit/provenance path can never leak. Pure.
+ */
+declare function maskEffectiveResult(result: EffectiveResult, sensitivityFor: (key: SettingKey) => Sensitivity): EffectiveResult;
+/**
+ * Partition a layer into the config values (safe to persist/query) and the secret values (to route
+ * to a secret backend). Secret keys never appear in `config`. Pure.
+ */
+declare function splitBySensitivity(layer: Layer, sensitivityFor: (key: SettingKey) => Sensitivity): {
+    config: Layer;
+    secrets: Layer;
+};
+/** Strip secret keys from a serialized layer before export/audit (they must never be written). */
+declare function redactSecretsFromLayer(serialized: SerializedLayer, sensitivityFor: (key: SettingKey) => Sensitivity): SerializedLayer;
+/**
+ * The contract a secret backend implements (OS keychain, Vault, encrypted store). Mirrors zodal's
+ * bifurcation "content provider". Reads return a masked ref; the plaintext is fetched only via an
+ * explicit `reveal`. Implemented by satellite `@zodal/dials-store-*` packages.
+ */
+interface SecretBackend {
+    has(key: SettingKey): Promise<boolean>;
+    get(key: SettingKey): Promise<SecretRef>;
+    /** Explicit, audited plaintext reveal — separate from ordinary reads. */
+    reveal(key: SettingKey): Promise<string | undefined>;
+    set(key: SettingKey, value: string): Promise<SecretRef>;
+    delete(key: SettingKey): Promise<void>;
+    /** The keys this backend holds (so a bifurcation provider can surface masked refs on load). */
+    list(): Promise<SettingKey[]>;
+}
+
+/**
+ * Linked validation — one model of relations over setting keys, evaluated to VALIDATE. Hard
+ * constraints are authored in Zod (`.refine`/`.superRefine`, validated over the effective values)
+ * and/or as a serializable `{ message, keys, check }` list (the NixOS `assertions`/`warnings` shape,
+ * a mirror that could be exported to a CSP/SAT solver). Soft `warnings` are advisory and never fail.
+ * Evaluation is fail-fast: it returns all errors so the UI can show them at resolve time.
+ */
+
+/** A serializable hard constraint: a predicate over the effective values plus a message + the keys it concerns. */
+interface Assertion {
+    id?: string;
+    message: string;
+    /** The keys this constraint relates (for highlighting + solver export). */
+    keys?: SettingKey[];
+    /** The predicate: returns true when satisfied. A throw counts as unsatisfied. */
+    check: (values: Record<string, unknown>) => boolean;
+}
+/** A soft warning: advisory guidance shown when `when` holds. Never fails validation. */
+interface Warning {
+    message: string;
+    keys?: SettingKey[];
+    when: (values: Record<string, unknown>) => boolean;
+}
+interface ConstraintsConfig {
+    /** A Zod schema validated against the effective values (cross-field via `.superRefine`). */
+    schema?: z.ZodType;
+    /** Declarative hard constraints (serializable mirror; solver-exportable). */
+    assertions?: Assertion[];
+    /** Soft, advisory warnings. */
+    warnings?: Warning[];
+}
+interface ConstraintError {
+    message: string;
+    keys: SettingKey[];
+}
+interface ConstraintResult {
+    ok: boolean;
+    errors: ConstraintError[];
+    warnings: string[];
+}
+/** Evaluate constraints + warnings over a resolved values map. Pure; collects all errors. */
+declare function evaluateConstraints(values: Record<string, unknown>, config?: ConstraintsConfig): ConstraintResult;
+
+/**
+ * Dependent (smart) defaults — the SUGGEST mode of the same field-relation model that constraints
+ * use to VALIDATE. A dependent default computes an advisory value for one key from the current
+ * values of others ("C is usually near f(A,B), but any C is valid"). It honors OVERRIDE-STICKINESS:
+ * once the user has set the target key (it is dirty), its dependent default is never recomputed, so
+ * a user's choice is never silently clobbered. Pure.
+ */
+
+interface DependentDefault {
+    /** The key this default applies to. */
+    key: SettingKey;
+    /** Keys this default depends on (documented; drives recompute scheduling in reactive consumers). */
+    dependsOn: SettingKey[];
+    /** Compute the suggested value from the current values. Return `undefined` to suggest nothing. */
+    derive: (values: Record<string, unknown>) => unknown;
+}
+interface DeriveOptions {
+    /** Keys the user has explicitly set (dirty) — their dependent defaults are NOT recomputed. */
+    dirtyKeys?: Iterable<SettingKey>;
+}
+interface DeriveResult {
+    values: Record<string, unknown>;
+    /** Keys whose dependent default was applied this pass. */
+    applied: SettingKey[];
+}
+/**
+ * Fill dependent defaults into a values map, returning a new map. A dirty target key is never
+ * overwritten (stickiness). Defaults are applied in declaration order, each seeing the results of
+ * earlier ones.
+ */
+declare function applyDependentDefaults(values: Record<string, unknown>, defaults: DependentDefault[], options?: DeriveOptions): DeriveResult;
+
+/**
+ * `defineDials` — the entry point. A settings document is modeled as a degenerate one-item zodal
+ * collection, so the Zod schema is the single source of truth and zodal's `defineCollection` supplies
+ * per-field affordances (for the UI layer). On top of that this binds the cascade engine: declared
+ * defaults become the lowest scope, the type-directed merge strategy and sensitivity classification
+ * are precomputed per key, and `resolve`/`explain`/`validate`/`withDependentDefaults` operate over an
+ * ordered stack of scoped layers.
+ */
+
+interface DefineDialsConfig<TSchema extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>> {
+    /** Hard/soft constraints evaluated over the effective values. */
+    constraints?: ConstraintsConfig;
+    /** Dependent (smart) defaults. */
+    dependentDefaults?: DependentDefault[];
+    /** Passed through to `defineCollection` (escape hatch for affordance config). */
+    collection?: CollectionConfig<z.infer<TSchema>>;
+}
+interface DialsResolveOptions {
+    /** Prepend the schema defaults as the lowest scope. Default: true. */
+    includeDefaults?: boolean;
+    /** Replace secret effective values with a masked `SecretRef`. Default: false. */
+    maskSecrets?: boolean;
+}
+interface DialsCapabilities {
+    keyCount: number;
+    hasSecrets: boolean;
+    hasConstraints: boolean;
+    hasDependentDefaults: boolean;
+    mergeStrategies: Record<string, MergeStrategy>;
+}
+interface DialsDefinition<TSchema extends z.ZodObject<z.ZodRawShape>> {
+    schema: TSchema;
+    /** The underlying zodal collection (affordance source for the UI). `undefined` if the schema is
+     *  not a shape `defineCollection` accepts — the cascade does not depend on it. */
+    collection: CollectionDefinition<TSchema> | undefined;
+    /** The declared defaults (the lowest cascade layer). */
+    defaults: Record<string, unknown>;
+    keys: SettingKey[];
+    mergeStrategyFor(key: SettingKey): MergeStrategy;
+    sensitivityFor(key: SettingKey): Sensitivity;
+    /** Resolve an ordered stack of scoped layers (lowest precedence first). */
+    resolve(stack: ScopedLayer[], options?: DialsResolveOptions): EffectiveResult;
+    /** Explain how one key resolved (its provenance), or undefined if no scope set it. */
+    explain(key: SettingKey, stack: ScopedLayer[], options?: DialsResolveOptions): KeyProvenance | undefined;
+    /** Evaluate constraints over a resolved values map. */
+    validate(values: Record<string, unknown>): ConstraintResult;
+    /** Fill dependent defaults into a values map, honoring dirty stickiness. */
+    withDependentDefaults(values: Record<string, unknown>, dirtyKeys?: SettingKey[]): Record<string, unknown>;
+    getCapabilities(): DialsCapabilities;
+}
+/** Define a settings surface from a Zod object schema. */
+declare function defineDials<TSchema extends z.ZodObject<z.ZodRawShape>>(schema: TSchema, config?: DefineDialsConfig<TSchema>): DialsDefinition<TSchema>;
+
+/**
+ * The `LayerStore` contract — how a scope sources (and optionally persists) its layer. The cascade
+ * resolves an ordered stack of `{ scope, layer }`; a `LayerStore` is what produces one scope's layer
+ * from a backing source (env vars, a JSONC/TOML/YAML file, a remote store, a secret backend, …).
+ * Concrete adapters live in satellite `@zodal/dials-store-*` packages; this is just the interface +
+ * an honest capability report. Pure types — no runtime/Node dependency.
+ */
+
+/** What a store can do, reported honestly (mirrors the spirit of zodal `ProviderCapabilities`). */
+interface LayerStoreCapabilities {
+    /** Can produce a layer via `load()`. */
+    readable: boolean;
+    /** Can persist a layer via `save()`. */
+    writable: boolean;
+    /** Can notify on external change via `subscribe()`. */
+    watchable: boolean;
+}
+/** A source/sink for a single scope's layer. */
+interface LayerStore {
+    /** The scope id this store provides a layer for (e.g. 'env', 'user', 'workspace'). */
+    readonly scope: string;
+    /** Honest capability report. */
+    getCapabilities(): LayerStoreCapabilities;
+    /** Load the current layer from the backing source. */
+    load(): Promise<Layer>;
+    /** Persist a layer to the backing source (present only when `writable`). */
+    save?(layer: Layer): Promise<void>;
+    /** Subscribe to external changes (present only when `watchable`); returns an unsubscribe function. */
+    subscribe?(onChange: (layer: Layer) => void): () => void;
+}
+
+export { type Assertion, type Conflict, type ConstraintError, type ConstraintResult, type ConstraintsConfig, type DefineDialsConfig, type DependentDefault, type DeriveOptions, type DeriveResult, type DialsCapabilities, type DialsDefinition, type DialsResolveOptions, type EffectiveResult, type JsonPatchOp, type KeyProvenance, type Layer, type LayerStore, type LayerStoreCapabilities, type MergeStrategy, type ResolveOptions, type ScopedLayer, type SecretBackend, type SecretRef, type Sensitivity, type SerializedLayer, type SettingKey, type SettingValue, type ShadowedLayer, UNSET, type Unset, type Warning, applyDependentDefaults, applyJsonPatch, applyMergePatch, baseType, classifySensitivity, defineDials, deserializeLayer, diffJsonPatch, evaluateConstraints, extractDefaults, getObjectShape, invertJsonPatch, isSecretRef, isUnset, keyMergeStrategy, layerToMergePatch, makeSecretRef, maskEffectiveResult, maskSecrets, mergeValues, readMeta, redactSecretsFromLayer, resolve, serializeLayer, splitBySensitivity };