@polintpro/proposit-core 0.3.0 → 0.4.0

package/dist/lib/core/interfaces/premise-engine.interfaces.d.ts

@@ -0,0 +1,317 @@
+import type { TCoreArgument, TCorePremise, TCorePropositionalExpression, TCorePropositionalVariable, TCoreSource, TCoreExpressionSourceAssociation } from "../../schemata/index.js";
+import type { TCoreExpressionAssignment, TCorePremiseEvaluationResult, TCoreValidationResult } from "../../types/evaluation.js";
+import type { TCoreMutationResult } from "../../types/mutation.js";
+import type { TExpressionInput, TExpressionWithoutPosition, TExpressionUpdate } from "../expression-manager.js";
+import type { TPremiseEngineSnapshot } from "../premise-engine.js";
+/**
+ * Single-premise expression tree mutations.
+ */
+export interface TExpressionMutations<TArg extends TCoreArgument = TCoreArgument, TPremise extends TCorePremise = TCorePremise, TExpr extends TCorePropositionalExpression = TCorePropositionalExpression, TVar extends TCorePropositionalVariable = TCorePropositionalVariable, TSource extends TCoreSource = TCoreSource> {
+    /**
+     * Adds an expression to this premise's tree.
+     *
+     * If the expression has `parentId: null` it becomes the root; only one
+     * root is permitted per premise. All structural rules (`implies`/`iff`
+     * root-only, child limits, position uniqueness) are enforced.
+     *
+     * @param expression - The expression to add, including position and
+     *   parent assignment.
+     * @returns The added expression (with checksum) and changeset.
+     * @throws If the premise already has a root expression and this one is
+     *   also a root.
+     * @throws If the expression's parent does not exist in this premise.
+     * @throws If the expression is a variable reference and the variable
+     *   has not been registered.
+     */
+    addExpression(expression: TExpressionInput<TExpr>): TCoreMutationResult<TExpr, TExpr, TVar, TPremise, TArg, TSource>;
+    /**
+     * Adds an expression as the last child of the given parent, with
+     * position computed automatically. If `parentId` is `null`, the
+     * expression becomes the root.
+     *
+     * @param parentId - The parent expression ID, or `null` for root.
+     * @param expression - The expression to add (position is auto-assigned).
+     * @returns The added expression (with checksum) and changeset.
+     * @throws If the premise already has a root and `parentId` is `null`.
+     * @throws If the expression is a variable reference and the variable
+     *   has not been registered.
+     */
+    appendExpression(parentId: string | null, expression: TExpressionWithoutPosition<TExpr>): TCoreMutationResult<TExpr, TExpr, TVar, TPremise, TArg, TSource>;
+    /**
+     * Adds an expression immediately before or after an existing sibling,
+     * with position computed automatically.
+     *
+     * @param siblingId - The ID of the existing sibling expression.
+     * @param relativePosition - Whether to insert `"before"` or `"after"`
+     *   the sibling.
+     * @param expression - The expression to add (position is auto-assigned).
+     * @returns The added expression (with checksum) and changeset.
+     * @throws If the sibling does not exist in this premise.
+     * @throws If the expression is a variable reference and the variable
+     *   has not been registered.
+     */
+    addExpressionRelative(siblingId: string, relativePosition: "before" | "after", expression: TExpressionWithoutPosition<TExpr>): TCoreMutationResult<TExpr, TExpr, TVar, TPremise, TArg, TSource>;
+    /**
+     * Updates mutable fields of an existing expression. Only `position`,
+     * `variableId`, and `operator` may be updated.
+     *
+     * @param expressionId - The ID of the expression to update.
+     * @param updates - The fields to update.
+     * @returns The updated expression and changeset.
+     * @throws If the expression does not exist in this premise.
+     * @throws If `variableId` references a non-existent variable.
+     */
+    updateExpression(expressionId: string, updates: TExpressionUpdate): TCoreMutationResult<TExpr, TExpr, TVar, TPremise, TArg, TSource>;
+    /**
+     * Removes an expression and optionally its entire descendant subtree,
+     * then collapses any ancestor operators with fewer than two children.
+     *
+     * @param expressionId - The ID of the expression to remove.
+     * @param deleteSubtree - Whether to remove all descendants as well.
+     * @returns The removed root expression, or `undefined` if not found.
+     */
+    removeExpression(expressionId: string, deleteSubtree: boolean): TCoreMutationResult<TExpr | undefined, TExpr, TVar, TPremise, TArg, TSource>;
+    /**
+     * Splices a new expression between existing nodes in the tree. The new
+     * expression inherits the tree slot of the anchor node
+     * (`leftNodeId ?? rightNodeId`).
+     *
+     * @param expression - The expression to insert, including position and
+     *   parent assignment.
+     * @param leftNodeId - The existing node to become the left child of
+     *   the new expression.
+     * @param rightNodeId - The existing node to become the right child of
+     *   the new expression.
+     * @returns The inserted expression (with checksum) and changeset.
+     * @throws If the expression is a variable reference and the variable
+     *   has not been registered.
+     */
+    insertExpression(expression: TExpressionInput<TExpr>, leftNodeId?: string, rightNodeId?: string): TCoreMutationResult<TExpr, TExpr, TVar, TPremise, TArg, TSource>;
+    /**
+     * Wraps an existing expression with a new operator and a new sibling
+     * in a single atomic operation.
+     *
+     * The operator takes the existing node's slot in the tree. Both the
+     * existing node and the new sibling become children of the operator.
+     * Exactly one of `leftNodeId` / `rightNodeId` must be provided — it
+     * identifies the existing node and which child slot it occupies.
+     *
+     * @param operator - The new operator expression to wrap with.
+     * @param newSibling - The new sibling expression to add alongside the
+     *   existing node.
+     * @param leftNodeId - The existing node to place as the left child.
+     * @param rightNodeId - The existing node to place as the right child.
+     * @returns The inserted operator (with checksum) and changeset.
+     * @throws If the new sibling is a variable reference and the variable
+     *   has not been registered.
+     */
+    wrapExpression(operator: TExpressionWithoutPosition<TExpr>, newSibling: TExpressionWithoutPosition<TExpr>, leftNodeId?: string, rightNodeId?: string): TCoreMutationResult<TExpr, TExpr, TVar, TPremise, TArg, TSource>;
+    /**
+     * Creates an association between a source and this expression within
+     * this premise.
+     *
+     * @param sourceId - The ID of the source.
+     * @param expressionId - The ID of the expression to associate.
+     * @returns The created association and changeset.
+     * @throws If the source does not exist.
+     * @throws If the expression does not exist in this premise.
+     * @throws If the association already exists.
+     */
+    addExpressionSourceAssociation(sourceId: string, expressionId: string): TCoreMutationResult<TCoreExpressionSourceAssociation, TExpr, TVar, TPremise, TArg, TSource>;
+    /**
+     * Removes an expression–source association by its own ID.
+     *
+     * @param associationId - The ID of the association to remove.
+     * @returns The removed association, or `undefined` if not found.
+     */
+    removeExpressionSourceAssociation(associationId: string): TCoreMutationResult<TCoreExpressionSourceAssociation | undefined, TExpr, TVar, TPremise, TArg, TSource>;
+    /**
+     * Returns all source associations for a given expression in this
+     * premise.
+     *
+     * @param expressionId - The expression ID to look up.
+     * @returns An array of expression–source associations.
+     */
+    getSourceAssociationsForExpression(expressionId: string): TCoreExpressionSourceAssociation[];
+}
+/**
+ * Single-premise expression tree reads.
+ */
+export interface TExpressionQueries<TExpr extends TCorePropositionalExpression = TCorePropositionalExpression> {
+    /**
+     * Returns an expression by ID, or `undefined` if not found in this
+     * premise.
+     *
+     * @param id - The expression ID to look up.
+     * @returns The expression entity, or `undefined`.
+     */
+    getExpression(id: string): TExpr | undefined;
+    /**
+     * Returns the ID of the root expression, or `undefined` if the premise
+     * is empty.
+     *
+     * @returns The root expression ID, or `undefined`.
+     */
+    getRootExpressionId(): string | undefined;
+    /**
+     * Returns the root expression, or `undefined` if the premise is empty.
+     *
+     * @returns The root expression entity, or `undefined`.
+     */
+    getRootExpression(): TExpr | undefined;
+    /**
+     * Returns all expressions in this premise.
+     *
+     * @returns An array of expression entities.
+     */
+    getExpressions(): TExpr[];
+    /**
+     * Returns the child expressions of the given parent, sorted by
+     * position.
+     *
+     * @param parentId - The parent expression ID, or `null` for root-level
+     *   children.
+     * @returns An array of child expression entities.
+     */
+    getChildExpressions(parentId: string | null): TExpr[];
+}
+/**
+ * Variable reference queries and cascade deletion.
+ */
+export interface TVariableReferences<TArg extends TCoreArgument = TCoreArgument, TPremise extends TCorePremise = TCorePremise, TExpr extends TCorePropositionalExpression = TCorePropositionalExpression, TVar extends TCorePropositionalVariable = TCorePropositionalVariable, TSource extends TCoreSource = TCoreSource> {
+    /**
+     * Returns all argument-level variables (from the shared
+     * VariableManager) sorted by ID. Since the VariableManager is shared
+     * across all premises, this returns every registered variable — not
+     * just those referenced by expressions in this premise.
+     *
+     * @returns An array of variable entities.
+     */
+    getVariables(): TVar[];
+    /**
+     * Returns the set of variable IDs referenced by expressions in this
+     * premise. Only variables that appear in `type: "variable"` expression
+     * nodes are included.
+     *
+     * @returns A Set of referenced variable ID strings.
+     */
+    getReferencedVariableIds(): Set<string>;
+    /**
+     * Deletes all expressions that reference the given variable ID,
+     * including their subtrees. Operator collapse runs after each removal.
+     *
+     * @param variableId - The variable ID whose referencing expressions
+     *   should be removed.
+     * @returns The removed expressions and changeset.
+     */
+    deleteExpressionsUsingVariable(variableId: string): TCoreMutationResult<TExpr[], TExpr, TVar, TPremise, TArg, TSource>;
+}
+/**
+ * Premise type classification (inference vs constraint).
+ */
+export interface TPremiseClassification {
+    /**
+     * Returns `true` if the root expression is an `implies` or `iff`
+     * operator, meaning this premise expresses a logical inference
+     * relationship.
+     *
+     * @returns Whether this premise is an inference.
+     */
+    isInference(): boolean;
+    /**
+     * Returns `true` if this premise does not have an inference operator at
+     * its root. Equivalent to `!isInference()`.
+     *
+     * @returns Whether this premise is a constraint.
+     */
+    isConstraint(): boolean;
+}
+/**
+ * Premise-level evaluation: single-assignment evaluation and evaluability
+ * validation.
+ */
+export interface TPremiseEvaluation {
+    /**
+     * Validates that this premise is structurally ready for evaluation.
+     *
+     * @returns A validation result with any issues found.
+     */
+    validateEvaluability(): TCoreValidationResult;
+    /**
+     * Evaluates the premise under a three-valued expression assignment.
+     *
+     * Variable values are looked up using Kleene three-valued logic
+     * (`null` = unknown). Missing variables default to `null`. For
+     * inference premises (`implies`/`iff`), an `inferenceDiagnostic` is
+     * computed with three-valued fields unless the root is rejected.
+     *
+     * @param assignment - The variable assignment and optional rejected
+     *   expression IDs.
+     * @param options - Optional evaluation options.
+     * @param options.strictUnknownKeys - If `true`, unknown variable keys
+     *   in the assignment cause an error.
+     * @param options.requireExactCoverage - If `true`, the assignment must
+     *   cover exactly the referenced variables.
+     * @returns The premise evaluation result.
+     */
+    evaluate(assignment: TCoreExpressionAssignment, options?: {
+        strictUnknownKeys?: boolean;
+        requireExactCoverage?: boolean;
+    }): TCorePremiseEvaluationResult;
+}
+/**
+ * Premise snapshot and mutation callback lifecycle.
+ * Static fromSnapshot factory is class-level only.
+ */
+export interface TPremiseLifecycle<TPremise extends TCorePremise = TCorePremise, TExpr extends TCorePropositionalExpression = TCorePropositionalExpression> {
+    /**
+     * Returns a serializable snapshot of the premise's owned state.
+     *
+     * @returns The premise engine snapshot.
+     */
+    snapshot(): TPremiseEngineSnapshot<TPremise, TExpr>;
+    /**
+     * Sets a callback invoked after every mutation, or `undefined` to
+     * clear.
+     *
+     * @param callback - The mutation callback, or `undefined` to remove.
+     */
+    setOnMutate(callback: (() => void) | undefined): void;
+    /**
+     * Invalidates the cached checksum so the next call recomputes it.
+     */
+    markDirty(): void;
+}
+/**
+ * Premise entity identity and metadata access.
+ */
+export interface TPremiseIdentity<TArg extends TCoreArgument = TCoreArgument, TPremise extends TCorePremise = TCorePremise, TExpr extends TCorePropositionalExpression = TCorePropositionalExpression, TVar extends TCorePropositionalVariable = TCorePropositionalVariable, TSource extends TCoreSource = TCoreSource> {
+    /**
+     * Returns the premise ID.
+     *
+     * @returns The premise ID string.
+     */
+    getId(): string;
+    /**
+     * Returns a serializable premise representation containing only
+     * identity/metadata and checksum. Use `getRootExpressionId()`,
+     * `getExpressions()`, `getReferencedVariableIds()` for runtime state.
+     *
+     * @returns The premise data entity.
+     */
+    toPremiseData(): TPremise;
+    /**
+     * Returns the premise's extra metadata record.
+     *
+     * @returns The extras record.
+     */
+    getExtras(): Record<string, unknown>;
+    /**
+     * Replaces the premise's extra metadata record.
+     *
+     * @param extras - The new extras record.
+     * @returns The previous extras record and changeset.
+     */
+    setExtras(extras: Record<string, unknown>): TCoreMutationResult<Record<string, unknown>, TExpr, TVar, TPremise, TArg, TSource>;
+}
+//# sourceMappingURL=premise-engine.interfaces.d.ts.map

