@spaceteams/weft 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Spaceteams
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.mts

@@ -0,0 +1,488 @@
+//#region src/semantics/algebra.d.ts
+type OpsDescriptor = {
+  readonly family: string;
+  readonly version: string;
+};
+type Equality<T> = {
+  eq(a: T, b: T): boolean;
+};
+type Order<T> = Equality<T> & {
+  compare(a: T, b: T): -1 | 0 | 1;
+};
+type Additive<T> = Equality<T> & {
+  zero(): T;
+  add(a: T, b: T): T;
+  sub(a: T, b: T): T;
+};
+type Scalable<T, S> = {
+  one(): S;
+  scale(value: T, factor: S): T;
+};
+type Divisible<T, R> = {
+  div(a: T, b: T): R;
+};
+declare const defaultOps: OpsDescriptor & Equality<unknown>;
+declare const defaultNumberOps: OpsDescriptor & Order<number> & Additive<number> & Scalable<number, number> & Divisible<number, number>;
+//#endregion
+//#region src/snapshot/canonicalize.d.ts
+type CanonicalJson = null | boolean | number | string | CanonicalJson[] | {
+  [key: string]: CanonicalJson;
+};
+//#endregion
+//#region src/semantics/codec.d.ts
+type Codec<T> = {
+  encode: (value: T) => CanonicalJson;
+  decode: (value: CanonicalJson) => T;
+};
+//#endregion
+//#region src/semantics/formatter.d.ts
+type Formatter<T, C = void> = {
+  format(value: T, context: C): string;
+};
+type Normalizer<T> = {
+  normalize(value: T): T;
+};
+//#endregion
+//#region src/key.d.ts
+type KeySemantics<T> = Equality<T> & Normalizer<T> & Codec<T>;
+type KeyId = string;
+type Key<T> = {
+  readonly id: KeyId;
+  readonly __kind: "key";
+  readonly __value?: T;
+};
+type AnyKey = Key<any>;
+declare function key<T>(id: KeyId): Key<T>;
+//#endregion
+//#region src/facts.d.ts
+type FactBag = Record<KeyId, unknown>;
+//#endregion
+//#region src/overlay/index.d.ts
+type Overlay = Record<KeyId, unknown>;
+type OverlayedFacts = {
+  readonly base: FactBag;
+  readonly overlay: Overlay;
+  readonly effective: FactBag;
+};
+//#endregion
+//#region src/draft/draft-meta.d.ts
+type DraftMeta = {
+  readonly createdBy?: string;
+  readonly createdAt?: string;
+  readonly label?: string;
+};
+//#endregion
+//#region src/draft/index.d.ts
+type DraftId = string;
+type Draft = {
+  readonly draftId: DraftId;
+  readonly base: FactBag;
+  readonly overlay: Overlay;
+  readonly meta?: DraftMeta;
+};
+declare function createDraft(draftId: DraftId, base: FactBag, overlay: Overlay): Draft;
+declare function isEmptyDraft(draft: Draft): boolean;
+//#endregion
+//#region src/input.d.ts
+type Input<T> = {
+  readonly kind: "input";
+  readonly key: Key<T>;
+};
+//#endregion
+//#region src/key-meta.d.ts
+type KeyMeta = {
+  readonly label?: string;
+  readonly description?: string;
+  readonly group?: string;
+  readonly unit?: string;
+  readonly order?: number;
+};
+//#endregion
+//#region src/rule/index.d.ts
+type Resolver = <T>(key: Key<T>) => T;
+type Rule<T> = {
+  readonly __kind: "rule";
+  readonly spec: Record<string, unknown>;
+  readonly target: Key<T>;
+  readonly deps: readonly AnyKey[];
+  readonly eval: (get: Resolver) => {
+    output: T;
+    detail?: Record<string, unknown>;
+  };
+};
+declare function rule<T>(def: {
+  target: Key<T>;
+  deps: readonly AnyKey[];
+  spec: Record<string, unknown>;
+  eval: (get: Resolver) => {
+    output: T;
+    detail?: Record<string, unknown>;
+  };
+}): Rule<T>;
+//#endregion
+//#region src/rule/rule-meta.d.ts
+type RuleMeta = {
+  readonly label?: string;
+  readonly description?: string;
+};
+//#endregion
+//#region src/model/index.d.ts
+type Model = {
+  readonly inputs: readonly Input<unknown>[];
+  readonly rules: readonly Rule<unknown>[];
+  readonly semantics: ReadonlyMap<KeyId, Partial<KeySemantics<unknown>>>;
+  readonly keyMeta: ReadonlyMap<KeyId, KeyMeta>;
+  readonly ruleMeta: ReadonlyMap<KeyId, RuleMeta>;
+};
+type CompiledModel = Model & {
+  readonly keys: ReadonlyMap<KeyId, AnyKey>;
+  readonly semantics: ReadonlyMap<KeyId, Partial<KeySemantics<unknown>>>;
+  readonly inputKeys: readonly KeyId[];
+  readonly orderedRuleTargets: readonly KeyId[];
+  readonly ruleByTarget: ReadonlyMap<KeyId, Rule<unknown>>;
+  readonly depsByTarget: ReadonlyMap<KeyId, readonly KeyId[]>;
+  readonly dependentsByKey: ReadonlyMap<KeyId, readonly KeyId[]>;
+};
+//#endregion
+//#region src/evaluate/trace-step.d.ts
+type TraceStep = {
+  readonly target: KeyId;
+  readonly keyMeta?: KeyMeta;
+  readonly deps: readonly KeyId[];
+  readonly ruleMeta?: RuleMeta;
+  readonly ruleSpec: Record<string, unknown>;
+  readonly inputs: Record<KeyId, unknown>;
+  readonly output: unknown;
+  readonly detail: Record<string, unknown>;
+};
+//#endregion
+//#region src/evaluate/evaluation-result.d.ts
+type MissingReason = {
+  kind: "missing-input";
+  key: KeyId;
+} | {
+  kind: "rule-not-run";
+  key: KeyId;
+  because: KeyId[];
+};
+type EvaluationResult = {
+  readonly values: ReadonlyMap<KeyId, unknown>;
+  readonly missing: ReadonlyMap<KeyId, MissingReason>;
+  readonly order: readonly string[];
+  readonly trace: readonly TraceStep[];
+};
+//#endregion
+//#region src/overlay/diff-results.d.ts
+type ValueDelta = {
+  readonly key: KeyId;
+  readonly kind: "added";
+  readonly after: unknown;
+} | {
+  readonly key: KeyId;
+  readonly kind: "removed";
+  readonly before: unknown;
+} | {
+  readonly key: KeyId;
+  readonly kind: "changed";
+  readonly before: unknown;
+  readonly after: unknown;
+};
+declare function diffResults(model: CompiledModel, before: EvaluationResult, after: EvaluationResult): {
+  deltas: readonly ValueDelta[];
+};
+//#endregion
+//#region src/evaluate/index.d.ts
+type EvaluateMode = "strict" | "lenient";
+declare const defaultEvaluateMode: EvaluateMode;
+declare function evaluate(model: CompiledModel, provided: FactBag, mode?: EvaluateMode): EvaluationResult;
+//#endregion
+//#region src/overlay/evaluate-overlay.d.ts
+type ValueOrigin = {
+  readonly kind: "base";
+} | {
+  readonly kind: "overlay";
+} | {
+  readonly kind: "derived";
+};
+type OriginMap = ReadonlyMap<KeyId, ValueOrigin>;
+type OverlayEvaluationResult = EvaluationResult & {
+  readonly overlayedFacts: OverlayedFacts;
+  readonly origins: OriginMap;
+};
+declare function evaluateOverlay(model: CompiledModel, base: FactBag, overlay: Overlay, mode?: EvaluateMode): OverlayEvaluationResult;
+//#endregion
+//#region src/overlay/diff-group.d.ts
+type DiffGroup = {
+  readonly label: string;
+  readonly deltas: readonly ValueDelta[];
+};
+type GroupedDiff = readonly DiffGroup[];
+//#endregion
+//#region src/overlay/explain-diff.d.ts
+type ExplainedDependency = {
+  readonly key: KeyId;
+  readonly label?: string;
+  readonly kind?: string;
+  readonly changed: boolean;
+};
+type Change = {
+  readonly delta: ValueDelta;
+  readonly dependencies?: readonly ExplainedDependency[];
+};
+declare function explainDiffs(result: OverlayEvaluationResult, deltas: readonly ValueDelta[]): readonly Change[];
+//#endregion
+//#region src/draft/evaluate-draft.d.ts
+type EvaluatedDraft = {
+  readonly draft: Draft;
+  readonly result: OverlayEvaluationResult;
+  readonly deltas: readonly ValueDelta[];
+};
+declare function evaluateDraft(model: CompiledModel, draft: Draft, mode?: EvaluateMode): EvaluatedDraft;
+//#endregion
+//#region src/draft/analyze-draft.d.ts
+type ImpactAnalysis = {
+  readonly direct: readonly KeyId[];
+  readonly affected: readonly KeyId[];
+  readonly terminal: readonly KeyId[];
+};
+type DraftAnalysis = {
+  readonly evaluated: EvaluatedDraft;
+  readonly groupedDiffs: readonly DiffGroup[];
+  readonly changes: readonly Change[];
+  readonly impact: ImpactAnalysis;
+  readonly normalizationIssues: readonly NormalizationIssue[];
+};
+declare function analyzeDraft(model: CompiledModel, draft: Draft, mode?: EvaluateMode): DraftAnalysis;
+type NormalizationIssue = {
+  level: "error" | "warning";
+  key: KeyId;
+  message: string;
+};
+type NormalizedDraft = {
+  draft: Draft;
+  issues: readonly NormalizationIssue[];
+};
+type AnalysisSnapshot = {
+  modelFingerprint: string;
+  baseFingerprint: string;
+  overlayFingerprint: string;
+  analysisFingerprint: string;
+  createdAt: string;
+};
+type FreezeDraftAnalysisInput = {
+  model: CompiledModel;
+  draft: Draft;
+  normalized: NormalizedDraft;
+  evaluated: EvaluatedDraft;
+  groupedDiffs: GroupedDiff;
+  changes: readonly Change[];
+  impact: ImpactAnalysis;
+  now: string;
+};
+declare function freezeDraftAnalysis(model: CompiledModel, analysis: DraftAnalysis): {
+  draftId: string;
+  snapshot: AnalysisSnapshot;
+  base: Record<string, unknown>;
+  overlay: Record<string, unknown>;
+  effective: Record<string, unknown>;
+  values: Record<string, CanonicalJson>;
+  deltas: ValueDelta[];
+  groupedDiffs: {
+    label: string;
+    deltas: ValueDelta[];
+  }[];
+  changes: {
+    delta: ValueDelta;
+    dependencies: readonly ExplainedDependency[] | undefined;
+  }[];
+  impact: ImpactAnalysis;
+  normalizationIssues: readonly NormalizationIssue[];
+  frozenAt: string;
+};
+//#endregion
+//#region src/inspect/inspection-node.d.ts
+type InspectionNode = {
+  key: KeyId;
+  kind: string;
+  label: string;
+  meta?: {
+    key?: KeyMeta;
+    rule?: RuleMeta;
+  };
+  structure?: {
+    ruleSpec?: Record<string, unknown>;
+  };
+  execution?: {
+    value?: unknown;
+    trace?: TraceStep;
+  };
+  change?: Change;
+  children: InspectionNode[];
+};
+//#endregion
+//#region src/inspect/inspect-diff-target.d.ts
+declare function inspectDiffTarget(model: CompiledModel, result: OverlayEvaluationResult, changes: readonly Change[], target: KeyId): InspectionNode;
+//#endregion
+//#region src/inspect/inspect-model-target.d.ts
+declare function inspectModelTarget(model: CompiledModel, target: string): InspectionNode;
+//#endregion
+//#region src/inspect/inspect-trace-target.d.ts
+declare function inspectTraceTarget(model: CompiledModel, trace: readonly TraceStep[], target: KeyId): InspectionNode;
+//#endregion
+//#region src/inspect/inspection-node-to-ascii.d.ts
+type RenderOptions = {
+  showMeta: boolean;
+  showChange: boolean;
+};
+declare const inspectionNodeToAscii: (root: InspectionNode, options: RenderOptions) => string;
+//#endregion
+//#region src/model/compile-model.d.ts
+type ModelIssue = {
+  level: "error" | "warn";
+  code: "DUPLICATE_INPUT" | "DUPLICATE_RULE_TARGET" | "INPUT_RULE_CONFLICT" | "MISSING_DEPENDENCY" | "CYCLE";
+  message: string;
+  keys?: readonly KeyId[];
+};
+type CompileResult = {
+  ok: true;
+  model: CompiledModel;
+  issues: readonly ModelIssue[];
+} | {
+  ok: false;
+  issues: readonly ModelIssue[];
+};
+declare function compileModel(model: Model): CompileResult;
+//#endregion
+//#region src/model/create-model.d.ts
+declare function createModel(): {
+  input<T>(k: Key<T>, meta?: KeyMeta, semantics?: Partial<KeySemantics<T>> | undefined): Key<T>;
+  rule<T>(r: Rule<T>, meta?: RuleMeta, semantics?: Partial<KeySemantics<T>> | undefined): Key<T>;
+  build(): Model;
+};
+//#endregion
+//#region src/model/model.d.ts
+declare function getDependencies(model: CompiledModel, key: AnyKey): readonly KeyId[];
+declare function getDependents(model: CompiledModel, key: AnyKey): readonly KeyId[];
+declare function getDeclaredKeys(model: CompiledModel): readonly KeyId[];
+declare function upstreamOf(model: CompiledModel, key: AnyKey): readonly KeyId[];
+declare function downstreamOf(model: CompiledModel, key: AnyKey): readonly KeyId[];
+declare function sortKeysByModelOrder(model: CompiledModel, keys: Iterable<KeyId>): readonly string[];
+//#endregion
+//#region src/model/model-graph.d.ts
+type ModelGraph = {
+  readonly nodes: readonly KeyId[];
+  readonly edges: readonly {
+    from: KeyId;
+    to: KeyId;
+  }[];
+};
+declare function toGraph(model: CompiledModel): ModelGraph;
+declare function subgraph(model: CompiledModel, includedKeys: readonly KeyId[]): ModelGraph;
+declare function upstreamGraphOf(model: CompiledModel, key: AnyKey, options?: {
+  includeTarget?: boolean;
+}): ModelGraph;
+declare function downstreamGraphOf(model: CompiledModel, key: AnyKey, options?: {
+  includeTarget?: boolean;
+}): ModelGraph;
+//#endregion
+//#region src/value.d.ts
+type Value<T> = {
+  readonly __kind: "value";
+  readonly value: T;
+};
+declare function value<T>(value: T): Value<T>;
+//#endregion
+//#region src/rule/operand.d.ts
+type Operand<T> = Value<T> | Key<T>;
+declare function resolveOperand<T>(operand: Operand<T>, get: (k: Key<T>) => T): T;
+//#endregion
+//#region src/rule/decision.d.ts
+type EqualityPredicate<T> = {
+  source: Key<T>;
+  op: "eq";
+  right: Operand<T>;
+} | {
+  source: Key<T>;
+  op: "in";
+  values: readonly Operand<T>[];
+};
+type OrderedPredicate<T> = {
+  source: Key<T>;
+  op: "gt" | "gte" | "lt" | "lte";
+  right: Operand<T>;
+};
+type Predicate<T> = EqualityPredicate<T> | OrderedPredicate<T>;
+type RowId = string;
+type DecisionRow<T, O, P extends Predicate<T> = Predicate<T>> = {
+  id: RowId;
+  when: readonly P[];
+  output: Operand<O>;
+  label?: string;
+};
+type DecisionTable<T, O, P extends Predicate<T> = Predicate<T>> = {
+  name: string;
+  rows: readonly DecisionRow<T, O, P>[];
+  default?: Operand<O>;
+};
+type RequiredOps<T, P extends Predicate<T>> = Extract<P, OrderedPredicate<T>> extends never ? Equality<T> : Order<T>;
+type DecisionTableTraceDetail = {
+  op: "decision";
+  tableName: string;
+  matchedRowId?: RowId;
+  matchedRowLabel?: RowId;
+  usedDefault: boolean;
+};
+type DecisionTableSpec = {
+  op: "decision";
+  opsDescriptor: OpsDescriptor;
+  table: DecisionTable<unknown, unknown>;
+};
+declare function decision<T, O, P extends Predicate<T>>(ops: OpsDescriptor & RequiredOps<T, P>, target: Key<O>, table: DecisionTable<T, O, P>): Rule<O>;
+//#endregion
+//#region src/rule/projection.d.ts
+type ProjectionSpec = {
+  op: "project";
+  source: KeyId;
+  field: string;
+};
+declare function projection<T extends Record<string, unknown>, K extends keyof T>(target: Key<T[K]>, source: Key<T>, field: K): Rule<T[K]>;
+//#endregion
+//#region src/rule/ratio.d.ts
+type RatioTraceSpec = {
+  op: "ratio";
+  opsDescriptor: OpsDescriptor;
+  numerator: KeyId;
+  denominator: KeyId;
+};
+declare function ratio<T, R>(ops: OpsDescriptor & Divisible<T, R>, target: Key<R>, numerator: Key<T>, denominator: Key<T>): Rule<R>;
+//#endregion
+//#region src/rule/scale.d.ts
+type ScaleTraceSpec = {
+  op: "scale";
+  opsDescriptor: OpsDescriptor;
+  input: KeyId;
+  factor: KeyId;
+};
+declare function scale<T, S>(ops: OpsDescriptor & Scalable<T, S>, target: Key<T>, input: Key<T>, factor: Key<S>): Rule<T>;
+//#endregion
+//#region src/rule/sum.d.ts
+type SumTraceSpec = {
+  op: "sum";
+  opsDescriptor: OpsDescriptor;
+  deps: readonly KeyId[];
+};
+declare function sum<T>(ops: OpsDescriptor & Additive<T>, target: Key<T>, deps: readonly Key<T>[]): Rule<T>;
+//#endregion
+//#region src/rule/weighted-sum.d.ts
+type WeightedSumSpec = {
+  op: "weighted-sum";
+  opsDescriptor: OpsDescriptor;
+  deps: readonly KeyId[];
+  weights: readonly unknown[];
+};
+declare function weightedSum<T, S>(ops: OpsDescriptor & Additive<T> & Scalable<T, S>, target: Key<T>, deps: readonly {
+  key: Key<T>;
+  weight: Operand<S>;
+}[]): Rule<T>;
+//#endregion
+export { Additive, AnyKey, Change, CompileResult, CompiledModel, DecisionRow, DecisionTable, DecisionTableSpec, DecisionTableTraceDetail, Divisible, Draft, DraftAnalysis, DraftId, Equality, EqualityPredicate, EvaluateMode, EvaluatedDraft, EvaluationResult, ExplainedDependency, Formatter, FreezeDraftAnalysisInput, ImpactAnalysis, InspectionNode, Key, KeyId, KeySemantics, MissingReason, Model, ModelGraph, ModelIssue, Normalizer, Operand, OpsDescriptor, Order, OrderedPredicate, OriginMap, OverlayEvaluationResult, Predicate, ProjectionSpec, RatioTraceSpec, RequiredOps, Resolver, RowId, Rule, Scalable, ScaleTraceSpec, SumTraceSpec, Value, ValueDelta, ValueOrigin, WeightedSumSpec, analyzeDraft, compileModel, createDraft, createModel, decision, defaultEvaluateMode, defaultNumberOps, defaultOps, diffResults, downstreamGraphOf, downstreamOf, evaluate, evaluateDraft, evaluateOverlay, explainDiffs, freezeDraftAnalysis, getDeclaredKeys, getDependencies, getDependents, inspectDiffTarget, inspectModelTarget, inspectTraceTarget, inspectionNodeToAscii, isEmptyDraft, key, projection, ratio, resolveOperand, rule, scale, sortKeysByModelOrder, subgraph, sum, toGraph, upstreamGraphOf, upstreamOf, value, weightedSum };