@polintpro/proposit-core 0.5.3 → 0.5.8

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

@@ -1,36 +1,265 @@
 import type { TCoreClaim } from "../../schemata/claim.js";
 import type { TCoreClaimSourceAssociation, TCoreSource } from "../../schemata/source.js";
-/** Narrow read-only interface for claim lookups. Used by ArgumentEngine for validation. */
+/**
+ * Narrow read-only interface for claim lookups. Used by `ArgumentEngine` for
+ * variable validation — callers that only need to verify claim existence
+ * should depend on this rather than the full `ClaimLibrary`.
+ */
 export interface TClaimLookup<TClaim extends TCoreClaim = TCoreClaim> {
+    /**
+     * Returns a claim by ID and version, or `undefined` if not found.
+     *
+     * @param id - The claim ID.
+     * @param version - The claim version number.
+     * @returns The claim entity, or `undefined`.
+     */
     get(id: string, version: number): TClaim | undefined;
 }
-/** Narrow read-only interface for source lookups. Used by ArgumentEngine for validation. */
+/**
+ * Narrow read-only interface for source lookups. Used by `ArgumentEngine` for
+ * validation — callers that only need to verify source existence should depend
+ * on this rather than the full `SourceLibrary`.
+ */
 export interface TSourceLookup<TSource extends TCoreSource = TCoreSource> {
+    /**
+     * Returns a source by ID and version, or `undefined` if not found.
+     *
+     * @param id - The source ID.
+     * @param version - The source version number.
+     * @returns The source entity, or `undefined`.
+     */
     get(id: string, version: number): TSource | undefined;
 }
