quilt-spreadsheet 0.1.0__py3-none-any.whl

quilt_spreadsheet/__init__.py

@@ -0,0 +1,50 @@
+"""
+quilt-spreadsheet — the IDE substrate.
+
+A spreadsheet-as-IDE where:
+  - front-end looks like a spreadsheet (rows x cols)
+  - each cell is a runnable program with hooks
+  - double-entry bookkeeping tracks every pull/push pair
+  - per-cell color namespaces (semantic heterogeneity is OK)
+  - backend porting handles scale/unit conversions
+  - distributed clocks allow skew; time-between-events converges
+
+This is the SUBSTRATE TRANSITION from quilt-egg (a single cell) to
+quilt-spreadsheet (a grid of cells with hooks).
+"""
+
+from .clock import (
+    CellClock, DistributedClock, get_default_clock, reset_default_clock
+)
+from .ledger import (
+    LedgerEntry, Ledger, get_default_ledger, reset_default_ledger
+)
+from .color import (
+    ColorNamespace, same_canonical, labels_matter
+)
+from .backend import (
+    Backend, get_default_backend, reset_default_backend,
+    convert, REGISTRY,
+)
+from .perception import Perception
+from .cell import (
+    SheetCell, DOCTRINE_AXIOMS, ACTION_AXIOMS,
+    register_cell, reset_registry, get_cell, all_cells,
+)
+from .grid import QuiltSpreadsheet, place_cell
+
+__all__ = [
+    "CellClock", "DistributedClock",
+    "get_default_clock", "reset_default_clock",
+    "LedgerEntry", "Ledger",
+    "get_default_ledger", "reset_default_ledger",
+    "ColorNamespace", "same_canonical", "labels_matter",
+    "Backend", "get_default_backend", "reset_default_backend",
+    "convert", "REGISTRY",
+    "Perception",
+    "SheetCell", "DOCTRINE_AXIOMS", "ACTION_AXIOMS",
+    "register_cell", "reset_registry", "get_cell", "all_cells",
+    "QuiltSpreadsheet", "place_cell",
+]
+
+__version__ = "0.1.0"

quilt_spreadsheet/__main__.py

@@ -0,0 +1,71 @@
+"""
+__main__.py — `python -m quilt_spreadsheet` runs a demo spreadsheet.
+"""
+
+import argparse
+import sys
+
+from .grid import QuiltSpreadsheet, reset_all
+
+
+def demo_spreadsheet():
+    """Build a 4×4 substrate with 4 programs that respond to pulls."""
+    reset_all()
+    sheet = QuiltSpreadsheet(rows=4, cols=4, name="canonical_demo")
+
+    def adder(*, source, hook, value):
+        # Cell that adds 1 to whatever is pulled
+        return (value or 0) + 1
+
+    def doubler(*, source, hook, value):
+        return (value or 0) * 2
+
+    def labeler(*, source, hook, value):
+        # Cell that translates a label
+        return "doubled" if hook == "double" else "added"
+
+    def tally(*, source, hook, value):
+        # Counts how many times it has been pulled
+        return f"tally:{value}"
+
+    # Place four programs
+    sheet.place_cell(0, 0, adder)
+    sheet.place_cell(0, 1, doubler)
+    sheet.place_cell(1, 0, labeler)
+    sheet.place_cell(1, 1, tally)
+
+    # Wire a workflow: cell at (2, 2) pulls adder, then doubler
+    def workflow(*, source, hook, value):
+        return f"workflow[{hook}]={value}"
+
+    sheet.place_cell(2, 2, workflow)
+    # Pull adder
+    sheet.pull(2, 2, 0, 0, hook="step1", value=5)
+    # Pull doubler — note this uses ledger.record_pair
+    sheet.pull(0, 0, 0, 1, hook="double", value=5)
+
+    print(sheet.render())
+    print()
+    print("Summary:")
+    for k, v in sheet.summary().items():
+        print(f"  {k}: {v}")
+    print()
+    print("Pulls and pushes recorded in the ledger (double-entry pairs).")
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        prog="quilt_spreadsheet",
+        description="The Quilt spreadsheet IDE substrate — double-entry bookkeeping, distributed clocks, per-cell color namespaces, backend porting.",
+    )
+    parser.add_argument("--rows", type=int, default=4, help="Spreadsheet rows (default: 4)")
+    parser.add_argument("--cols", type=int, default=4, help="Spreadsheet cols (default: 4)")
+    parser.add_argument("--demo", choices=["canonical"], default="canonical", help="Demo to run")
+    args = parser.parse_args()
+    if args.demo == "canonical":
+        demo_spreadsheet()
+        return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

quilt_spreadsheet/backend.py

