{"id":34595728,"url":"https://github.com/recdnd/spiral-core-series","last_synced_at":"2026-03-13T21:31:43.320Z","repository":{"id":330273829,"uuid":"1122188383","full_name":"recdnd/spiral-core-series","owner":"recdnd","description":"Append-only event DAG prototypes with RECENT_A trace-closure frontier + conflict-pair bound signals.","archived":false,"fork":false,"pushed_at":"2026-01-13T15:27:39.000Z","size":108,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-13T18:16:26.784Z","etag":null,"topics":["append-only","causal-graph","dag","dsl","event-sourcing","frontier","observability","research-prototype","spiralvm","tracing"],"latest_commit_sha":null,"homepage":"https://core.rec.ooo","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/recdnd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-24T08:49:28.000Z","updated_at":"2026-01-13T15:27:42.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/recdnd/spiral-core-series","commit_stats":null,"previous_names":["recdnd/spiral-core-series"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/recdnd/spiral-core-series","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/recdnd%2Fspiral-core-series","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/recdnd%2Fspiral-core-series/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/recdnd%2Fspiral-core-series/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/recdnd%2Fspiral-core-series/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/recdnd","download_url":"https://codeload.github.com/recdnd/spiral-core-series/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/recdnd%2Fspiral-core-series/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30476281,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-13T20:45:58.186Z","status":"ssl_error","status_checked_at":"2026-03-13T20:45:20.133Z","response_time":60,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["append-only","causal-graph","dag","dsl","event-sourcing","frontier","observability","research-prototype","spiralvm","tracing"],"created_at":"2025-12-24T11:35:43.404Z","updated_at":"2026-03-13T21:31:43.304Z","avatar_url":"https://github.com/recdnd.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# spiral-core-series\n\nA minimal, append-only event history core for Spiral. Focused on traceable causality, conflict signals, and frontier visibility.\n\n\u003e **Status**: Prototype series (v0.02 → v0.46).  \n\u003e **Latest**: v0.46 — Parents printing + strong binding + invariants.\n\n---\n\n## What This Is\n\n`spiral-core-series` is a compact set of Python prototypes that explore a single problem:\n\n**How do we keep \"what matters\" visible in an event stream, without losing causal meaning?**\n\nCore capabilities:\n\n- Append-only event log.\n- Derived signals (e.g. `conflict_heat`).\n- View projection (`frontier`) that surfaces relevant nodes while preserving causality.\n- Strong binding rule: derived events must be attributable to a concrete input pair (\"conflict pair\").\n\n**Notation**: `parent_ids` (code) == `parents` (discussion) == `P_e` (spec).\n\n---\n\n## What Problem It Solves / What's Novel\n\nEvent streams accumulate fast. Traditional approaches face two critical limitations:\n\n1. **Sliding windows** drop causal context when truncating by time.\n2. **Score-based ranking** loses explainability when events are selected by importance alone.\n\n**RECENT_A is not a sliding window.** It defines \"recent context\" not as a temporal window, but as the minimal causally closed subgraph necessary to explain the system's latest behavior.\n\n---\n\n## Docs\n\n- **Concept / intuition**: [`docs/ABSTRACT.md`](docs/ABSTRACT.md)\n- **Formal spec**: [`docs/SPEC_RECENT_A.md`](docs/SPEC_RECENT_A.md)\n- **Engineering narrative**: [`docs/WHITEPAPER.md`](docs/WHITEPAPER.md)\n- **Version arc**: [`CHANGELOG.md`](CHANGELOG.md)\n\n---\n\n## Quickstart\n\nRequirements: Python 3.10+\n\n```bash\ngit clone https://github.com/recdnd/spiral-core-series.git\ncd spiral-core-series\npython3 run.py\n```\n\nExpected output (shape):\n\nHistory size: ... (append-only)\n\n== View: LAST_12 ==\n\n== View: FRONTIER_RECENT_K_FIXED ... ==\n\nInvariant: no deletions, no edits. Only new events.\n\n---\n\n## Cite / Attribution\n\nIf you build on **RECENT_A (trace-closure frontier)** or the **conflict-pair binding** rule, attribution is appreciated:\n\n- Concept + prototype: **recdnd/spiral-core-series**\n- Spec: [`docs/SPEC_RECENT_A.md`](docs/SPEC_RECENT_A.md)\n\n---\n\n## Why It Exists\n\nEvent streams accumulate fast. Naive sliding windows drop causal context. Simple ranking loses explainability.\n\nThis series builds a **trace-closure** approach: instead of truncating by time or score, we maintain minimal causally closed subgraphs that remain interpretable.\n\n---\n\n## Core Invariants\n\n**Append-only. No edits. No deletions.**\n\n- Events are only appended to history.\n- No mutation, no deletion, no retroactive changes.\n\n**Causal edges are explicit via parent_ids.**\n\n- Every event declares its causal parents explicitly.\n- The history forms a DAG (directed acyclic graph).\n\n**Derived events binding.**\n\n- Every `observe(conflict_heat)` and `noise(conflict(2))` must be attributable to a concrete **conflict pair** (two input events).\n- This is enforced by runtime invariants (see v0.46).\n\n---\n\n## RECENT_A Overview (Trace-Closure)\n\n**RECENT_A is not a sliding window.**\n\nInstead of a plain sliding window, RECENT_A is defined as:\n\n\u003e **The minimal causally closed subgraph generated from the last K events, augmented with reactive system responses.**\n\nComponents:\n\n- **Seed**: Last K events (time-based).\n- **Upward closure**: Include ancestors (bounded by depth).\n- **Downward closure**: Include reactive explainers (observe/noise/repair) that reference kept nodes.\n- **Ranking is orthogonal**: `trace_score` sorts the view, it does not decide membership.\n\n**Formal spec**: See [`docs/SPEC_RECENT_A.md`](docs/SPEC_RECENT_A.md).\n\n---\n\n## Repo Structure\n\n```\nspiral-core-series/\n├── README.md                    # This file\n├── .gitignore\n├── spiral_core.py              # Minimal core (optional reference)\n├── docs/\n│   ├── ABSTRACT.md\n│   ├── SPEC_RECENT_A.md\n│   └── WHITEPAPER.md\n├── CHANGELOG.md\n└── versions/\n    ├── v0.02/\n    │   └── spiral_core_v02.py\n    ├── v0.03/\n    │   └── spiral_core_v03_a-only.py\n    ...\n    └── v0.046/\n        ├── README.md\n        └── spiral_core_v046_frontier-recent-k-fix.py  # Latest reference\n```\n\n**Version naming**: Each version lives in `versions/vX.XX/` with its prototype file(s). Append-only series: no deletions, no merges.\n\n---\n\n## Quickstart\n\n**Requirements:** Python 3.10+ (and `make`)\n\n```bash\ngit clone https://github.com/recdnd/spiral-core-series.git\ncd spiral-core-series\npython3 run.py\n```\n\n**Expected output**:\n\n- `LAST_12` — newest events in append-only history.\n- `FRONTIER_RECENT_K_FIXED` — RECENT_A-like view (recent seed + closure + one-hop forward).\n- `FRONTIER_GLOBAL` — global skeleton view from latest roots.\n- `OBSERVE_ONLY` — observe events sorted by trace score.\n- `Invariant: ...` — must pass (strong binding checks).\n\nParents are printed as `parents=[deadbeef,feedcafe]` (first 8 chars) for causality visibility.\n\n### Minimal Demo\n\n```bash\n$ make run\n\nHistory size: 66 (append-only)\n\n== View: LAST_12 ==\n1766567425207 da65d94eaa729bd2 noise score=1.000 p=2 parents=[a391db30,7c0f834e] [conflict(2)] | NOISE:...\n1766567425206 48717d1805cebf8e observe score=0.998 p=2 parents=[a391db30,7c0f834e] | observe=conflict_heat; ...\n1766567425205 7e9a83747106e6f5 input score=0.996 p=1 parents=[9bb7b51c] | repair: summarize; topic=y\n...\n\n== View: FRONTIER_RECENT_K_FIXED top20 (ranked by trace_score) ==\n...\n\nInvariant: no deletions, no edits. Only new events.\n```\n\nThe `parents=[...]` field makes \"why is this event here?\" answerable by inspection.\n\n---\n\n## Event Model (Minimal)\n\nEach event has:\n\n- `ts`: monotonic ms timestamp.\n- `id`: short hash id.\n- `parent_ids`: causal edges (explicit).\n- `meta`: typed tags (`kind`, `topic`, etc.).\n- `payload`: a human-readable line.\n\n**Kinds used in the series**:\n\n- `input`: primary events with `meta.topic`.\n- `observe`: derived state, currently `observe=conflict_heat`.\n- `noise`: derived escalation, currently `noise_kind=conflict(2)`.\n- `repair`: implemented as a special `input` payload in current prototypes.\n\n---\n\n## Output Glossary\n\n**Views**:\n\n- `LAST_N`: Simple tail view (last N events by timestamp).\n- `FRONTIER_RECENT_K_FIXED`: RECENT_A trace-closure view.\n- `FRONTIER_GLOBAL`: Global skeleton view (roots + closure + one-hop forward).\n\n**Event types**:\n\n- `input`: Primary events with topics (x, y, z).\n- `observe`: Derived conflict heat state (`observe=conflict_heat`).\n- `noise`: Conflict escalation (`noise_kind=conflict(2)`).\n- `repair`: Repair attempts (currently as `input` payload).\n\n**Fields**:\n\n- `parents=[id8,id8]`: Causal parent ids (truncated to 8 hex chars for readability).\n- `score=0.998`: Trace score (time decay, view-only ranking).\n- `p=2`: Parent count.\n\n**Conflict pair**: Two input event ids that generated a conflict. Strongly bound to `observe` and `noise` events in v0.46+.\n\n---\n\n## Strong Binding Rule\n\n**Definition**: Every derived event (`observe(conflict_heat)` or `noise(conflict(2))`) must have `parent_ids` equal to the **conflict pair** (two input events) that generated it.\n\n**Why**: This ensures every derived event is traceable to concrete inputs. No floating explanations. Frontier views remain interpretable.\n\n**Enforcement**: Runtime invariants check this at the end of each run (v0.46+). See [`versions/v0.046/README.md`](versions/v0.046/README.md) for details.\n\n---\n\n## Roadmap\n\n- **v0.46** (current): Parents printing + strong binding + invariants. ✅\n- **v0.47+** (future): Conflict pair selection policy pluggability, deterministic replay, compact export (JSONL).\n\nFor detailed changelog across v0.39 → v0.46, see [`CHANGELOG.md`](CHANGELOG.md).\n\n---\n\n## Additional Resources\n\n- **v0.46 README**: [`versions/v0.046/README.md`](versions/v0.046/README.md) — Latest version implementation details.\n\n---\n\n## License\n\nApache-2.0\n\n---\n\n## Credits\n\nBuilt by Rec. Part of the Spiral / SpiralVM research-to-tool chain.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frecdnd%2Fspiral-core-series","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Frecdnd%2Fspiral-core-series","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Frecdnd%2Fspiral-core-series/lists"}