KindScript Lattice & Algebra Visualizations

Visual guide to the mathematical structures underlying architectural enforcement

Contents 1. What Is a Lattice? 2. The CodeLoc Containment Lattice 3. The Meet Operation 4. What Is a Powerset Lattice? 5. CodeLoc Sets & Canonicalization 6. Set Operations: Union, Intersect, Exclude 7. CarrierExpr as Expression Tree 8. Oxide vs. KindScript: Flat vs. Hierarchical 9. The Full Pipeline Flow

1. What Is a Lattice?

A lattice is a partially ordered set where every pair of elements has a meet (greatest lower bound) and a join (least upper bound).

top a b bot join(a,b) = top meet(a,b) = bot a ≤ top b ≤ top bot ≤ a bot ≤ b

The Hasse diagram shows the ordering: lines go from lower to higher. Every pair has a unique meet (go down to where they converge) and join (go up to where they converge).

2. The CodeLoc Containment Lattice

KindScript's CodeLoc forms a three-level containment lattice. Higher = more general (contains more). Lower = more specific (contained by more).

DIRECTORY FILE DECLARATION dir: /src/domain file: /src/domain/order.ts ... file: /src/domain/event.ts decl: order.ts#Order decl: order.ts#LineItem decl: event.ts#Event decl: event.ts#Emit subsumes(dir, file) = true    subsumes(file, decl) = true    subsumes(dir, decl) = true
Directory (coarsest)
File
Declaration (finest)
Reading the diagram: Every line means "the upper node subsumes (contains) the lower node." subsumes(dir('/src/domain'), declLoc('/src/domain/order.ts', 'Order')) = true — the directory transitively contains the declaration.

3. The Meet Operation

meet(a, b) returns the greatest lower bound — the most specific location contained by both. Returns null if the locations are incomparable (different branches of the tree).

meet(dir, file) = file

/src/domain /src/domain/order.ts ← GLB file is under dir, so file is the meet

meet(file_A, file_B) = null

order.ts event.ts × null incomparable — no GLB exists

meet(file, decl) = decl

file: order.ts decl: order.ts#Order ← GLB same file, so decl is the meet

meet(dir, decl) = decl

/src/domain (file is implicit) decl: domain/order.ts#Order ← GLB transitive: dir subsumes decl

4. What Is a Powerset Lattice?

Take a set S = {a, b, c}. The powerset is all possible subsets, ordered by ⊆. This forms a lattice where meet = ∩ and join = ∪.

{a, b, c} {a, b} {a, c} {b, c} {a} {b} {c} ∅ ← top (everything) ← 2-element subsets ← singletons ← bottom (nothing) meet({a,b}, {b,c}) = {a,b} ∩ {b,c} = {b} join({a}, {c}) = {a} ∪ {c} = {a,c}
Oxide uses this directly. Regions are elements of P(Loans) — the powerset of all loans. Each loan {shrd x} or {uniq y.0} is an atom. No loan subsumes another, so the powerset is naturally canonical. KindScript's version is more complex because its atoms (CodeLocs) have internal structure.

5. CodeLoc Sets & Canonicalization

Because CodeLocs have containment (a directory subsumes its files), sets of CodeLocs can contain redundancy. canonicalize() removes locations that are subsumed by coarser ones already in the set.

Canonicalization: Remove Subsumed Elements

Input set

dir /src/domain
file /src/domain/order.ts
decl /src/domain/order.ts#Order
file /src/infra/db.ts
→
canonicalize

Canonical form

dir /src/domain
file /src/domain/order.ts
decl order.ts#Order
file /src/infra/db.ts

The directory /src/domain already claims everything under it —
the file and declaration are redundant, so they're removed.

Why this matters: Without canonicalization, two "equal" sets could look different: [dir('/src')] vs [dir('/src'), file('/src/a.ts')]. Canonicalization gives a unique representative for each equivalence class. This is why KindScript's lattice is a quotient of a powerset, not a pure powerset.

6. Set Operations: Union, Intersect, Exclude

unionLocs — Merge + Canonicalize