@@ -0,0 +1,183 @@
+"""
+backend.py — the porting, conversion, gating, and snapping layer.
+
+Casey: "the true backend is the actual porting and conversions. one cell
+might be using a different scale than another but if the backend can convert
+so their equal exchange for their applications, it doesn't matter. the
+backend can gate variables or convert approximations to snaps but the time
+is in the same units on both sides."
+
+This is the polyformalism-port layer at the substrate level. Different
+cells may use:
+  - different scales (celsius vs fahrenheit)
+  - different units (ns vs ms)
+  - different precision (continuous vs snapped)
+  - different visibility (some variables are gated)
+
+The backend DOES NOT enforce agreement. The backend PROVIDES porting
+for when cells need to exchange data.
+"""
+
+from typing import Any, Tuple
+import math
+
+
+#: The canonical conversions registry — extensible.
+#: Each entry: name -> callable(value, from_unit, to_unit)
+#: Time is preserved in the SAME units on both sides (per Casey).
+REGISTRY = {}
+
+
+def convert(name: str):
+    """Decorator to register a backend conversion."""
+    def deco(fn):
+        REGISTRY[name] = fn
+        return fn
+    return deco
+
+
+@convert("temperature")
+def convert_temperature(value: float, from_unit: str, to_unit: str) -> float:
+    """Convert temperature scales."""
+    if from_unit == to_unit:
+        return value
+    if from_unit == 'celsius' and to_unit == 'fahrenheit':
+        return value * 9/5 + 32
+    if from_unit == 'fahrenheit' and to_unit == 'celsius':
+        return (value - 32) * 5/9
+    if from_unit == 'celsius' and to_unit == 'kelvin':
+        return value + 273.15
+    raise ValueError(f"unsupported temperature conversion: {from_unit} -> {to_unit}")
+
+
+@convert("time")
+def convert_time(value: float, from_unit: str, to_unit: str) -> float:
+    """Time is preserved in the SAME units on both sides (per Casey).
+
+    Per Casey's directive: 'time is in the same units on both sides'.
+    This converter refuses to convert across units — it normalizes to
+    nanoseconds (canonical) and back.
+
+    Use ms and ns. The substrate does not negotiate time across calendars.
+    """
+    if from_unit == to_unit:
+        return value
+    if from_unit not in ('ns', 'ms', 's') or to_unit not in ('ns', 'ms', 's'):
+        raise ValueError(f"time must be in same units: {from_unit} vs {to_unit}")
+    # Casey: convert for compatibility but it's a unit-preserving op
+    if from_unit == 'ns' and to_unit == 'ms':
+        return value / 1e6
+    if from_unit == 'ms' and to_unit == 'ns':
+        return value * 1e6
+    if from_unit == 'ns' and to_unit == 's':
+        return value / 1e9
+    if from_unit == 's' and to_unit == 'ns':
+        return value * 1e9
+    return value
+
+
+@convert("distance")
+def convert_distance(value: float, from_unit: str, to_unit: str) -> float:
+    """Distance scaling."""
+    if from_unit == to_unit:
+        return value
+    if from_unit == 'm' and to_unit == 'cm':
+        return value * 100
+    if from_unit == 'cm' and to_unit == 'm':
+        return value / 100
+    raise ValueError(f"unsupported distance conversion: {from_unit} -> {to_unit}")
+
+
+@convert("ratio")
+def convert_ratio(value: float, from_unit: str, to_unit: str) -> float:
+    """Ratios are unitless — convert between percent, decimal, ppm."""
+    if from_unit == to_unit:
+        return value
+    if from_unit == 'decimal' and to_unit == 'percent':
+        return value * 100
+    if from_unit == 'percent' and to_unit == 'decimal':
+        return value / 100
+    if from_unit == 'ppm' and to_unit == 'decimal':
+        return value / 1e6
+    raise ValueError(f"unsupported ratio conversion: {from_unit} -> {to_unit}")
+
+
+class Backend:
+    """The porting backend — applied at cell boundaries.
+
+    Functions: convert, gate, snap, time-aware porting.
+    """
+
+    def __init__(self):
+        self.conversions_run: int = 0
+
+    def port(self, value: Any, from_unit: str, to_unit: str,
+             domain: str = "ratio") -> Any:
+        """Port a value across scales/units in the same domain.
+
+        Default domain is 'ratio' (unitless). For physical conversions
+        pass domain='temperature' or 'distance'.
+        """
+        if from_unit == to_unit:
+            return value
+        if domain not in REGISTRY:
+            raise ValueError(f"unknown backend domain: {domain}")
+        self.conversions_run += 1
+        return REGISTRY[domain](value, from_unit, to_unit)
+
+    def gate(self, value: Any, predicate) -> Any:
+        """Backend 'gate' — release a value only if predicate is satisfied.
+
+        Casey: 'the backend can gate variables or convert approximations
+        to snaps'. The gate is controlled release/transformation.
+
+        Returns None if predicate fails. The cell receives None and can
+        decide what to do (default action: skip).
+        """
+        if not predicate(value):
+            return None
+        return value
+
+    def gate_below(self, value: float, threshold: float) -> Any:
+        """Common gate: block values below threshold."""
+        if value < threshold:
+            return None
+        return value
+
+    def snap(self, value: float, granularity: float) -> float:
+        """Approximation snap — snap to discrete grid.
+
+        Casey: 'the backend can gate variables or convert approximations
+        to snaps'. A snap rounds the value to the nearest multiple of
+        granularity.
+
+        e.g. snap(3.7, 0.5) = 3.5 (or 4.0, depending on tie-break)
+        """
+        if granularity <= 0:
+            return value
+        return round(value / granularity) * granularity
+
+    def port_time(self, value: float, from_unit: str, to_unit: str) -> float:
+        """Time porting — preserves same units on both sides (per Casey)."""
+        return REGISTRY["time"](value, from_unit, to_unit)
+
+    def stats(self) -> dict:
+        return {
+            "conversions_run": self.conversions_run,
+            "available_conversions": sorted(REGISTRY.keys()),
+        }
+
+
+_default_backend = None
+
+
+def get_default_backend() -> Backend:
+    global _default_backend
+    if _default_backend is None:
+        _default_backend = Backend()
+    return _default_backend
+
+
+def reset_default_backend() -> None:
+    global _default_backend
+    _default_backend = None

quilt_spreadsheet/cell.py

