@proposit/proposit-core 0.8.9

package/dist/lib/utils/position.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"position.d.ts","sourceRoot":"","sources":["../../../src/lib/utils/position.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,mBAAmB,GAAG;IAC9B,GAAG,EAAE,MAAM,CAAA;IACX,GAAG,EAAE,MAAM,CAAA;IACX,OAAO,EAAE,MAAM,CAAA;CAClB,CAAA;AAED,eAAO,MAAM,YAAY,cAAc,CAAA;AACvC,eAAO,MAAM,YAAY,aAAa,CAAA;AACtC,eAAO,MAAM,gBAAgB,IAAI,CAAA;AAEjC,eAAO,MAAM,uBAAuB,EAAE,mBAIrC,CAAA;AAED,gFAAgF;AAChF,wBAAgB,QAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAErD"}

package/dist/lib/utils/position.js

@@ -0,0 +1,13 @@
+export const POSITION_MIN = -2147483647;
+export const POSITION_MAX = 2147483647;
+export const POSITION_INITIAL = 0;
+export const DEFAULT_POSITION_CONFIG = {
+    min: POSITION_MIN,
+    max: POSITION_MAX,
+    initial: POSITION_INITIAL,
+};
+/** Returns the integer midpoint between two numbers, truncating toward zero. */
+export function midpoint(a, b) {
+    return Math.trunc(a + (b - a) / 2);
+}
+//# sourceMappingURL=position.js.map

package/dist/lib/utils/position.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"position.js","sourceRoot":"","sources":["../../../src/lib/utils/position.ts"],"names":[],"mappings":"AAMA,MAAM,CAAC,MAAM,YAAY,GAAG,CAAC,UAAU,CAAA;AACvC,MAAM,CAAC,MAAM,YAAY,GAAG,UAAU,CAAA;AACtC,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAC,CAAA;AAEjC,MAAM,CAAC,MAAM,uBAAuB,GAAwB;IACxD,GAAG,EAAE,YAAY;IACjB,GAAG,EAAE,YAAY;IACjB,OAAO,EAAE,gBAAgB;CAC5B,CAAA;AAED,gFAAgF;AAChF,MAAM,UAAU,QAAQ,CAAC,CAAS,EAAE,CAAS;IACzC,OAAO,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC,CAAC,CAAA;AACtC,CAAC"}

package/package.json

@@ -0,0 +1,82 @@
+{
+    "name": "@proposit/proposit-core",
+    "version": "0.8.9",
+    "description": "Core engine for building and manipulating propositional logic arguments.",
+    "license": "MIT",
+    "keywords": [
+        "propositional-logic",
+        "logic-engine",
+        "argument",
+        "validation",
+        "formal-logic"
+    ],
+    "homepage": "https://github.com/Proposit-App/proposit-core",
+    "type": "module",
+    "engines": {
+        "node": ">=22.3.0"
+    },
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        },
+        "./extensions/ieee": {
+            "types": "./dist/extensions/ieee/index.d.ts",
+            "import": "./dist/extensions/ieee/index.js"
+        },
+        "./extensions/basics": {
+            "types": "./dist/extensions/basics/index.d.ts",
+            "import": "./dist/extensions/basics/index.js"
+        }
+    },
+    "bin": {
+        "proposit-core": "./dist/cli.js"
+    },
+    "files": [
+        "dist",
+        "skills"
+    ],
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Proposit-App/proposit-core.git"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "scripts": {
+        "generate:parser": "peggy --format es -o src/lib/core/parser/formula-gen.js src/lib/core/parser/formula.peggy",
+        "build": "rm -rf dist tsconfig.build.tsbuildinfo && pnpm run generate:parser && pnpm tsc -p tsconfig.build.json && cp src/lib/core/parser/formula-gen.js dist/lib/core/parser/formula-gen.js && pnpm run docs",
+        "typecheck": "pnpm tsc -p tsconfig.json",
+        "lint": "pnpm run prettify:check && pnpm eslint .",
+        "prettify": "pnpm prettier -w .",
+        "prettify:check": "pnpm prettier --check .",
+        "test": "pnpm vitest run",
+        "check": "pnpm run typecheck && pnpm run lint && pnpm run test && pnpm run build",
+        "docs": "typedoc",
+        "cli": "node dist/cli.js",
+        "preversion": "pnpm run check",
+        "prepublishOnly": "pnpm run check"
+    },
+    "devDependencies": {
+        "@types/js-yaml": "^4.0.9",
+        "@types/node": "^25.5.2",
+        "eslint": "^9.28.0",
+        "eslint-plugin-check-file": "^3.3.1",
+        "eslint-plugin-n": "^17.24.0",
+        "globals": "^17.4.0",
+        "peggy": "^5.1.0",
+        "prettier": "^3.8.1",
+        "typedoc": "^0.28.18",
+        "typescript": "^6.0.2",
+        "typescript-eslint": "^8.58.0",
+        "vitest": "^4.1.2"
+    },
+    "packageManager": "pnpm@10.23.0",
+    "dependencies": {
+        "commander": "^14.0.3",
+        "js-yaml": "^4.1.1",
+        "typebox": "^1.1.14"
+    }
+}