package/dist/lib/core/interfaces/premise-engine.interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"premise-engine.interfaces.d.ts","sourceRoot":"","sources":["../../../../src/lib/core/interfaces/premise-engine.interfaces.ts"],"names":[],"mappings":"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"}

package/dist/lib/core/interfaces/premise-engine.interfaces.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=premise-engine.interfaces.js.map

package/dist/lib/core/interfaces/premise-engine.interfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"premise-engine.interfaces.js","sourceRoot":"","sources":["../../../../src/lib/core/interfaces/premise-engine.interfaces.ts"],"names":[],"mappings":""}

package/dist/lib/core/interfaces/shared.interfaces.d.ts

@@ -0,0 +1,24 @@
+/**
+ * An entity that can produce a human-readable display string.
+ */
+export interface TDisplayable {
+    /**
+     * Renders the entity as a human-readable string.
+     *
+     * @returns A human-readable display string.
+     */
+    toDisplayString(): string;
+}
+/**
+ * An entity that can produce a deterministic content checksum.
+ */
+export interface TChecksummable {
+    /**
+     * Returns a deterministic content checksum. Computed lazily — only
+     * recalculated when state has changed.
+     *
+     * @returns A hex-encoded checksum string.
+     */
+    checksum(): string;
+}
+//# sourceMappingURL=shared.interfaces.d.ts.map