@@ -0,0 +1,231 @@
+"""
+cell.py — the SheetCell.
+
+A SheetCell is:
+  - Addressable by (row, col)
+  - Has a program (a Python callable — "a python program might sit in a cell
+    as a shell command ready to run")
+  - Has DNA (alignment seed)
+  - Has hooks to other cells (pull/push wake-up)
+  - Has its own color/label namespace
+  - Has its own perception (sorts the spreadsheet around it)
+
+Casey: "there's no central program within the cell's instance, it's just
+a program running so if [pulls happen], it runs."
+
+The cell has NO main(). The cell's program runs ONLY when it is woken
+(by pull or by push). The cell's program has the signature:
+    program(*, source, hook, value) -> response_value
+"""
+
+from typing import Tuple, Optional, Callable, Dict, Any, List
+import uuid
+
+from .color import ColorNamespace
+from .perception import Perception
+from .clock import get_default_clock
+from .ledger import get_default_ledger
+from .backend import get_default_backend
+
+
+#: The 5 bedrock doctrine axioms (substrate walker canon line)
+DOCTRINE_AXIOMS = frozenset({
+    'cells_are_scars',
+    'witness_log_is_prediction',
+    'oracle_is_heard',
+    'canon_gate_is_chord',
+    'substrate_quantum',
+})
+
+#: The action axioms — what a cell CAN do
+ACTION_AXIOMS = frozenset({
+    'pull',        # pull from another cell
+    'push',        # push to another cell
+    'witness',     # record to the witness log
+    'perceive',    # sort the spreadsheet around it
+    'label',       # assign a color label
+    'convert',     # port values through backend
+    'snap',        # approximate-snap values
+})
+
+
+class SheetCell:
+    """A cell in the Quilt spreadsheet substrate.
+
+    No main(). The cell RUNS when pulled. The cell RESPONDS when pushed.
+    Between events, the cell is dormant.
+    """
+
+    NUM_DIALS = 16
+
+    __slots__ = (
+        'row', 'col', 'rank', 'program', 'axioms',
+        'dials', 'color', 'perception', 'witness_log',
+        'pulls', 'pushes', 'hooks_named',
+        'awake_count', 'last_event_ns',
+    )
+
+    def __init__(
+        self,
+        row: int,
+        col: int,
+        program: Callable,
+        axioms: Optional[frozenset] = None,
+    ):
+        if not callable(program):
+            raise TypeError(f"program must be callable, got {type(program)}")
+        if axioms is None:
+            axioms = frozenset(DOCTRINE_AXIOMS | ACTION_AXIOMS)
+        self.row = row
+        self.col = col
+        self.rank: Tuple[int, int] = (row, col)
+        self.program = program
+        self.axioms = axioms
+        self.dials = [0.0] * self.NUM_DIALS
+        self.color = ColorNamespace(self.rank)
+        self.perception = Perception(self.rank)
+        self.witness_log: List[dict] = []
+        self.pulls: Dict[Tuple[int, int], List[str]] = {}  # source -> [hooks]
+        self.pushes: Dict[Tuple[int, int], List[str]] = {}  # target -> [hooks]
+        self.hooks_named: Dict[str, Any] = {}  # named hooks -> last known values
+        self.awake_count: int = 0
+        self.last_event_ns: int = 0
+
+    def permits(self, action: str) -> bool:
+        return action in self.axioms
+
+    def label(self, label: str, canonical_value: Any) -> None:
+        """Assign a private color label to a canonical state."""
+        if not self.permits('label'):
+            return
+        self.color.assign(label, canonical_value)
+
+    def ingest_observation(self, item: dict) -> None:
+        """Add a raw observation to this cell's perception."""
+        if not self.permits('perceive'):
+            return
+        self.perception.ingest([item])
+
+    def on_pull(
+        self,
+        source: Tuple[int, int],
+        hook: str,
+        value: Any = None,
+        timestamp_ns: int = 0,
+    ) -> dict:
+        """Wake the cell — a pull came in.
+
+        The cell RUNS its program with the pull as input.
+        Returns the cell's response (the push).
+        """
+        clock = get_default_clock()
+        ledger = get_default_ledger()
+        ts = clock.tick(self.rank)
+        if timestamp_ns == 0:
+            timestamp_ns = ts
+        # Record the pull on the ledger
+        pull_entry = ledger.record_pull(
+            source=source,
+            target=self.rank,
+            hook=hook,
+            value=value,
+            timestamp_ns=timestamp_ns,
+        )
+        # Run the program (the cell has no main — it runs here)
+        try:
+            if not self.permits('witness'):
+                response = None
+            else:
+                response = self.program(
+                    source=source,
+                    hook=hook,
+                    value=value,
+                )
+        except Exception as e:
+            response = {"_error": str(e), "_hook": hook, "_source": source}
+        # Record the witness
+        self.witness_log.append({
+            'event': 'pull',
+            'source': source,
+            'hook': hook,
+            'value': value,
+            'response': response,
+            'timestamp_ns': timestamp_ns,
+        })
+        self.awake_count += 1
+        self.last_event_ns = timestamp_ns
+        # Track pair sync between cells
+        clock.track_pair_sync(source, self.rank)
+        # Record push on ledger (paired with the pull)
+        if response is not None:
+            ledger.record_push(
+                source=self.rank,
+                target=source,
+                hook=hook,
+                value=response,
+                timestamp_ns=ts,
+                pair_id=pull_entry.pair_id,
+            )
+            self.pushes.setdefault(source, []).append(hook)
+        if source not in self.pulls:
+            self.pulls[source] = []
+        self.pulls[source].append(hook)
+        return {
+            'response': response,
+            'pair_id': pull_entry.pair_id,
+            'timestamp_ns': ts,
+            'cell': self.rank,
+        }
+
+    def pull_from(
+        self,
+        target: Tuple[int, int],
+        hook: str,
+        value: Any = None,
+    ) -> dict:
+        """Pull from another cell. The target wakes up via on_pull."""
+        clock = get_default_clock()
+        ts = clock.tick(self.rank)
+        # Find the target
+        target_cell = _find_cell_global(target)
+        if target_cell is None:
+            return {'error': 'target cell not found', 'target': target}
+        # Wake the target
+        result = target_cell.on_pull(
+            source=self.rank,
+            hook=hook,
+            value=value,
+            timestamp_ns=ts,
+        )
+        # Track sync
+        clock.track_pair_sync(self.rank, target)
+        return result
+
+    def __repr__(self):
+        awake = 'awake' if self.awake_count > 0 else 'dormant'
+        return (f"SheetCell(rank={self.rank}, axioms={len(self.axioms)}, "
+                f"awake={self.awake_count}, status={awake})")
+
+
+# A module-level cell registry for the spreadsheet substrate
+_cell_registry: Dict[Tuple[int, int], SheetCell] = {}
+
+
+def register_cell(cell: SheetCell) -> None:
+    _cell_registry[cell.rank] = cell
+
+
+def _find_cell_global(rank: Tuple[int, int]) -> Optional[SheetCell]:
+    return _cell_registry.get(rank)
+
+
+def reset_registry() -> None:
+    _cell_registry.clear()
+
+
+def get_cell(rank: Tuple[int, int]) -> Optional[SheetCell]:
+    return _cell_registry.get(rank)
+
+
+def all_cells() -> List[SheetCell]:
+    return list(_cell_registry.values())

quilt_spreadsheet/clock.py