Set A

file /src/domain/order.ts
file /src/domain/event.ts
union

Set B

dir /src/domain
=

Result

dir /src/domain
file order.ts
file event.ts

The directory subsumes both files after merge, so canonicalization removes them.

intersectLocs — Pairwise Meet + Canonicalize

Set A

dir /src/domain
intersect

Set B

decl domain/order.ts#Order
file /src/infra/db.ts
=

Result

decl domain/order.ts#Order

meet(dir, decl) = decl (dir contains the decl's file) — meet(dir, infra/db.ts) = null (different tree)

excludeLocs — Subsumption-Aware Difference

Base

file /src/a.ts
file /src/b.ts
file /src/c.ts
exclude

Excluded

file /src/b.ts
=

Result

file /src/a.ts
file /src/b.ts
file /src/c.ts

Each base location is checked: is it subsumed by any excluded location? If yes, it's dropped.

7. CarrierExpr as Expression Tree

A CarrierExpr is an algebraic expression that describes where code lives. The resolver evaluates it to a concrete CodeLoc[] set.

"All service files except deprecated ones, plus the core package"

union exclude atom: pkg:@myorg/core atom: glob:**/*.service.ts atom: tag:@deprecated base excluded children[0] children[1] ↓ resolves to [a.service.ts, b.service.ts, old.service.ts] ↓ resolves to [old.service.ts] ↓ resolves to [packages/core/index.ts, ...] final: [a.service.ts, b.service.ts, packages/core/index.ts, ...]
The carrier algebra is KindScript's unique contribution. Oxide doesn't need this — memory has one coordinate system (place expressions). Architecture needs multiple coordinate systems (path, glob, tag, package) composed algebraically.

8. Oxide vs. KindScript: Flat vs. Hierarchical

The structural difference: Oxide's atoms (loans) are flat — no loan subsumes another. KindScript's atoms (CodeLocs) are hierarchical — directories subsume files subsume declarations.

Oxide: Flat Powerset

shrd x uniq y.0 shrd z uniq w All atoms are peers — no subsumption Region = any subset: {shrd x, uniq y.0} Union = plain set union Intersection = plain set intersection Already canonical — no redundancy possible

KindScript: Hierarchical

dir: /src/domain file: order.ts file: event.ts #Order #LineItem Atoms have structure — dir ⊒ file ⊒ decl Union needs canonicalize() to remove redundancy from subsumption
PropertyOxideKindScript
Atom structureFlat (no loan subsumes another)Hierarchical (dir ⊒ file ⊒ decl)
Set unionA ∪ Bcanonicalize([...A, ...B])
Set intersectA ∩ Bpairwise meet + canonicalize
Canonical?Always (flat atoms)Requires canonicalize()
Boolean algebra?Yes (complete)No (canonicalization breaks complements)
Lattice typePowerset latticeQuotient of powerset

9. The Full Pipeline Flow

How the algebraic structures flow through KindScript's five-stage pipeline.

SCAN discover files PARSE build CarrierExpr BIND resolve & bind EXTRACT build dep graph CHECK enforce constraints CarrierExpr alive × dies here CodeLoc[] alive — flows to end produces: file list tagged decls produces: ArchNode tree CarrierExpr map resolves & produces: CodeLoc[] sets Binding[] BoundArchitecture (carrier discarded) queries CodeLoc via: filesOf() hasDeclarationLocs() queries CodeLoc via: claims() claimOn() Form Independence: The checker never sees CarrierExpr. It only sees CodeLoc[] via BoundNodeView.
This is the Oxide parallel: Oxide's checker also never sees how regions were computed — it only sees concrete loan sets. In both systems, the expression layer (CarrierExpr / implicit region inference) is resolved before checking begins. Safety invariants are checked against resolved sets, not against the expressions that produced them.

KindScript Lattice Visualizations — Generated 2026-02-16
Source: src/domain/physical/code-loc.ts · src/application/pipeline/carrier/carrier-expr.ts · src/application/pipeline/carrier/loc-set-ops.ts