package/skills/proposit-core/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: proposit-core
+description: Use when working with the proposit-core library — building propositional logic arguments, managing premises/variables/expressions, evaluating with Kleene three-valued logic, or using the proposit-core CLI.
+---
+
+# proposit-core
+
+A TypeScript library and CLI for building, evaluating, and analyzing propositional logic arguments using Kleene three-valued logic.
+
+## When to Use
+
+- Building or manipulating propositional logic arguments programmatically
+- Managing premises, variables, and expression trees
+- Evaluating arguments under variable assignments (three-valued: true/false/null)
+- Checking argument validity via truth-table enumeration
+- Diffing argument versions or analyzing premise relationships
+- Using the proposit-core CLI to manage arguments on disk
+- Writing tests for proposit-core features
+
+## Key Patterns
+
+- All mutating methods return `TCoreMutationResult<T>` — destructure `{ result, changes }`
+- Intent-based expression insertion: prefer `appendExpression`/`addExpressionRelative` over `addExpression`
+- Supporting premises derived from expression type (no explicit assignment)
+- Per-entity checksums are lazy (computed on read)
+- ESM with `.js` extensions on all relative imports
+- Typebox schemas with `Value.Parse()` for runtime validation
+
+## Reference
+
+- **API Usage** — `docs/api-usage.md` — Creating arguments, managing premises/variables/expressions, evaluation, validity checking, diffing, relationship analysis.
+- **Architecture & Design** — `docs/architecture.md` — Class hierarchy, expression tree internals, midpoint positions, operator collapse, mutation changesets, checksums.
+- **Types & Schemas** — `docs/types-schemas.md` — All exported types: expression unions, evaluation types, mutation result types, diff types, relationship types, checksum config.
+- **Testing** — `docs/testing.md` — Test file structure, describe block conventions, fixture patterns, how to add new tests.
+- **CLI** — `docs/cli.md` — CLI routing, state storage layout, engine hydration, version resolution, command reference.

package/skills/proposit-core/docs/api-usage.md