@@ -0,0 +1,130 @@
+"""
+clock.py — distributed clocks with skew tolerance.
+
+Each cell has its own clock. Clocks may disagree. The substrate does NOT
+require clocks to agree. The substrate DOES require that the time between
+events be measurable.
+
+Casey: "even if their clocks don't agree, the time between events extrapolates
+the agreement with more and more confidence the longer they are in sync."
+
+This is the load-bearing insight: clock synchronization is EMERGENT, not
+required. Each cell's clock is private. The substrate walker tracks:
+  - event timestamps (relative to the cell's t0)
+  - delta between events (the time between events)
+  - confidence score (rises the longer two cells have shared events)
+"""
+
+import time
+from typing import Dict, Tuple, Optional
+
+
+class CellClock:
+    """A single cell's clock. Starts at cell's birth (t0)."""
+
+    __slots__ = ('t0', 'last_event_ns', 'event_count')
+
+    def __init__(self):
+        self.t0: Optional[int] = None
+        self.last_event_ns: Optional[int] = None
+        self.event_count: int = 0
+
+    def tick(self) -> int:
+        """Advance the clock. Returns the cell-local time in nanoseconds."""
+        if self.t0 is None:
+            self.t0 = time.monotonic_ns()
+        now = time.monotonic_ns()
+        self.last_event_ns = now
+        self.event_count += 1
+        return now - self.t0
+
+
+class DistributedClock:
+    """A coordinator of cell clocks. Skew is allowed. Convergence is emergent."""
+
+    def __init__(self):
+        self._clocks: Dict[Tuple[int, int], CellClock] = {}
+        # Pairwise confidence: tracks how long two cells have been in sync
+        # {(a, b): confidence_score}, where confidence rises the longer
+        # the pair has shared events.
+        self._pairwise_time: Dict[Tuple, int] = {}
+        self._pairwise_event_count: Dict[Tuple, int] = {}
+
+    def tick(self, cell_rank: Tuple[int, int]) -> int:
+        """Tick the named cell's clock. Returns cell-local time in ns."""
+        if cell_rank not in self._clocks:
+            self._clocks[cell_rank] = CellClock()
+        return self._clocks[cell_rank].tick()
+
+    def cell_local_time(self, cell_rank: Tuple[int, int]) -> int:
+        """Read the cell-local time without ticking."""
+        clk = self._clocks.get(cell_rank)
+        if clk is None or clk.t0 is None:
+            return 0
+        return time.monotonic_ns() - clk.t0
+
+    def time_between_events(self, ts_a: int, ts_b: int) -> int:
+        """The time between two events.
+
+        Casey: "the time between events extrapolates the agreement"
+        The DELTA is the substrate's measurement. Clocks can disagree
+        about absolute time; they cannot disagree about deltas (if events
+        are time-stamped close enough).
+
+        Returns absolute value so order doesn't matter.
+        """
+        return abs(ts_b - ts_a)
+
+    def track_pair_sync(self, cell_a: Tuple[int, int], cell_b: Tuple[int, int]) -> None:
+        """Record that two cells have shared another event.
+
+        Every shared event raises the pairwise confidence. The longer
+        cells are in sync, the more confident we are that time-between-
+        events extrapolates.
+        """
+        key = tuple(sorted((cell_a, cell_b)))
+        self._pairwise_time[key] = self._pairwise_time.get(key, 0) + 1
+        self._pairwise_event_count[key] = self._pairwise_event_count.get(key, 0) + 1
+
+    def pair_confidence(self, cell_a: Tuple[int, int], cell_b: Tuple[int, int]) -> float:
+        """Confidence score for the time-between-events agreement.
+
+        Confidence rises as the number of shared events rises.
+        Capped at [0, 1].
+        """
+        key = tuple(sorted((cell_a, cell_b)))
+        count = self._pairwise_event_count.get(key, 0)
+        # asymptotic: confidence = 1 - 1/(count+1)
+        if count == 0:
+            return 0.0
+        return min(1.0, 1.0 - 1.0 / (count + 1))
+
+    def skew_estimate(self, cell_a: Tuple[int, int], cell_b: Tuple[int, int]) -> int:
+        """Estimate the clock skew between two cells.
+
+        Skew is computed by averaging per-event deltas — but we're clocking
+        each cell independently, so skew emerges as the difference in
+        'cell-local time' at the same wall moment.
+
+        Returns estimated skew in nanoseconds. Positive = B's clock is ahead.
+        """
+        local_a = self.cell_local_time(cell_a)
+        local_b = self.cell_local_time(cell_b)
+        return local_b - local_a
+
+
+# A module-level singleton — the substrate uses one clock
+_default_clock = None
+
+
+def get_default_clock() -> DistributedClock:
+    global _default_clock
+    if _default_clock is None:
+        _default_clock = DistributedClock()
+    return _default_clock
+
+
+def reset_default_clock() -> None:
+    """Reset for testing."""
+    global _default_clock
+    _default_clock = None

quilt_spreadsheet/color.py