package/dist/lib/core/interfaces/shared.interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.interfaces.d.ts","sourceRoot":"","sources":["../../../../src/lib/core/interfaces/shared.interfaces.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,MAAM,WAAW,YAAY;IACzB;;;;OAIG;IACH,eAAe,IAAI,MAAM,CAAA;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC3B;;;;;OAKG;IACH,QAAQ,IAAI,MAAM,CAAA;CACrB"}

package/dist/lib/core/interfaces/shared.interfaces.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=shared.interfaces.js.map

package/dist/lib/core/interfaces/shared.interfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"shared.interfaces.js","sourceRoot":"","sources":["../../../../src/lib/core/interfaces/shared.interfaces.ts"],"names":[],"mappings":""}

package/dist/lib/core/interfaces/source-management.interfaces.d.ts

@@ -0,0 +1,110 @@
+import type { TCoreArgument, TCorePremise, TCorePropositionalExpression, TCorePropositionalVariable, TOptionalChecksum, TCoreSource, TCoreVariableSourceAssociation, TCoreExpressionSourceAssociation } from "../../schemata/index.js";
+import type { TCoreMutationResult } from "../../types/mutation.js";
+/**
+ * Source CRUD, association management, and lookup for an argument.
+ */
+export interface TSourceManagement<TArg extends TCoreArgument = TCoreArgument, TPremise extends TCorePremise = TCorePremise, TExpr extends TCorePropositionalExpression = TCorePropositionalExpression, TVar extends TCorePropositionalVariable = TCorePropositionalVariable, TSource extends TCoreSource = TCoreSource> {
+    /**
+     * Registers a new source with this argument.
+     *
+     * @param source - The source entity to add, with optional checksum.
+     * @returns The added source (with checksum) and changeset.
+     * @throws If a source with the given ID already exists.
+     */
+    addSource(source: TOptionalChecksum<TSource>): TCoreMutationResult<TSource, TExpr, TVar, TPremise, TArg, TSource>;
+    /**
+     * Removes a source and any associations referencing it.
+     *
+     * @param sourceId - The ID of the source to remove.
+     * @returns The removed source, or `undefined` if not found.
+     */
+    removeSource(sourceId: string): TCoreMutationResult<TSource | undefined, TExpr, TVar, TPremise, TArg, TSource>;
+    /**
+     * Creates an association between a source and a variable.
+     *
+     * @param sourceId - The ID of the source.
+     * @param variableId - The ID of the variable to associate.
+     * @returns The created association and changeset.
+     * @throws If the source does not exist.
+     * @throws If the variable does not exist.
+     * @throws If the association already exists.
+     */
+    addVariableSourceAssociation(sourceId: string, variableId: string): TCoreMutationResult<TCoreVariableSourceAssociation, TExpr, TVar, TPremise, TArg, TSource>;
+    /**
+     * Removes a variable–source association by its own ID.
+     *
+     * @param associationId - The ID of the association to remove.
+     * @returns The removed association, or `undefined` if not found.
+     */
+    removeVariableSourceAssociation(associationId: string): TCoreMutationResult<TCoreVariableSourceAssociation | undefined, TExpr, TVar, TPremise, TArg, TSource>;
+    /**
+     * Creates an association between a source and an expression within a
+     * specific premise.
+     *
+     * @param sourceId - The ID of the source.
+     * @param expressionId - The ID of the expression to associate.
+     * @param premiseId - The ID of the premise that owns the expression.
+     * @returns The created association and changeset.
+     * @throws If the source does not exist.
+     * @throws If the expression does not exist in the specified premise.
+     * @throws If the association already exists.
+     */
+    addExpressionSourceAssociation(sourceId: string, expressionId: string, premiseId: string): TCoreMutationResult<TCoreExpressionSourceAssociation, TExpr, TVar, TPremise, TArg, TSource>;
+    /**
+     * Removes an expression–source association by its own ID.
+     *
+     * @param associationId - The ID of the association to remove.
+     * @returns The removed association, or `undefined` if not found.
+     */
+    removeExpressionSourceAssociation(associationId: string): TCoreMutationResult<TCoreExpressionSourceAssociation | undefined, TExpr, TVar, TPremise, TArg, TSource>;
+    /**
+     * Returns all registered sources sorted by ID.
+     *
+     * @returns An array of source entities.
+     */
+    getSources(): TSource[];
+    /**
+     * Returns the source with the given ID, or `undefined` if not found.
+     *
+     * @param sourceId - The source ID to look up.
+     * @returns The source entity, or `undefined`.
+     */
+    getSource(sourceId: string): TSource | undefined;
+    /**
+     * Returns all variable and expression associations for a given source.
+     *
+     * @param sourceId - The source ID to look up.
+     * @returns An object with `variable` and `expression` association arrays.
+     */
+    getAssociationsForSource(sourceId: string): {
+        variable: TCoreVariableSourceAssociation[];
+        expression: TCoreExpressionSourceAssociation[];
+    };
+    /**
+     * Returns all source associations for a given variable.
+     *
+     * @param variableId - The variable ID to look up.
+     * @returns An array of variable–source associations.
+     */
+    getAssociationsForVariable(variableId: string): TCoreVariableSourceAssociation[];
+    /**
+     * Returns all source associations for a given expression.
+     *
+     * @param expressionId - The expression ID to look up.
+     * @returns An array of expression–source associations.
+     */
+    getAssociationsForExpression(expressionId: string): TCoreExpressionSourceAssociation[];
+    /**
+     * Returns all variable–source associations across the argument.
+     *
+     * @returns An array of all variable–source association entities.
+     */
+    getAllVariableSourceAssociations(): TCoreVariableSourceAssociation[];
+    /**
+     * Returns all expression–source associations across the argument.
+     *
+     * @returns An array of all expression–source association entities.
+     */
+    getAllExpressionSourceAssociations(): TCoreExpressionSourceAssociation[];
+}
+//# sourceMappingURL=source-management.interfaces.d.ts.map