@@ -0,0 +1,442 @@
+# proposit-core API Reference
+
+## 1. Creating an Argument
+
+```typescript
+import { ArgumentEngine } from "@polintpro/proposit-core"
+
+const engine = new ArgumentEngine({
+    id: "arg-1",
+    version: 0,
+    title: "My Argument",
+    description: "Description",
+})
+```
+
+- Constructor accepts `Omit<TCoreArgument, "checksum">` -- extra fields allowed (`additionalProperties: true` in schema).
+- Optional second parameter: `{ checksumConfig?: TCoreChecksumConfig }`.
+- Retrieve metadata: `engine.getArgument()` returns `TCoreArgument` (with checksum).
+
+## 2. Variable Management
+
+Variables are argument-scoped. A single `VariableManager` is shared across all premises.
+
+```typescript
+// Add
+const { result: variable, changes } = engine.addVariable({
+    id: "v1",
+    argumentId: "arg-1",
+    argumentVersion: 0,
+    symbol: "P",
+})
+
+// Update (rename)
+engine.updateVariable("v1", { symbol: "Q" })
+
+// Remove -- cascades: deletes all referencing expressions across all premises (with operator collapse)
+engine.removeVariable("v1")
+
+// Read
+engine.getVariables() // TCorePropositionalVariable[] (sorted by ID, with checksums)
+```
+
+**Signatures:**
+
+| Method                                           | Returns                                                        |
+| ------------------------------------------------ | -------------------------------------------------------------- |
+| `engine.addVariable(variable)`                   | `TCoreMutationResult<TCorePropositionalVariable>`              |
+| `engine.updateVariable(variableId, { symbol? })` | `TCoreMutationResult<TCorePropositionalVariable \| undefined>` |
+| `engine.removeVariable(variableId)`              | `TCoreMutationResult<TCorePropositionalVariable \| undefined>` |
+| `engine.getVariables()`                          | `TCorePropositionalVariable[]`                                 |
+
+**Throws:** duplicate symbol, duplicate ID, mismatched `argumentId`/`argumentVersion`.
+
+## 3. Premise CRUD
+
+```typescript
+// Create (auto-generated UUID)
+const { result: pm, changes } = engine.createPremise({ title: "Premise 1" })
+
+// Create with explicit ID
+const { result: pm2 } = engine.createPremiseWithId("p-1", {
+    title: "Premise 1",
+})
+
+// Remove
+const { result: removedData } = engine.removePremise("p-1")
+
+// Read
+engine.getPremise("p-1") // PremiseManager | undefined
+engine.hasPremise("p-1") // boolean
+engine.listPremiseIds() // string[] (sorted)
+engine.listPremises() // PremiseManager[] (sorted by ID)
+```
+
+- `extras` is `Record<string, unknown>` -- preserved via `additionalProperties` (e.g. `{ title: "..." }`).
+- First premise created is auto-assigned as conclusion (reflected in changeset `changes.roles`).
+
+**Signatures:**
+
+| Method                                    | Returns                                          |
+| ----------------------------------------- | ------------------------------------------------ |
+| `engine.createPremise(extras?)`           | `TCoreMutationResult<PremiseManager>`            |
+| `engine.createPremiseWithId(id, extras?)` | `TCoreMutationResult<PremiseManager>`            |
+| `engine.removePremise(premiseId)`         | `TCoreMutationResult<TCorePremise \| undefined>` |
+
+## 4. Expression Tree
+
+### Insertion APIs (prefer the top two)
+
+```typescript
+const pm = engine.getPremise("p-1")!
+
+// 1. Append as last child (position auto-computed)
+const { result: expr } = pm.appendExpression(null, {
+    id: "e-root",
+    type: "operator",
+    operator: "implies",
+    argumentId: "arg-1",
+    argumentVersion: 0,
+    parentId: null, // ignored for appendExpression -- parentId comes from first arg
+})
+
+// 2. Insert relative to sibling
+pm.addExpressionRelative("e-sibling", "before", {
+    id: "e-new",
+    type: "variable",
+    variableId: "v1",
+    argumentId: "arg-1",
+    argumentVersion: 0,
+    parentId: "e-root", // ignored -- derived from sibling's parent
+})
+
+// 3. Low-level with explicit position
+pm.addExpression({
+    id: "e-3",
+    type: "variable",
+    variableId: "v1",
+    argumentId: "arg-1",
+    argumentVersion: 0,
+    parentId: "e-root",
+    position: 0,
+})
+```
+
+**Input types:**
+
+- `appendExpression` and `addExpressionRelative`: `TExpressionWithoutPosition` (no `position` or `checksum`).
+- `addExpression`: `TExpressionInput` (no `checksum`, but has `position`).
+
+### Other mutations
+
+```typescript
+// Insert (wraps existing nodes under new operator)
+pm.insertExpression(newOperatorExpr, leftNodeId, rightNodeId)
+
+// Update in-place (restricted swaps: and<->or, implies<->iff)
+pm.updateExpression("e-1", { operator: "or" })
+pm.updateExpression("e-var", { variableId: "v2" })
+pm.updateExpression("e-1", { position: 5 })
+
+// Remove
+pm.removeExpression("e-1", true) // deleteSubtree=true: delete subtree + operator collapse
+pm.removeExpression("e-1", false) // deleteSubtree=false: promote single child into slot
+```
+
+**Signatures:**
+
+| Method                                                         | Returns                                                          |
+| -------------------------------------------------------------- | ---------------------------------------------------------------- |
+| `pm.appendExpression(parentId, expr)`                          | `TCoreMutationResult<TCorePropositionalExpression>`              |
+| `pm.addExpressionRelative(siblingId, "before"\|"after", expr)` | `TCoreMutationResult<TCorePropositionalExpression>`              |
+| `pm.addExpression(expr)`                                       | `TCoreMutationResult<TCorePropositionalExpression>`              |
+| `pm.insertExpression(expr, leftNodeId?, rightNodeId?)`         | `TCoreMutationResult<TCorePropositionalExpression>`              |
+| `pm.updateExpression(id, updates)`                             | `TCoreMutationResult<TCorePropositionalExpression>`              |
+| `pm.removeExpression(id, deleteSubtree)`                       | `TCoreMutationResult<TCorePropositionalExpression \| undefined>` |
+
+**Read methods:**
+
+| Method                             | Returns                                               |
+| ---------------------------------- | ----------------------------------------------------- |
+| `pm.getExpression(id)`             | `TCorePropositionalExpression \| undefined`           |
+| `pm.getExpressions()`              | `TCorePropositionalExpression[]` (sorted by ID)       |
+| `pm.getChildExpressions(parentId)` | `TCorePropositionalExpression[]` (sorted by position) |
+| `pm.getRootExpression()`           | `TCorePropositionalExpression \| undefined`           |
+| `pm.getRootExpressionId()`         | `string \| undefined`                                 |
+
+### Expression type rules
+
+- `implies` and `iff` must be root (`parentId: null`). Cannot be nested.
+- `not`: exactly 1 child. Cannot swap operator (delete and re-create instead).
+- `and`/`or`: 2+ children. Can swap between each other.
+- `implies`/`iff`: exactly 2 children at positions 0 and 1. Can swap between each other.
+- `formula`: transparent unary wrapper (1 child). Equivalent to parentheses.
+
+### Operator collapse (on remove with `deleteSubtree: true`)
+
+After deleting a subtree, `collapseIfNeeded` runs on the parent:
+
+- **0 children left**: parent operator/formula deleted, recurse to grandparent.
+- **1 child left**: parent deleted, surviving child promoted into parent's slot.
+
+## 5. Roles
+
+```typescript
+engine.setConclusionPremise("p-1")
+engine.clearConclusionPremise()
+engine.getConclusionPremise() // PremiseManager | undefined
+engine.listSupportingPremises() // PremiseManager[] -- derived: inference premises not the conclusion
+engine.getRoleState() // TCoreArgumentRoleState: { conclusionPremiseId?: string }
+```
+
+- Supporting premises are **derived**, not explicitly managed. Any inference premise (`implies`/`iff` root) that is not the conclusion is automatically supporting.
+- `setConclusionPremise` and `clearConclusionPremise` return `TCoreMutationResult<TCoreArgumentRoleState>`.
+
+## 6. Evaluation
+
+### Premise-level
+
+```typescript
+const result = pm.evaluate({
+    variables: { v1: true, v2: false, v3: null },
+    rejectedExpressionIds: ["e-5"],
+})
+// result: TCorePremiseEvaluationResult
+// result.rootValue -- TCoreTrivalentValue (true | false | null)
+// result.expressionValues -- Record<string, TCoreTrivalentValue>
+// result.inferenceDiagnostic -- for implies/iff roots
+```
+
+### Argument-level
+
+```typescript
+const result = engine.evaluate({
+    variables: { v1: true, v2: false },
+    rejectedExpressionIds: [],
+})
+
+if (result.ok) {
+    result.isAdmissibleAssignment // TCoreTrivalentValue
+    result.allSupportingPremisesTrue // TCoreTrivalentValue
+    result.conclusionTrue // TCoreTrivalentValue
+    result.isCounterexample // TCoreTrivalentValue
+    result.preservesTruthUnderAssignment // TCoreTrivalentValue
+    result.conclusion // TCorePremiseEvaluationResult
+    result.supportingPremises // TCorePremiseEvaluationResult[]
+    result.constraintPremises // TCorePremiseEvaluationResult[]
+}
+```
+
+**Options:** `engine.evaluate(assignment, { validateFirst?, includeExpressionValues?, includeDiagnostics?, strictUnknownAssignmentKeys? })`
+
+### Validity check
+
+```typescript
+const result = engine.checkValidity({
+    mode: "firstCounterexample", // or "exhaustive"
+    maxVariables: 20,
+    maxAssignmentsChecked: 1_000_000,
+})
+
+if (result.ok) {
+    result.isValid // true | false | undefined (undefined = truncated)
+    result.counterexamples // TCoreCounterexample[]
+    result.checkedVariableIds // string[]
+    result.numAssignmentsChecked
+    result.numAdmissibleAssignments
+    result.truncated // boolean
+}
+```
+
+### Structural validation
+
+```typescript
+const validation = engine.validateEvaluability()
+// validation: TCoreValidationResult { ok: boolean, issues: TCoreValidationIssue[] }
+// Also: pm.validateEvaluability() for premise-level
+```
+
+## 7. Diffing
+
+```typescript
+import {
+    diffArguments,
+    defaultCompareArgument,
+    defaultCompareVariable,
+    defaultComparePremise,
+    defaultCompareExpression,
+} from "@polintpro/proposit-core"
+
+const diff = diffArguments(engineA, engineB, {
+    compareArgument: defaultCompareArgument,
+    compareVariable: defaultCompareVariable,
+    comparePremise: defaultComparePremise,
+    compareExpression: defaultCompareExpression,
+})
+// diff: TCoreArgumentDiff
+// diff.argument -- TCoreEntityFieldDiff<TCoreArgument>
+// diff.variables -- TCoreEntitySetDiff<TCorePropositionalVariable>
+// diff.premises -- TCorePremiseSetDiff (with nested expression diffs)
+// diff.roles -- TCoreRoleDiff
+```
+
+- Standalone function. Pluggable comparators (each receives before/after, returns `TCoreFieldChange[]`).
+- All options optional -- defaults are used when omitted.
+
+## 8. Relationship Analysis
+
+```typescript
+import {
+    analyzePremiseRelationships,
+    buildPremiseProfile,
+} from "@polintpro/proposit-core"
+
+// Analyze how all premises relate to a focused premise
+const analysis = analyzePremiseRelationships(engine, "p-conclusion")
+// analysis: TCorePremiseRelationshipAnalysis
+// analysis.focusedPremiseId
+// analysis.premises -- TCorePremiseRelationResult[] per other premise
+//   each: { premiseId, relationship, variableDetails, transitive }
+//   relationship: "supporting" | "contradicting" | "restricting" | "downstream" | "unrelated"
+
+// Build a variable profile for a single premise
+const profile = buildPremiseProfile(pm)
+// profile: TCorePremiseProfile
+// profile.premiseId
+// profile.appearances -- TCoreVariableAppearance[]
+```
+
+Both are standalone functions.
+
+## 9. Formula Parsing
+
+```typescript
+import { parseFormula } from "@polintpro/proposit-core"
+import type { FormulaAST } from "@polintpro/proposit-core"
+
+const ast: FormulaAST = parseFormula("P -> (Q & R)")
+```
+
+**Supported syntax:** `&&`/`∧` (AND), `||`/`∨` (OR), `!`/`¬` (NOT), `->`/`→` (implies), `<->`/`↔` (iff), parentheses.
+
+**AST types:**
+
+```typescript
+type FormulaAST =
+    | { type: "variable"; name: string }
+    | { type: "not"; operand: FormulaAST }
+    | { type: "and"; operands: FormulaAST[] }
+    | { type: "or"; operands: FormulaAST[] }
+    | { type: "implies"; left: FormulaAST; right: FormulaAST }
+    | { type: "iff"; left: FormulaAST; right: FormulaAST }
+```
+
+## 10. Mutation Result Pattern
+
+Every mutating method returns `TCoreMutationResult<T>`:
+
+```typescript
+interface TCoreMutationResult<T> {
+    result: T
+    changes: TCoreChangeset
+}
+
+interface TCoreChangeset {
+    expressions?: TCoreEntityChanges<TCorePropositionalExpression>
+    variables?: TCoreEntityChanges<TCorePropositionalVariable>
+    premises?: TCoreEntityChanges<TCorePremise>
+    roles?: TCoreArgumentRoleState // present only when roles changed
+    argument?: TCoreArgument // present only when argument changed
+}
+
+interface TCoreEntityChanges<T> {
+    added: T[]
+    modified: T[]
+    removed: T[]
+}
+```
+
+**Usage pattern:**
+
+```typescript
+const { result: premise, changes } = engine.createPremise()
+changes.premises?.added // newly added premise
+changes.roles // new role state (if changed, e.g. auto-conclusion)
+changes.expressions?.removed // cascaded removals (e.g. from removeVariable)
+```
+
+## 11. Serialization
+
+### PremiseManager
+
+| Method                                     | Returns                                               | Description                                       |
+| ------------------------------------------ | ----------------------------------------------------- | ------------------------------------------------- |
+| `pm.toData()`                              | `TCorePremise`                                        | Serializable snapshot (only referenced variables) |
+| `pm.toDisplayString()`                     | `string`                                              | Human-readable formula (`P -> (Q /\ R)`)          |
+| `pm.isInference()`                         | `boolean`                                             | Root is `implies` or `iff`                        |
+| `pm.isConstraint()`                        | `boolean`                                             | Not an inference (inverse of above)               |
+| `pm.checksum()`                            | `string`                                              | Premise-level checksum (lazy)                     |
+| `pm.getId()`                               | `string`                                              | Premise ID                                        |
+| `pm.getExtras()`                           | `Record<string, unknown>`                             | Extra fields (e.g. title)                         |
+| `pm.setExtras(extras)`                     | `TCoreMutationResult<Record<string, unknown>>`        | Replace extras                                    |
+| `pm.getReferencedVariableIds()`            | `Set<string>`                                         | Variable IDs used in expressions                  |
+| `pm.getVariables()`                        | `TCorePropositionalVariable[]`                        | All argument-level variables                      |
+| `pm.deleteExpressionsUsingVariable(varId)` | `TCoreMutationResult<TCorePropositionalExpression[]>` | Cascade delete                                    |
+
+### ArgumentEngine
+
+| Method                                | Returns                           | Description                     |
+| ------------------------------------- | --------------------------------- | ------------------------------- |
+| `engine.toData()`                     | `TCoreArgumentEngineData`         | Full state snapshot             |
+| `engine.exportState()`                | `TCoreArgumentEngineData`         | Alias for `toData()`            |
+| `engine.getArgument()`                | `TCoreArgument`                   | Argument metadata with checksum |
+| `engine.checksum()`                   | `string`                          | Argument-level checksum (lazy)  |
+| `engine.collectReferencedVariables()` | `{ variableIds, byId, bySymbol }` | Cross-premise variable index    |
+
+## 12. Checksum Utilities
+
+```typescript
+import {
+    computeHash,
+    canonicalSerialize,
+    entityChecksum,
+    DEFAULT_CHECKSUM_CONFIG,
+    createChecksumConfig,
+} from "@polintpro/proposit-core"
+
+// Low-level hash
+const hash = computeHash("input string")
+
+// Serialize object to canonical deterministic JSON (sorted keys)
+const serialized = canonicalSerialize({ a: 1, b: 2 })
+
+// Entity checksum
+const checksum = entityChecksum(entity, new Set(["id", "symbol"]))
+
+// Custom config
+const config = createChecksumConfig({
+    expressionFields: new Set([
+        "id",
+        "type",
+        "operator",
+        "variableId",
+        "parentId",
+        "position",
+    ]),
+    variableFields: new Set(["id", "symbol"]),
+})
+const engine = new ArgumentEngine(arg, { checksumConfig: config })
+```
+
+## 13. Position Utilities
+
+```typescript
+import {
+    POSITION_MIN, // 0
+    POSITION_MAX, // Number.MAX_SAFE_INTEGER
+    POSITION_INITIAL, // midpoint(POSITION_MIN, POSITION_MAX)
+    midpoint, // (a, b) => a + (b - a) / 2
+} from "@polintpro/proposit-core"
+```
+
+Positions are opaque numbers. Only relative ordering matters. The `appendExpression` and `addExpressionRelative` APIs compute positions automatically -- prefer those over manual positioning.