@@ -0,0 +1,90 @@
+"""
+color.py — per-cell local color/label namespaces.
+
+Casey: "if one's red is the other's blue and they think they are talking
+about the same thing but they are objectively not. it still doesn't matter
+if their logics agree for their specific cells application."
+
+This is the substrate's TOLERANCE for semantic heterogeneity. Each cell
+has its own private color/label space. The substrate does NOT enforce
+a global "red = blue = hot" naming convention. The substrate records
+the labels used and the logic state, and it lets the application's
+LOGIC (not the names) determine whether two cells agree.
+
+In practice:
+  - each cell has a ColorNamespace
+  - when a cell labels something "red", it records its own private
+    red->canonical mapping
+  - the substrate's porting backend uses the CANONICAL value, not the label
+  - the cell can re-label "red" to "critical" without coordinating
+"""
+
+from typing import Dict, Tuple, Optional, Any
+
+
+class ColorNamespace:
+    """A single cell's private color/label space.
+
+    Each cell sees the world through its OWN labels. Two cells can call the
+    same observation different things and still communicate correctly —
+    because the substrate's porting/backend handles the canonical
+    translation.
+    """
+
+    __slots__ = ('owner', '_label_to_canonical', '_canonical_to_label')
+
+    def __init__(self, owner: Tuple[int, int]):
+        self.owner = owner  # cell rank
+        self._label_to_canonical: Dict[str, Any] = {}
+        self._canonical_to_label: Dict[Any, str] = {}
+
+    def assign(self, label: str, canonical_value: Any) -> None:
+        """Assign a private label to a canonical value.
+
+        e.g. color.assign('red', 'CRITICAL')
+        e.g. color.assign('blue', 'CRITICAL')  # same canonical, different label
+        """
+        self._label_to_canonical[label] = canonical_value
+        self._canonical_to_label[canonical_value] = label
+
+    def canonical(self, label: str) -> Optional[Any]:
+        """Look up the canonical value for a private label."""
+        return self._label_to_canonical.get(label)
+
+    def label(self, canonical_value: Any) -> Optional[str]:
+        """Look up the private label for a canonical value (the inverse)."""
+        return self._canonical_to_label.get(canonical_value)
+
+    def labels(self) -> Dict[str, Any]:
+        """Read-only view of all private labels."""
+        return dict(self._label_to_canonical)
+
+    def __repr__(self):
+        return f"ColorNamespace(owner={self.owner}, labels={self.labels()!r})"
+
+
+def same_canonical(ns_a: ColorNamespace, label_a: str,
+                   ns_b: ColorNamespace, label_b: str) -> bool:
+    """True iff two cells' labels resolve to the same canonical value.
+
+    This is how the substrate verifies that two cells agree on the LOGIC,
+    not the labels. Cell A's "red" and Cell B's "blue" agree iff both
+    map to the same canonical value (e.g., 'CRITICAL').
+    """
+    a = ns_a.canonical(label_a)
+    b = ns_b.canonical(label_b)
+    return a is not None and a == b
+
+
+def labels_matter(ns_a: ColorNamespace, ns_b: ColorNamespace) -> bool:
+    """Whether the LABELS (not the canonical values) of two cells agree.
+
+    This is intentionally weak. The substrate doesn't compare labels —
+    it compares canonical values. labels_matter is FALSE in most cases.
+    """
+    if set(ns_a.labels().keys()) != set(ns_b.labels().keys()):
+        return False
+    for label in ns_a.labels():
+        if not ns_b.canonical(label):
+            return False
+    return True

quilt_spreadsheet/grid.py

@@ -0,0 +1,135 @@
+"""
+grid.py — QuiltSpreadsheet — the spreadsheet-shaped substrate.
+
+A spreadsheet-shaped substrate. Each cell is a runnable program with
+hooks to other cells. The grid is the substrate walker canvas — cells
+live INSIDE the grid, the grid is the IDE's front-end.
+
+The substrate transition: from quilt-egg (1 cell) to quilt-spreadsheet
+(grid of cells). Same DNA, same constants, more dimensions.
+"""
+
+from typing import Tuple, Optional, Callable, Dict, Any, List
+import sys
+
+from .cell import SheetCell, register_cell
+from .clock import get_default_clock, reset_default_clock
+from .ledger import get_default_ledger, reset_default_ledger
+from .backend import get_default_backend, reset_default_backend
+
+
+class QuiltSpreadsheet:
+    """A spreadsheet-shaped substrate.
+
+    The IDE front-end is rows × cols of cells. Each cell is a runnable
+    program with hooks. Pulls and pushes between cells are recorded in
+    the double-entry ledger.
+    """
+
+    def __init__(self, rows: int = 8, cols: int = 8, name: str = "spreadsheet"):
+        self.rows = rows
+        self.cols = cols
+        self.name = name
+        self._cells: Dict[Tuple[int, int], SheetCell] = {}
+        # Bind module-level singletons to this substrate instance
+        # (for testing — production uses the module-level clock/ledger)
+        self.clock = get_default_clock()
+        self.ledger = get_default_ledger()
+        self.backend = get_default_backend()
+
+    def place_cell(
+        self,
+        row: int,
+        col: int,
+        program: Callable,
+        axioms=None,
+    ) -> SheetCell:
+        """Place a program into the substrate at (row, col).
+
+        Casey: "a python program might sit in a cell as a shell command
+        ready to run with hooks to other cells for wake-up."
+
+        The cell is the program's home. It wakes when pulled.
+        """
+        if (row, col) in self._cells:
+            raise ValueError(f"cell at ({row}, {col}) already exists")
+        cell = SheetCell(row=row, col=col, program=program, axioms=axioms)
+        self._cells[cell.rank] = cell
+        register_cell(cell)
+        return cell
+
+    def get_cell(self, row: int, col: int) -> Optional[SheetCell]:
+        return self._cells.get((row, col))
+
+    def cells(self) -> List[SheetCell]:
+        return list(self._cells.values())
+
+    def render(self) -> str:
+        """Render the substrate as a spreadsheet-shaped string.
+
+        Each cell shows its row,col and a status indicator:
+          '.' = dormant
+          '*' = awake (has been pulled at least once)
+          'P' = pulled (received a pull)
+          'X' = pushed (sent a push)
+        """
+        rows_str = []
+        for r in range(self.rows):
+            line = "  "
+            for c in range(self.cols):
+                cell = self._cells.get((r, c))
+                if cell is None:
+                    mark = "."
+                elif cell.awake_count > 0:
+                    mark = "*"
+                else:
+                    mark = "_"
+                line += f" {mark}  "
+            rows_str.append(line)
+        header = "  " + "  ".join(f"c{c}" for c in range(self.cols))
+        return "\n".join([f"QuiltSpreadsheet '{self.name}' {self.rows}x{self.cols}", header] + rows_str)
+
+    def pull(self, source_row, source_col, target_row, target_col,
+             hook: str = "default", value: Any = None) -> dict:
+        """Cell at (source) pulls from cell at (target).
+
+        Records the pull/push pair in the ledger. Wakes the target.
+        """
+        source_cell = self._cells.get((source_row, source_col))
+        target_cell = self._cells.get((target_row, target_col))
+        if source_cell is None or target_cell is None:
+            return {'error': f"cell(s) not found: source={(source_row, source_col)}, target={(target_row, target_col)}"}
+        return source_cell.pull_from(target_cell.rank, hook=hook, value=value)
+
+    def summary(self) -> dict:
+        cells = self.cells()
+        total_awake = sum(1 for c in cells if c.awake_count > 0)
+        total_pulls = sum(len(hooks) for hooks in (c.pulls for c in cells))
+        # Flatten the hooks lists
+        total_pull_count = sum(len(v) for c in cells for v in c.pulls.values())
+        total_push_count = sum(len(v) for c in cells for v in c.pushes.values())
+        return {
+            "name": self.name,
+            "rows": self.rows,
+            "cols": self.cols,
+            "cells_placed": len(self._cells),
+            "cells_awake": total_awake,
+            "ledger": self.ledger.summary(),
+            "backend_conversions_run": self.backend.stats()["conversions_run"],
+        }
+
+
+def place_cell(row: int, col: int, program: Callable, axioms=None) -> SheetCell:
+    """Convenience: place a cell into the default registry."""
+    cell = SheetCell(row=row, col=col, program=program, axioms=axioms)
+    register_cell(cell)
+    return cell
+
+
+def reset_all() -> None:
+    """Reset all singletons for testing."""
+    reset_default_clock()
+    reset_default_ledger()
+    reset_default_backend()
+    from .cell import reset_registry
+    reset_registry()