-/** Serializable snapshot of a ClaimLibrary. */
-export type TClaimLibrarySnapshot<TClaim extends TCoreClaim = TCoreClaim> = {
-    claims: TClaim[];
-};
-/** Serializable snapshot of a SourceLibrary. */
-export type TSourceLibrarySnapshot<TSource extends TCoreSource = TCoreSource> = {
-    sources: TSource[];
-};
+/**
+ * Full management interface for a versioned claim library. Extends
+ * `TClaimLookup` with mutation, query, and snapshot methods.
+ */
+export interface TClaimLibraryManagement<TClaim extends TCoreClaim = TCoreClaim> extends TClaimLookup<TClaim> {
+    /**
+     * Creates a new claim at version 0. The `version`, `frozen`, and
+     * `checksum` fields are assigned automatically.
+     *
+     * @param claim - The claim data without system-managed fields.
+     * @returns The created claim entity with all fields populated.
+     * @throws If a claim with the same ID already exists.
+     */
+    create(claim: Omit<TClaim, "version" | "frozen" | "checksum">): TClaim;
+    /**
+     * Updates mutable fields on the current (latest, unfrozen) version of a
+     * claim. System-managed fields (`id`, `version`, `frozen`, `checksum`)
+     * cannot be updated.
+     *
+     * @param id - The claim ID.
+     * @param updates - The fields to update.
+     * @returns The updated claim entity.
+     * @throws If the claim does not exist.
+     * @throws If the current version is frozen.
+     */
+    update(id: string, updates: Partial<Omit<TClaim, "id" | "version" | "frozen" | "checksum">>): TClaim;
+    /**
+     * Freezes the current version of a claim (marking it immutable) and
+     * creates a new mutable version at `version + 1`.
+     *
+     * @param id - The claim ID.
+     * @returns An object containing the `frozen` version and the new
+     *   `current` (mutable) version.
+     * @throws If the claim does not exist.
+     * @throws If the current version is already frozen.
+     */
+    freeze(id: string): {
+        frozen: TClaim;
+        current: TClaim;
+    };
+    /**
+     * Returns the latest version of a claim, or `undefined` if not found.
+     *
+     * @param id - The claim ID.
+     * @returns The latest claim entity, or `undefined`.
+     */
+    getCurrent(id: string): TClaim | undefined;
+    /**
+     * Returns all claim entities across all IDs and versions.
+     *
+     * @returns An array of all claim entities.
+     */
+    getAll(): TClaim[];
+    /**
+     * Returns all versions of a claim sorted by version number ascending.
+     *
+     * @param id - The claim ID.
+     * @returns An array of claim entities, or an empty array if the ID does
+     *   not exist.
+     */
+    getVersions(id: string): TClaim[];
+    /**
+     * Returns a serializable snapshot of all claims in the library.
+     *
+     * @returns The claim library snapshot.
+     */
+    snapshot(): TClaimLibrarySnapshot<TClaim>;
+}
+/**
+ * Full management interface for a versioned source library. Extends
+ * `TSourceLookup` with mutation, query, and snapshot methods.
+ */
+export interface TSourceLibraryManagement<TSource extends TCoreSource = TCoreSource> extends TSourceLookup<TSource> {
+    /**
+     * Creates a new source at version 0. The `version`, `frozen`, and
+     * `checksum` fields are assigned automatically.
+     *
+     * @param source - The source data without system-managed fields.
+     * @returns The created source entity with all fields populated.
+     * @throws If a source with the same ID already exists.
+     */
+    create(source: Omit<TSource, "version" | "frozen" | "checksum">): TSource;
+    /**
+     * Updates mutable fields on the current (latest, unfrozen) version of a
+     * source. System-managed fields (`id`, `version`, `frozen`, `checksum`)
+     * cannot be updated.
+     *
+     * @param id - The source ID.
+     * @param updates - The fields to update.
+     * @returns The updated source entity.
+     * @throws If the source does not exist.
+     * @throws If the current version is frozen.
+     */
+    update(id: string, updates: Partial<Omit<TSource, "id" | "version" | "frozen" | "checksum">>): TSource;
+    /**
+     * Freezes the current version of a source (marking it immutable) and
+     * creates a new mutable version at `version + 1`.
+     *
+     * @param id - The source ID.
+     * @returns An object containing the `frozen` version and the new
+     *   `current` (mutable) version.
+     * @throws If the source does not exist.
+     * @throws If the current version is already frozen.
+     */
+    freeze(id: string): {
+        frozen: TSource;
+        current: TSource;
+    };
+    /**
+     * Returns the latest version of a source, or `undefined` if not found.
+     *
+     * @param id - The source ID.
+     * @returns The latest source entity, or `undefined`.
+     */
+    getCurrent(id: string): TSource | undefined;
+    /**
+     * Returns all source entities across all IDs and versions.
+     *
+     * @returns An array of all source entities.
+     */
+    getAll(): TSource[];
+    /**
+     * Returns all versions of a source sorted by version number ascending.
+     *
+     * @param id - The source ID.
+     * @returns An array of source entities, or an empty array if the ID does
+     *   not exist.
+     */
+    getVersions(id: string): TSource[];
+    /**
+     * Returns a serializable snapshot of all sources in the library.
+     *
+     * @returns The source library snapshot.
+     */
+    snapshot(): TSourceLibrarySnapshot<TSource>;
+}
 /**
  * Narrow read-only interface for claim-source association lookups.
  * Implemented by `ClaimSourceLibrary`. Passed to `ArgumentEngine` as the
  * fourth constructor parameter.
  */
 export interface TClaimSourceLookup<TAssoc extends TCoreClaimSourceAssociation = TCoreClaimSourceAssociation> {
-    /** Returns all associations for the given claim ID. */
+    /**
+     * Returns all associations for the given claim ID.
+     *
+     * @param claimId - The claim ID to filter by.
+     * @returns An array of matching associations.
+     */
     getForClaim(claimId: string): TAssoc[];
-    /** Returns all associations for the given source ID. */
+    /**
+     * Returns all associations for the given source ID.
+     *
+     * @param sourceId - The source ID to filter by.
+     * @returns An array of matching associations.
+     */
     getForSource(sourceId: string): TAssoc[];
-    /** Returns an association by ID, or `undefined` if not found. */
+    /**
+     * Returns an association by ID, or `undefined` if not found.
+     *
+     * @param id - The association ID.
+     * @returns The association entity, or `undefined`.
+     */
     get(id: string): TAssoc | undefined;
 }