package/dist/lib/core/interfaces/source-management.interfaces.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-management.interfaces.d.ts","sourceRoot":"","sources":["../../../../src/lib/core/interfaces/source-management.interfaces.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACR,aAAa,EACb,YAAY,EACZ,4BAA4B,EAC5B,0BAA0B,EAC1B,iBAAiB,EACjB,WAAW,EACX,8BAA8B,EAC9B,gCAAgC,EACnC,MAAM,yBAAyB,CAAA;AAChC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,yBAAyB,CAAA;AAElE;;GAEG;AACH,MAAM,WAAW,iBAAiB,CAC9B,IAAI,SAAS,aAAa,GAAG,aAAa,EAC1C,QAAQ,SAAS,YAAY,GAAG,YAAY,EAC5C,KAAK,SAAS,4BAA4B,GAAG,4BAA4B,EACzE,IAAI,SAAS,0BAA0B,GAAG,0BAA0B,EACpE,OAAO,SAAS,WAAW,GAAG,WAAW;IAEzC;;;;;;OAMG;IACH,SAAS,CACL,MAAM,EAAE,iBAAiB,CAAC,OAAO,CAAC,GACnC,mBAAmB,CAAC,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,CAAC,CAAA;IAErE;;;;;OAKG;IACH,YAAY,CACR,QAAQ,EAAE,MAAM,GACjB,mBAAmB,CAClB,OAAO,GAAG,SAAS,EACnB,KAAK,EACL,IAAI,EACJ,QAAQ,EACR,IAAI,EACJ,OAAO,CACV,CAAA;IAED;;;;;;;;;OASG;IACH,4BAA4B,CACxB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACnB,mBAAmB,CAClB,8BAA8B,EAC9B,KAAK,EACL,IAAI,EACJ,QAAQ,EACR,IAAI,EACJ,OAAO,CACV,CAAA;IAED;;;;;OAKG;IACH,+BAA+B,CAC3B,aAAa,EAAE,MAAM,GACtB,mBAAmB,CAClB,8BAA8B,GAAG,SAAS,EAC1C,KAAK,EACL,IAAI,EACJ,QAAQ,EACR,IAAI,EACJ,OAAO,CACV,CAAA;IAED;;;;;;;;;;;OAWG;IACH,8BAA8B,CAC1B,QAAQ,EAAE,MAAM,EAChB,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,GAClB,mBAAmB,CAClB,gCAAgC,EAChC,KAAK,EACL,IAAI,EACJ,QAAQ,EACR,IAAI,EACJ,OAAO,CACV,CAAA;IAED;;;;;OAKG;IACH,iCAAiC,CAC7B,aAAa,EAAE,MAAM,GACtB,mBAAmB,CAClB,gCAAgC,GAAG,SAAS,EAC5C,KAAK,EACL,IAAI,EACJ,QAAQ,EACR,IAAI,EACJ,OAAO,CACV,CAAA;IAED;;;;OAIG;IACH,UAAU,IAAI,OAAO,EAAE,CAAA;IAEvB;;;;;OAKG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAA;IAEhD;;;;;OAKG;IACH,wBAAwB,CAAC,QAAQ,EAAE,MAAM,GAAG;QACxC,QAAQ,EAAE,8BAA8B,EAAE,CAAA;QAC1C,UAAU,EAAE,gCAAgC,EAAE,CAAA;KACjD,CAAA;IAED;;;;;OAKG;IACH,0BAA0B,CACtB,UAAU,EAAE,MAAM,GACnB,8BAA8B,EAAE,CAAA;IAEnC;;;;;OAKG;IACH,4BAA4B,CACxB,YAAY,EAAE,MAAM,GACrB,gCAAgC,EAAE,CAAA;IAErC;;;;OAIG;IACH,gCAAgC,IAAI,8BAA8B,EAAE,CAAA;IAEpE;;;;OAIG;IACH,kCAAkC,IAAI,gCAAgC,EAAE,CAAA;CAC3E"}

package/dist/lib/core/interfaces/source-management.interfaces.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=source-management.interfaces.js.map

package/dist/lib/core/interfaces/source-management.interfaces.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"source-management.interfaces.js","sourceRoot":"","sources":["../../../../src/lib/core/interfaces/source-management.interfaces.ts"],"names":[],"mappings":""}