quilt_spreadsheet/ledger.py

@@ -0,0 +1,163 @@
+"""
+ledger.py — double-entry bookkeeping for spreadsheet pull/push pairs.
+
+Casey: "there's a double-entry book keeping that for every pull is a push
+somewhere else that simply needs an agreement and timestamp."
+
+This is the SUBSTRATE-level ledger. Every pull from cell A to cell B is
+recorded ONCE as a pair: a 'pull' entry in A's view, a 'push' entry in
+B's view. Both share the SAME (source, target, hook, timestamp). The
+agreement criterion: any matching pair (a, b) that matches (a, b, hook, ts)
+is a successful ledger entry.
+
+If there is a pull without a matching push, the ledger reports an
+unbalanced entry (the substrate's "alert"). This is the substrate's
+audit trail — the witness log at the spreadsheet level.
+"""
+
+from dataclasses import dataclass, field
+from typing import Tuple, List, Dict, Optional, Any
+import time
+import uuid
+
+
+@dataclass(frozen=True)
+class LedgerEntry:
+    """A single ledger entry.
+
+    A pull is one entry. A push that responds to a pull is another entry.
+    Both share the same pair_id — that's the agreement.
+    """
+    pair_id: str       # UUID linking pull + push
+    source: Tuple[int, int]   # cell rank
+    target: Tuple[int, int]   # cell rank
+    direction: str     # 'pull' or 'push'
+    hook: str          # the hook name (the "what" of the request)
+    value: Any         # the value being transferred
+    timestamp_ns: int  # monotonic clock at the moment of recording
+    seen_by: List[Tuple[int, int]] = field(default_factory=list)  # which cells' clocks recorded this
+
+
+class Ledger:
+    """The double-entry ledger.
+
+    Every pull/push pair is recorded as TWO entries with the same pair_id.
+    The ledger can verify that every pull has a matching push by walking
+    all entries grouped by pair_id.
+    """
+
+    def __init__(self):
+        self._entries: List[LedgerEntry] = []
+        self._pair_count: int = 0
+
+    def record_pull(
+        self,
+        source: Tuple[int, int],
+        target: Tuple[int, int],
+        hook: str,
+        value: Any,
+        timestamp_ns: int,
+    ) -> LedgerEntry:
+        """Record a 'pull' — a request from source to target."""
+        pair_id = str(uuid.uuid4())
+        entry = LedgerEntry(
+            pair_id=pair_id,
+            source=source,
+            target=target,
+            direction='pull',
+            hook=hook,
+            value=value,
+            timestamp_ns=timestamp_ns,
+            seen_by=[source],
+        )
+        self._entries.append(entry)
+        return entry
+
+    def record_push(
+        self,
+        source: Tuple[int, int],
+        target: Tuple[int, int],
+        hook: str,
+        value: Any,
+        timestamp_ns: int,
+        pair_id: str,
+    ) -> Optional[LedgerEntry]:
+        """Record the matched 'push' response for a prior pull.
+
+        The pair_id MUST match the pull's pair_id. If no pull exists yet,
+        return None (the push without a pull is a substrate violation).
+        """
+        # Verify the pull exists
+        pull = self._find_pull(pair_id)
+        if pull is None:
+            return None  # push without a pull — substrate violation
+        entry = LedgerEntry(
+            pair_id=pair_id,
+            source=source,
+            target=target,
+            direction='push',
+            hook=hook,
+            value=value,
+            timestamp_ns=timestamp_ns,
+            seen_by=[source, target],
+        )
+        self._entries.append(entry)
+        self._pair_count += 1
+        return entry
+
+    def _find_pull(self, pair_id: str) -> Optional[LedgerEntry]:
+        for e in self._entries:
+            if e.pair_id == pair_id and e.direction == 'pull':
+                return e
+        return None
+
+    @property
+    def total_pulls(self) -> int:
+        return sum(1 for e in self._entries if e.direction == 'pull')
+
+    @property
+    def total_pushes(self) -> int:
+        return sum(1 for e in self._entries if e.direction == 'push')
+
+    @property
+    def total_pairs(self) -> int:
+        return self._pair_count
+
+    @property
+    def unbalanced(self) -> List[LedgerEntry]:
+        """All pulls that don't have a matching push."""
+        paired_pull_ids = {
+            e.pair_id for e in self._entries if e.direction == 'push'
+        }
+        return [
+            e for e in self._entries
+            if e.direction == 'pull' and e.pair_id not in paired_pull_ids
+        ]
+
+    def all_entries(self) -> List[LedgerEntry]:
+        return list(self._entries)
+
+    def summary(self) -> dict:
+        return {
+            "total_entries": len(self._entries),
+            "pulls": self.total_pulls,
+            "pushes": self.total_pushes,
+            "pairs": self.total_pairs,
+            "unbalanced_pulls": len(self.unbalanced),
+        }
+
+
+# Module-level singleton
+_default_ledger = None
+
+
+def get_default_ledger() -> Ledger:
+    global _default_ledger
+    if _default_ledger is None:
+        _default_ledger = Ledger()
+    return _default_ledger
+
+
+def reset_default_ledger() -> None:
+    global _default_ledger
+    _default_ledger = None