-/** Serializable snapshot of a ClaimSourceLibrary (`{ claimSourceAssociations }`). */
+/**
+ * Full management interface for a claim-source association library. Extends
+ * `TClaimSourceLookup` with mutation, query, and snapshot methods.
+ * Associations are create-or-delete only — no update path.
+ */
+export interface TClaimSourceLibraryManagement<TAssoc extends TCoreClaimSourceAssociation = TCoreClaimSourceAssociation> extends TClaimSourceLookup<TAssoc> {
+    /**
+     * Creates a claim-source association. Validates that the referenced claim
+     * and source exist in their respective libraries.
+     *
+     * @param assoc - The association data without the `checksum` field.
+     * @returns The created association with checksum populated.
+     * @throws If an association with the same ID already exists.
+     * @throws If the referenced claim or source does not exist.
+     */
+    add(assoc: Omit<TAssoc, "checksum">): TAssoc;
+    /**
+     * Removes a claim-source association by ID.
+     *
+     * @param id - The association ID to remove.
+     * @returns The removed association entity.
+     * @throws If the association does not exist.
+     */
+    remove(id: string): TAssoc;
+    /**
+     * Returns all associations in the library.
+     *
+     * @returns An array of all association entities.
+     */
+    getAll(): TAssoc[];
+    /**
+     * Returns all associations matching the predicate.
+     *
+     * @param predicate - A filter function applied to each association.
+     * @returns An array of matching associations.
+     */
+    filter(predicate: (a: TAssoc) => boolean): TAssoc[];
+    /**
+     * Returns a serializable snapshot of all associations in the library.
+     *
+     * @returns The claim-source library snapshot.
+     */
+    snapshot(): TClaimSourceLibrarySnapshot<TAssoc>;
+}
+/**
+ * Serializable snapshot of a `ClaimLibrary`. Contains all claim entities
+ * across all IDs and versions.
+ */
+export type TClaimLibrarySnapshot<TClaim extends TCoreClaim = TCoreClaim> = {
+    /** All claim entities in the library. */
+    claims: TClaim[];
+};
+/**
+ * Serializable snapshot of a `SourceLibrary`. Contains all source entities
+ * across all IDs and versions.
+ */
+export type TSourceLibrarySnapshot<TSource extends TCoreSource = TCoreSource> = {
+    /** All source entities in the library. */
+    sources: TSource[];
+};
+/**
+ * Serializable snapshot of a `ClaimSourceLibrary`. Contains all association
+ * entities.
+ */
 export type TClaimSourceLibrarySnapshot<TAssoc extends TCoreClaimSourceAssociation = TCoreClaimSourceAssociation> = {
+    /** All claim-source association entities in the library. */
     claimSourceAssociations: TAssoc[];
 };
 //# sourceMappingURL=library.interfaces.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"library.interfaces.d.ts","sourceRoot":"","sources":["../../../../src/lib/core/interfaces/library.interfaces.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,yBAAyB,CAAA;AACzD,OAAO,KAAK,EACR,2BAA2B,EAC3B,WAAW,EACd,MAAM,0BAA0B,CAAA;AAEjC,2FAA2F;AAC3F,MAAM,WAAW,YAAY,CAAC,MAAM,SAAS,UAAU,GAAG,UAAU;IAChE,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;CACvD;AAED,4FAA4F;AAC5F,MAAM,WAAW,aAAa,CAAC,OAAO,SAAS,WAAW,GAAG,WAAW;IACpE,GAAG,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,GAAG,SAAS,CAAA;CACxD;AAED,+CAA+C;AAC/C,MAAM,MAAM,qBAAqB,CAAC,MAAM,SAAS,UAAU,GAAG,UAAU,IAAI;IACxE,MAAM,EAAE,MAAM,EAAE,CAAA;CACnB,CAAA;AAED,gDAAgD;AAChD,MAAM,MAAM,sBAAsB,CAAC,OAAO,SAAS,WAAW,GAAG,WAAW,IACxE;IACI,OAAO,EAAE,OAAO,EAAE,CAAA;CACrB,CAAA;AAEL;;;;GAIG;AACH,MAAM,WAAW,kBAAkB,CAC/B,MAAM,SAAS,2BAA2B,GAAG,2BAA2B;IAExE,uDAAuD;IACvD,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IACtC,wDAAwD;IACxD,YAAY,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,CAAA;IACxC,iEAAiE;IACjE,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;CACtC;AAED,qFAAqF;AACrF,MAAM,MAAM,2BAA2B,CACnC,MAAM,SAAS,2BAA2B,GAAG,2BAA2B,IACxE;IACA,uBAAuB,EAAE,MAAM,EAAE,CAAA;CACpC,CAAA"}
+{"version":3,"file":"library.interfaces.d.ts","sourceRoot":"","sources":["../../../../src/lib/core/interfaces/library.interfaces.ts"],"names":[],"mappings":"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"}

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

@@ -14,6 +14,13 @@ export interface TExpressionMutations<TArg extends TCoreArgument = TCoreArgument
      * root is permitted per premise. All structural rules (`implies`/`iff`
      * root-only, child limits, position uniqueness) are enforced.
      *