quilt_spreadsheet/perception.py

@@ -0,0 +1,72 @@
+"""
+perception.py — per-cell sorting and grouping of the spreadsheet around it.
+
+Casey: "the relationship is cellular and sorting and grouping for that
+cell's perception of the spreadsheet around it (there's no central program
+within the cell's instance, it's just a program running so if it sorts
+for it's own purpose by type instead of date so it can group with simple
+excel terms."
+
+Each cell has its OWN perception of the spreadsheet. A cell can sort
+its view by type, by tag, by relevance, by age — whatever its program
+needs. The substrate provides the raw view; the cell sorts as it sees fit.
+"""
+
+from typing import List, Dict, Any, Optional, Tuple, Callable
+from collections import defaultdict
+
+
+class Perception:
+    """A single cell's view of the spreadsheet around it.
+
+    Cells pull from each other. When a cell pulls a slice of the spreadsheet,
+    it gets the raw observations. Each cell has its own Perception that
+    sorts those observations for its program's purpose.
+    """
+
+    __slots__ = ('owner', '_items', '_sort_key')
+
+    def __init__(self, owner: Tuple[int, int]):
+        self.owner = owner
+        self._items: List[Dict[str, Any]] = []
+        self._sort_key: Optional[Callable] = None
+
+    def ingest(self, items: List[Dict[str, Any]]) -> None:
+        """Add raw observations to this perception."""
+        self._items.extend(items)
+
+    def sort_by_type(self) -> 'Perception':
+        """Sort observations by 'type' field (default perception sort).
+
+        Casey: 'if it sorts for its own purpose by type instead of date'.
+        The type-based sort groups by category — like Excel grouping
+        rows by data type.
+        """
+        self._sort_key = lambda x: x.get('type', '')
+        self._items.sort(key=self._sort_key)
+        return self
+
+    def sort_by(self, key: Callable) -> 'Perception':
+        """Custom sort."""
+        self._sort_key = key
+        self._items.sort(key=key)
+        return self
+
+    def group_by_type(self) -> Dict[str, List[Dict[str, Any]]]:
+        """Group observations by 'type' field. Returns dict[group_name, items]."""
+        groups: Dict[str, List[Dict[str, Any]]] = defaultdict(list)
+        for item in self._items:
+            t = item.get('type', 'untyped')
+            groups[t].append(item)
+        return dict(groups)
+
+    def filter(self, predicate: Callable[[Dict[str, Any]], bool]) -> 'Perception':
+        """Keep only items where predicate returns True."""
+        self._items = [i for i in self._items if predicate(i)]
+        return self
+
+    def items(self) -> List[Dict[str, Any]]:
+        return list(self._items)
+
+    def size(self) -> int:
+        return len(self._items)

quilt_spreadsheet-0.1.0.dist-info/METADATA

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: quilt-spreadsheet
+Version: 0.1.0
+Summary: The Quilt IDE as spreadsheet substrate — cells as programs with hooks, double-entry bookkeeping, per-cell color namespaces, backend porting, distributed clocks
+Author: Casey / SuperInstance
+License: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Dynamic: license-file
+Dynamic: requires-python
+
+# quilt-spreadsheet
+
+> **The Quilt IDE as spreadsheet substrate.**
+>
+> Front-end: rows × cols. Each cell is a runnable program with hooks.
+> Double-entry bookkeeping tracks every pull/push. Per-cell color
+> namespaces. Backend porting across scales. Distributed clocks with
+> skew tolerance.
+
+## What this is
+
+A runnable Python substrate where:
+
+1. **Front-end is a spreadsheet** — `QuiltSpreadsheet(rows, cols)`. Each cell is a `SheetCell`.
+2. **Each cell is a runnable program** with hooks (pulls wake it). No `main()`. Event-driven.
+3. **Double-entry bookkeeping** — every pull/push pair is recorded as a ledger pair. Same UUID, same timestamp.
+4. **Per-cell color namespaces** — cells can label anything anything. The substrate checks canonical agreement, not labels.
+5. **Backend porting** — different cells can use different scales/units. The backend converts at the boundary.
+6. **Distributed clocks with skew** — clocks can disagree. Time-between-events is the sync signal. Confidence rises with shared events.
+
+## Quick start
+
+```bash
+# Run the canonical demo
+python3 -m quilt_spreadsheet
+
+# Or with custom dimensions
+python3 -m quilt_spreadsheet --rows 4 --cols 4
+
+# Run individual demos
+PYTHONPATH=. python3 demos/demo_double_entry.py
+PYTHONPATH=. python3 demos/demo_color_independent.py
+PYTHONPATH=. python3 demos/demo_backend_conversion.py
+PYTHONPATH=. python3 demos/demo_clock_skew.py
+```
+
+## Quick example
+
+```python
+from quilt_spreadsheet.grid import QuiltSpreadsheet
+
+sheet = QuiltSpreadsheet(rows=4, cols=4)
+
+def adder(*, source, hook, value):
+    return (value or 0) + 1
+
+def doubler(*, source, hook, value):
+    return (value or 0) * 2
+
+# Place programs into cells
+sheet.place_cell(0, 0, adder)
+sheet.place_cell(0, 1, doubler)
+
+# Cell (0, 0) pulls from cell (0, 1) with value=5
+result = sheet.pull(0, 0, 0, 1, hook="double", value=5)
+
+print(result)
+# {'response': 10, 'pair_id': '...', 'timestamp_ns': ..., 'cell': (0, 1)}
+```
+
+## The 4 demos
+
+### 1. `demos/demo_double_entry.py`
+
+Demonstrates the load-bearing ledger. Pulls and pushes are paired by UUID
++ timestamp. Unbalanced pulls are flagged but not prevented.
+
+### 2. `demos/demo_color_independent.py`
+
+Two cells with different color labels (red/blue) for the same canonical
+(CRITICAL). The substrate verifies agreement at canonical level, not
+labels.
+
+### 3. `demos/demo_backend_conversion.py`
+
+Backend ports values between scales (celsius → fahrenheit). Gates values
+below threshold. Snaps approximations to discrete grid. Time is preserved
+in same units on both sides.
+
+### 4. `demos/demo_clock_skew.py`
+
+Two cells share 10 events. Confidence rises asymptotically from 0.5 to 0.91.
+Skew is observable but manageable.
+
+## Architecture
+
+```
+QuiltSpreadsheet (rows × cols)
+    ├── CellClock [per-cell, private]
+    ├── Ledger [double-entry pair ledger]
+    ├── Backend [conversions, gates, snaps]
+    └── SheetCell (rows × cols)
+        ├── program: Callable (no main, runs on pull)
+        ├── axioms: frozenset (DNA)
+        ├── dials: List[float] (16 mutable state slots)
+        ├── color: ColorNamespace (private labels)
+        ├── perception: Perception (own sort/group)
+        ├── witness_log: List[dict]
+        ├── pulls: Dict[cell, List[hook]]
+        └── pushes: Dict[cell, List[hook]]
+```
+
+## The 3 commands
+
+```python
+# 1. Place a program into a cell
+sheet.place_cell(row, col, program, axioms=None)
+
+# 2. Pull from another cell (cell A at (r0, c0) wakes cell at (r1, c1))
+sheet.pull(r0, c0, r1, c1, hook='name', value=...)
+
+# 3. Inspect state
+sheet.render()        # spreadsheet-shaped ascii view
+sheet.summary()       # substrate state dict
+sheet.ledger.summary()  # double-entry pair ledger
+```
+
+## Substrate transition
+
+This repo is the substrate transition FROM `quilt-egg` (single cell) TO
+`quilt-spreadsheet` (grid of cells with hooks). Same constants, same DNA.
+More dimensions.
+
+| quilt-egg | quilt-spreadsheet |
+|---|---|
+| 1 cell | rows × cols cells |
+| 1 tick loop | pull-triggered wake |
+| DNA + dials | DNA + dials + hooks + color + perception |
+| 18 tests | 21 tests |
+| 4 demos | 4 demos |
+
+## Layered navigation
+
+| Layer | Where |
+|---|---|
+| **CANON.md** | [CANON.md](CANON.md) — what this repo is, in 24 lines |
+| **README** | [README.md](README.md) — quick start, navigation |
+| **Spec** | [docs/SPEC.md](docs/SPEC.md) — half-canon, half-spec |
+| **Source** | [quilt_spreadsheet/](quilt_spreadsheet/) — `clock.py`, `ledger.py`, `color.py`, `backend.py`, `perception.py`, `cell.py`, `grid.py` |
+| **Demos** | [demos/](demos/) — 4 runnable demos |
+| **Tests** | [tests/](tests/) — 21 unit tests |
+| **Origin** | [quilt-egg](../quilt-egg/) — the prior substrate |
+
+## Polyformalism
+
+This substrate is canonically a polyformalism port. The canary
+`fnv1a-64("café Δ 日本語") = 0x024a555471370b18d` is verified on every
+Quilt port.
+
+## Tests
+
+```bash
+PYTHONPATH=. python3 -m unittest discover -s tests -v
+```
+
+21 tests covering:
+- Clock skew tolerance and pairwise confidence
+- Double-entry ledger pairing (and unbalanced-pull handling)
+- Per-cell color namespaces
+- Backend conversions, gates, snaps
+- Spreadsheet pull/push wiring
+- Perception sorting/grouping/filtering
+
+## License
+
+MIT — Casey / SuperInstance, Sept 23, 2026

quilt_spreadsheet-0.1.0.dist-info/RECORD

@@ -0,0 +1,14 @@
+quilt_spreadsheet/__init__.py,sha256=xneWWEnIDwyWxnS8-Jt6mddZfYjnxNZ8zoLq3A_RcZU,1621
+quilt_spreadsheet/__main__.py,sha256=x_KjfS7DM8VsaSBPcZPHB1Quuo_BONCl24H7O15kKQM,2228
+quilt_spreadsheet/backend.py,sha256=SasWWpO1e4AJrj3vcJDrZ-kRlALtrd2vMSGGOxP95cU,6272
+quilt_spreadsheet/cell.py,sha256=xCNmxMcE7CMeToE7iZOyCtvjg36ts0ZIp-R_YaN8le0,7280
+quilt_spreadsheet/clock.py,sha256=irq27i8VsXNkOrGqeFPxoCpyz263n7lBM_xoGb20s50,4799
+quilt_spreadsheet/color.py,sha256=3MNZsNmIs5FXFaViBsDJl8Smg_DoSudXQSY9qzQM7vU,3508
+quilt_spreadsheet/grid.py,sha256=5Gl0URdpeKh5_e13HlgXzUPIPWtHUwS_bOglDFhk6QE,5083
+quilt_spreadsheet/ledger.py,sha256=UfSWRoxHjKR0FkwiWtjNqIVodqyClKUgpqTn8zqr4_s,5029
+quilt_spreadsheet/perception.py,sha256=yxG-gs9g41fqayyfZi63j5105wsRskYrRL20N7aAPYI,2679
+quilt_spreadsheet-0.1.0.dist-info/licenses/LICENSE,sha256=QzOhcWaBRQ6WHKAOfQD_V2h1XWSnul4IqnY3HLXli1s,64
+quilt_spreadsheet-0.1.0.dist-info/METADATA,sha256=bSy5tmz5pxfozJxprsQQQnRWbW820TRJAzHk0dAKE5g,5893
+quilt_spreadsheet-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+quilt_spreadsheet-0.1.0.dist-info/top_level.txt,sha256=Mn9cDYnVzobyyFHksUv_wcASZPXGespLhPxgkGqdmUg,18
+quilt_spreadsheet-0.1.0.dist-info/RECORD,,

quilt_spreadsheet-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

quilt_spreadsheet-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,3 @@
+MIT License
+
+Copyright (c) 2026 Casey Digennaro / SuperInstance

quilt_spreadsheet-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+quilt_spreadsheet