+     * When `grammarConfig.autoNormalize` is `true`, operator nesting
+     * violations are auto-corrected by inserting a `formula` buffer between
+     * the parent operator and the non-`not` operator child, rather than
+     * throwing. Auto-normalize is only active for `addExpression`; compound
+     * operations (`insertExpression`, `wrapExpression`) and `removeExpression`
+     * always throw on violations regardless of this flag.
+     *
      * @param expression - The expression to add, including position and
      *   parent assignment.
      * @returns The added expression (with checksum) and changeset.
@@ -22,6 +29,8 @@ export interface TExpressionMutations<TArg extends TCoreArgument = TCoreArgument
      * @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.
+     * @throws If a non-not operator would become a direct child of another
+     *   operator expression (when `autoNormalize` is `false`).
      */
     addExpression(expression: TExpressionInput<TExpr>): TCoreMutationResult<TExpr, TExpr, TVar, TPremise, TArg>;
     /**
@@ -35,6 +44,8 @@ export interface TExpressionMutations<TArg extends TCoreArgument = TCoreArgument
      * @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.
+     * @throws If a non-not operator would become a direct child of another
+     *   operator expression.
      */
     appendExpression(parentId: string | null, expression: TExpressionWithoutPosition<TExpr>): TCoreMutationResult<TExpr, TExpr, TVar, TPremise, TArg>;
     /**
@@ -49,6 +60,8 @@ export interface TExpressionMutations<TArg extends TCoreArgument = TCoreArgument
      * @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.
+     * @throws If a non-not operator would become a direct child of another
+     *   operator expression.
      */
     addExpressionRelative(siblingId: string, relativePosition: "before" | "after", expression: TExpressionWithoutPosition<TExpr>): TCoreMutationResult<TExpr, TExpr, TVar, TPremise, TArg>;
     /**
@@ -69,6 +82,8 @@ export interface TExpressionMutations<TArg extends TCoreArgument = TCoreArgument
      * @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.
+     * @throws If removal would promote a non-not operator as a direct
+     *   child of another operator expression.
      */
     removeExpression(expressionId: string, deleteSubtree: boolean): TCoreMutationResult<TExpr | undefined, TExpr, TVar, TPremise, TArg>;
     /**
@@ -85,6 +100,8 @@ export interface TExpressionMutations<TArg extends TCoreArgument = TCoreArgument
      * @returns The inserted expression (with checksum) and changeset.
      * @throws If the expression is a variable reference and the variable
      *   has not been registered.
+     * @throws If a non-not operator would become a direct child of another
+     *   operator expression.
      */
     insertExpression(expression: TExpressionInput<TExpr>, leftNodeId?: string, rightNodeId?: string): TCoreMutationResult<TExpr, TExpr, TVar, TPremise, TArg>;
     /**
@@ -104,6 +121,8 @@ export interface TExpressionMutations<TArg extends TCoreArgument = TCoreArgument
      * @returns The inserted operator (with checksum) and changeset.
      * @throws If the new sibling is a variable reference and the variable
      *   has not been registered.
+     * @throws If a non-not operator would become a direct child of another
+     *   operator expression.
      */
     wrapExpression(operator: TExpressionWithoutPosition<TExpr>, newSibling: TExpressionWithoutPosition<TExpr>, leftNodeId?: string, rightNodeId?: string): TCoreMutationResult<TExpr, TExpr, TVar, TPremise, TArg>;
     /**
@@ -261,6 +280,25 @@ export interface TPremiseLifecycle<TPremise extends TCorePremise = TCorePremise,
      * @param callback - The mutation callback, or `undefined` to remove.
      */
     setOnMutate(callback: (() => void) | undefined): void;
+    /**
+     * Sets a callback that checks whether adding a variable-expression to a
+     * premise would create a circular binding. Injected by `ArgumentEngine`
+     * to enable cross-premise cycle detection. If not set, only the direct
+     * check (within the premise itself) runs.
+     *
+     * @param check - A function that returns `true` if adding the variable
+     *   to the premise would create a cycle, or `undefined` to clear.
+     */
+    setCircularityCheck(check: ((variableId: string, premiseId: string) => boolean) | undefined): void;
+    /**
+     * Sets a callback that checks whether a premise-bound variable's target
+     * premise has an empty expression tree. Injected by `ArgumentEngine` to
+     * enable cross-premise validation. Used during `validateEvaluability`.
+     *
+     * @param check - A function that returns `true` if the variable's bound
+     *   premise has no root expression, or `undefined` to clear.
+     */
+    setEmptyBoundPremiseCheck(check: ((variableId: string) => boolean) | undefined): void;
     /**
      * Invalidates the cached checksum so the next call recomputes it.
      */

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

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