Rename ephemeral -> wisp terminology throughout Gas Town
- .beads-ephemeral/ -> .beads-wisp/ - Rename doctor checks: EphemeralCheck -> WispCheck - Update all docs to use 'transient' for polecats, 'wisp' for molecules - Preserve 'ephemeral' only as descriptive adjective for wisps - Steam engine metaphor: wisps are steam vapors that dissipate Part of Christmas launch wisp terminology unification.
This commit is contained in:
Steve Yegge
@@ -357,8 +357,8 @@ Molecules follow a **states of matter** metaphor through their lifecycle:
|
||||
┌───────────────┐ ┌───────────────┐
|
||||
│ Mol │ │ Wisp │
|
||||
│ (liquid) │ │ (gas) │
|
||||
│ durable │ │ ephemeral │
|
||||
│ main beads │ │ .beads-eph/ │
|
||||
│ durable │ │ transient │
|
||||
│ main beads │ │ .beads-wisp/ │
|
||||
└───────┬───────┘ └───────┬───────┘
|
||||
│ │
|
||||
bd mol squash bd mol squash
|
||||
@@ -374,15 +374,15 @@ Molecules follow a **states of matter** metaphor through their lifecycle:
|
||||
**Phase transitions:**
|
||||
- **Proto → Mol/Wisp** (`bd mol bond`): Instantiate a template into a running execution
|
||||
- **Mol → Digest** (`bd mol squash`): Compress completed work into permanent record
|
||||
- **Wisp → (evaporates)** (`bd mol squash` or `bd mol burn`): Ephemeral trace disappears
|
||||
- **Wisp → (evaporates)** (`bd mol squash` or `bd mol burn`): Transient trace disappears
|
||||
|
||||
### When to Use Mol vs Wisp
|
||||
|
||||
The choice between **Mol** (durable) and **Wisp** (ephemeral) depends on the work's importance and audit requirements:
|
||||
The choice between **Mol** (durable) and **Wisp** (transient) depends on the work's importance and audit requirements:
|
||||
|
||||
| Aspect | Mol (Durable) | Wisp (Ephemeral) |
|
||||
| Aspect | Mol (Durable) | Wisp (Transient) |
|
||||
|--------|---------------|------------------|
|
||||
| **Storage** | Main `.beads/` database | `.beads-ephemeral/` directory |
|
||||
| **Storage** | Main `.beads/` database | `.beads-wisp/` directory |
|
||||
| **Persistence** | Survives indefinitely | Evaporates on squash/burn |
|
||||
| **Git tracking** | Committed, synced | Never committed |
|
||||
| **Audit trail** | Full history preserved | Only digest (if squashed) |
|
||||
@@ -396,7 +396,7 @@ The choice between **Mol** (durable) and **Wisp** (ephemeral) depends on the wor
|
||||
|
||||
**Use Wisp for:**
|
||||
- Orchestration tasks (witness patrols, health checks)
|
||||
- Polecat work sessions (ephemeral by nature)
|
||||
- Polecat work sessions (transient by nature)
|
||||
- Patrol loops (continuous monitoring)
|
||||
- Routine operations (no audit value)
|
||||
|
||||
@@ -491,7 +491,7 @@ This is like a **distributed work queue** backed by beads:
|
||||
|
||||
### Wisp Molecules: Transient Execution Traces
|
||||
|
||||
**Wisps** are ephemeral execution traces - the "steam" in Gas Town's engine metaphor. When a molecule executes, it generates wisps: transient issues that capture the work being done.
|
||||
**Wisps** are transient execution traces - the "steam" in Gas Town's engine metaphor. Claude is fire; Claude Code is a Steam engine; Gas Town is a Steam Train, with Beads as the tracks. Wisps are steam vapors that dissipate after the work is done.
|
||||
|
||||
**Why wisps?**
|
||||
- **Observability**: See what's happening during execution without cluttering the permanent ledger
|
||||
@@ -547,8 +547,8 @@ bd mol burn gt-abc123.exec-001 # Discard wisps without digest
|
||||
|
||||
**Wisp storage:**
|
||||
|
||||
Wisps are stored in a per-rig ephemeral database:
|
||||
- `<rig>/.beads-ephemeral/` - Separate from permanent beads, **gitignored**
|
||||
Wisps are stored in a per-rig wisp database:
|
||||
- `<rig>/.beads-wisp/` - Separate from permanent beads, **gitignored**
|
||||
- Fast writes, no sync overhead
|
||||
- Auto-cleaned on squash/burn
|
||||
- Digests write to permanent beads
|
||||
@@ -1316,7 +1316,7 @@ Polecats are the workers that do actual implementation:
|
||||
4. On completion, polecat generates summary and squashes wisps to digest
|
||||
5. Request shutdown, get deleted
|
||||
|
||||
The polecat itself is ephemeral, and so is its execution trace (wisps). Only the digest survives.
|
||||
The polecat itself is transient, and so is its execution trace (wisps). Only the digest survives.
|
||||
|
||||
## Key Workflows
|
||||
|
||||
@@ -1694,7 +1694,7 @@ sequenceDiagram
|
||||
After Witness kills session:
|
||||
- Remove worktree: `git worktree remove polecats/<name>`
|
||||
- Delete branch: `git branch -d polecat/<name>`
|
||||
- Polecat ceases to exist (ephemeral)
|
||||
- Polecat ceases to exist (transient)
|
||||
|
||||
### 13. Resource-Constrained Worker Pool
|
||||
|
||||
@@ -1807,7 +1807,7 @@ With daemon session cycling, the system can run autonomously for extended period
|
||||
- **Workers cycle**: If individual tasks are very large
|
||||
- **Daemon persistence**: Survives all agent restarts
|
||||
|
||||
The daemon is the only truly persistent component. All agents are ephemeral sessions that hand off state via mail.
|
||||
The daemon is the only truly persistent component. All agents are transient sessions that hand off state via mail.
|
||||
|
||||
Work is a continuous stream - you can add new issues, spawn new workers, reprioritize the queue, all without "starting a new swarm" or managing batch boundaries.
|
||||
|
||||
@@ -1900,7 +1900,7 @@ gt handoff # Polecat requests shutdown (run when done)
|
||||
gt session stop <p> # Kill polecat session (Witness uses this)
|
||||
```
|
||||
|
||||
**Note**: `gt wake` and `gt sleep` are deprecated - polecats are ephemeral, not pooled.
|
||||
**Note**: `gt wake` and `gt sleep` are deprecated - polecats are transient, not pooled.
|
||||
|
||||
### Landing & Merge Queue
|
||||
|
||||
|
||||
@@ -163,7 +163,7 @@ parallel: true
|
||||
|
||||
# Beads Cleanup
|
||||
|
||||
Daily cleanup of ephemeral beads.
|
||||
Daily cleanup of wisp storage.
|
||||
|
||||
## Actions
|
||||
|
||||
|
||||
@@ -92,7 +92,7 @@ bd mol bond <proto-id> [--wisp] [--assignee=<addr>]
|
||||
|
||||
- **Default (Mol)**: Creates a durable molecule tracked in the main `.beads/` database.
|
||||
Steps become permanent issues that survive indefinitely.
|
||||
- **With --wisp**: Creates an ephemeral molecule in `.beads-ephemeral/`. Steps are
|
||||
- **With --wisp**: Creates a wisp (transient molecule) in `.beads-wisp/`. Steps are
|
||||
transient and will be cleaned up on squash or burn.
|
||||
|
||||
**Examples:**
|
||||
@@ -133,7 +133,7 @@ bd mol squash <mol-id> --summary='...'
|
||||
|
||||
- **For Mol (durable)**: Creates a digest issue in the permanent beads database.
|
||||
The digest contains the summary and links back to the original proto.
|
||||
- **For Wisp (ephemeral)**: Evaporates the wisp (deletes from `.beads-ephemeral/`)
|
||||
- **For Wisp (transient)**: Evaporates the wisp (deletes from `.beads-wisp/`)
|
||||
and creates a digest in the permanent database. The execution trace is gone,
|
||||
but the outcome is preserved.
|
||||
|
||||
@@ -181,7 +181,7 @@ bd mol burn <mol-id> [--reason='...']
|
||||
|
||||
- Discards all molecule state (steps, progress, artifacts)
|
||||
- No digest is created - the molecule leaves no permanent record
|
||||
- For Wisps: Simply deletes from `.beads-ephemeral/`
|
||||
- For Wisps: Simply deletes from `.beads-wisp/`
|
||||
- For Mols: Marks as abandoned/closed without digest
|
||||
|
||||
**When to burn vs squash:**
|
||||
|
||||
@@ -159,7 +159,7 @@ gastown/
|
||||
│ ├── spawn/
|
||||
│ │ ├── new_polecat.md
|
||||
│ │ ├── reuse_polecat.md
|
||||
│ │ └── ephemeral_worker.md
|
||||
│ │ └── transient_worker.md
|
||||
│ └── lifecycle/
|
||||
│ ├── handoff.md
|
||||
│ ├── escalation.md
|
||||
@@ -175,7 +175,7 @@ type PromptContext struct {
|
||||
Role string
|
||||
RigName string
|
||||
PolecatName string
|
||||
Ephemeral bool
|
||||
Transient bool
|
||||
IssueID string
|
||||
IssueTitle string
|
||||
// ... additional fields
|
||||
@@ -348,7 +348,7 @@ Crew workers are the overseer's personal workspaces - a new role that differs fr
|
||||
## Your Role: CREW WORKER ({{ name }} in {{ rig }})
|
||||
|
||||
You are a **crew worker** - the overseer's (human's) personal workspace within the {{ rig }} rig.
|
||||
Unlike polecats which are witness-managed and ephemeral, you are:
|
||||
Unlike polecats which are witness-managed and transient, you are:
|
||||
|
||||
- **Persistent**: Your workspace is never auto-garbage-collected
|
||||
- **User-managed**: The overseer controls your lifecycle, not the Witness
|
||||
|
||||
@@ -1,12 +1,12 @@
|
||||
# Wisp Architecture: Ephemeral Molecule Storage
|
||||
# Wisp Architecture: Transient Molecule Storage
|
||||
|
||||
> Status: Design Spec v1 - December 2024
|
||||
|
||||
## Overview
|
||||
|
||||
**Wisps** are ephemeral molecule execution traces - the "steam" in Gas Town's engine
|
||||
metaphor. This document specifies where wisps are stored, how they're managed, and
|
||||
which roles use them.
|
||||
**Wisps** are transient molecule execution traces - the "steam" in Gas Town's engine
|
||||
metaphor. Claude is fire; Claude Code is a Steam engine; Gas Town is a Steam Train,
|
||||
with Beads as the tracks. Wisps are steam vapors that dissipate after the work is done.
|
||||
|
||||
## Core Principle
|
||||
|
||||
@@ -15,7 +15,7 @@ which roles use them.
|
||||
| Artifact | Storage | Git Tracked | Purpose |
|
||||
|----------|---------|-------------|---------|
|
||||
| Issues | `.beads/issues.jsonl` | Yes | Permanent project history |
|
||||
| Wisps | `.beads-ephemeral/issues.jsonl` | **No** | Transient execution traces |
|
||||
| Wisps | `.beads-wisp/issues.jsonl` | **No** | Transient execution traces |
|
||||
| Digests | `.beads/issues.jsonl` | Yes | Compressed summaries of squashed wisps |
|
||||
|
||||
## Storage Architecture
|
||||
@@ -28,27 +28,27 @@ which roles use them.
|
||||
│ ├── .beads/ # CANONICAL rig beads (versioned)
|
||||
│ │ ├── issues.jsonl # Permanent issues + digests
|
||||
│ │ ├── config.yaml
|
||||
│ │ └── .gitignore # Excludes .beads-ephemeral
|
||||
│ │ └── .gitignore # Excludes .beads-wisp
|
||||
│ │
|
||||
│ └── .beads-ephemeral/ # GITIGNORED - local wisps
|
||||
│ └── issues.jsonl # In-progress ephemeral molecules
|
||||
│ └── .beads-wisp/ # GITIGNORED - local wisps
|
||||
│ └── issues.jsonl # In-progress wisp molecules
|
||||
│
|
||||
├── refinery/rig/ # Refinery's clone
|
||||
│ ├── .beads/ # Inherits from mayor/rig
|
||||
│ └── .beads-ephemeral/ # Refinery's local wisps
|
||||
│ └── .beads-wisp/ # Refinery's local wisps
|
||||
│
|
||||
├── witness/ # Witness (no clone needed)
|
||||
│ └── .beads-ephemeral/ # Witness's local wisps
|
||||
│ └── .beads-wisp/ # Witness's local wisps
|
||||
│
|
||||
└── polecats/<name>/ # Polecat worktrees
|
||||
├── .beads/ # Inherits from mayor/rig
|
||||
└── .beads-ephemeral/ # Polecat's local wisps (if using wisps)
|
||||
└── .beads-wisp/ # Polecat's local wisps (if using wisps)
|
||||
```
|
||||
|
||||
### Key Points
|
||||
|
||||
1. **`.beads-ephemeral/` is gitignored** - Never synced, never versioned
|
||||
2. **Each execution context has its own ephemeral store** - Process isolation
|
||||
1. **`.beads-wisp/` is gitignored** - Never synced, never versioned
|
||||
2. **Each execution context has its own wisp store** - Process isolation
|
||||
3. **Digests go to canonical `.beads/`** - Permanent record after squash
|
||||
4. **Wisps are deleted after squash/burn** - No accumulation
|
||||
|
||||
@@ -56,24 +56,24 @@ which roles use them.
|
||||
|
||||
Add to `.beads/.gitignore`:
|
||||
```
|
||||
.beads-ephemeral/
|
||||
.beads-wisp/
|
||||
```
|
||||
|
||||
Or add to rig-level `.gitignore`:
|
||||
```
|
||||
**/.beads-ephemeral/
|
||||
**/.beads-wisp/
|
||||
```
|
||||
|
||||
## Wisp Lifecycle
|
||||
|
||||
```
|
||||
bd mol bond <proto> --ephemeral
|
||||
bd mol bond <proto> --wisp
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────┐
|
||||
│ .beads-ephemeral/ │
|
||||
│ .beads-wisp/ │
|
||||
│ └── issues.jsonl │ ← Wisp created here
|
||||
│ └── {id, ephemeral: true, ...}
|
||||
│ └── {id, wisp: true, ...}
|
||||
└────────────┬────────────┘
|
||||
│
|
||||
┌────────┴────────┐
|
||||
@@ -95,9 +95,9 @@ These roles have repetitive/cyclic work that would accumulate without wisps:
|
||||
|
||||
| Role | Molecule | Storage Location | Squash Frequency |
|
||||
|------|----------|------------------|------------------|
|
||||
| **Deacon** | mol-deacon-patrol | mayor/rig/.beads-ephemeral/ | Per cycle |
|
||||
| **Witness** | mol-witness-patrol | witness/.beads-ephemeral/ | Per cycle |
|
||||
| **Refinery** | mol-refinery-cycle | refinery/rig/.beads-ephemeral/ | Per cycle |
|
||||
| **Deacon** | mol-deacon-patrol | mayor/rig/.beads-wisp/ | Per cycle |
|
||||
| **Witness** | mol-witness-patrol | witness/.beads-wisp/ | Per cycle |
|
||||
| **Refinery** | mol-refinery-cycle | refinery/rig/.beads-wisp/ | Per cycle |
|
||||
|
||||
### Roles That Use Regular Molecules
|
||||
|
||||
@@ -126,8 +126,8 @@ Every role using wisps must implement this pattern:
|
||||
|
||||
```go
|
||||
func patrolCycle() {
|
||||
// 1. Bond ephemeral molecule
|
||||
mol := bdMolBond("mol-<role>-patrol", "--ephemeral")
|
||||
// 1. Bond wisp molecule
|
||||
mol := bdMolBond("mol-<role>-patrol", "--wisp")
|
||||
|
||||
// 2. Execute cycle steps
|
||||
for _, step := range mol.Steps {
|
||||
@@ -140,7 +140,7 @@ func patrolCycle() {
|
||||
|
||||
// 4. Squash - REQUIRED (this is the cleanup)
|
||||
bdMolSquash(mol.ID, "--summary", summary)
|
||||
// Wisp deleted from .beads-ephemeral/
|
||||
// Wisp deleted from .beads-wisp/
|
||||
// Digest created in .beads/issues.jsonl
|
||||
|
||||
// 5. Sleep until next cycle
|
||||
@@ -157,11 +157,11 @@ For this architecture to work, Beads needs:
|
||||
### New Commands
|
||||
|
||||
```bash
|
||||
# Bond with ephemeral flag
|
||||
bd mol bond <proto> --ephemeral
|
||||
# Creates in .beads-ephemeral/ instead of .beads/
|
||||
# Bond with wisp flag (--ephemeral is an alias)
|
||||
bd mol bond <proto> --wisp
|
||||
# Creates in .beads-wisp/ instead of .beads/
|
||||
|
||||
# List ephemeral molecules
|
||||
# List wisps
|
||||
bd wisp list
|
||||
# Shows in-progress wisps
|
||||
|
||||
@@ -172,28 +172,28 @@ bd wisp gc
|
||||
|
||||
### Storage Behavior
|
||||
|
||||
| Command | With `--ephemeral` | Without |
|
||||
|---------|-------------------|---------|
|
||||
| `bd mol bond` | Creates in `.beads-ephemeral/` | Creates in `.beads/` |
|
||||
| `bd mol step` | Updates in ephemeral | Updates in permanent |
|
||||
| `bd mol squash` | Deletes from ephemeral, creates digest in permanent | Creates digest in permanent |
|
||||
| `bd mol burn` | Deletes from ephemeral | Marks abandoned in permanent |
|
||||
| Command | With `--wisp` | Without |
|
||||
|---------|---------------|---------|
|
||||
| `bd mol bond` | Creates in `.beads-wisp/` | Creates in `.beads/` |
|
||||
| `bd mol step` | Updates in wisp store | Updates in permanent |
|
||||
| `bd mol squash` | Deletes from wisp, creates digest in permanent | Creates digest in permanent |
|
||||
| `bd mol burn` | Deletes from wisp | Marks abandoned in permanent |
|
||||
|
||||
### Config
|
||||
|
||||
```yaml
|
||||
# .beads/config.yaml
|
||||
ephemeral:
|
||||
wisp:
|
||||
enabled: true
|
||||
directory: ../.beads-ephemeral # Relative to .beads/
|
||||
auto_gc: true # Clean orphans on bd init
|
||||
directory: ../.beads-wisp # Relative to .beads/
|
||||
auto_gc: true # Clean orphans on bd init
|
||||
```
|
||||
|
||||
## Crash Recovery
|
||||
|
||||
If a patrol crashes mid-cycle:
|
||||
|
||||
1. **Wisp persists in `.beads-ephemeral/`** - Provides recovery breadcrumb
|
||||
1. **Wisp persists in `.beads-wisp/`** - Provides recovery breadcrumb
|
||||
2. **On restart, agent can:**
|
||||
- Resume from last step (if step tracking is granular)
|
||||
- Or burn and start fresh (simpler for patrol loops)
|
||||
@@ -232,9 +232,10 @@ bd list --type=digest --parent=gt-deacon-patrol
|
||||
|
||||
For existing Gas Town installations:
|
||||
|
||||
1. **Add `.beads-ephemeral/` to gitignore** (immediate)
|
||||
2. **Update patrol runners to use `--ephemeral`** (as patched)
|
||||
3. **No migration of existing data** - Fresh start for ephemeral storage
|
||||
1. **Add `.beads-wisp/` to gitignore** (immediate)
|
||||
2. **Update patrol runners to use `--wisp`** (as patched)
|
||||
3. **No migration of existing data** - Fresh start for wisp storage
|
||||
4. **Optional**: Remove old `.beads-ephemeral/` directories
|
||||
|
||||
## Open Questions
|
||||
|
||||
@@ -250,5 +251,5 @@ For existing Gas Town installations:
|
||||
|
||||
## Implementation Tracking
|
||||
|
||||
- **Beads**: bd-kwjh (Wisp storage: ephemeral molecule tracking)
|
||||
- **Gas Town**: gt-3x0z.9 (mol-deacon-patrol uses ephemeral)
|
||||
- **Beads**: bd-kwjh (Wisp storage: transient molecule tracking)
|
||||
- **Gas Town**: gt-3x0z.9 (mol-deacon-patrol uses wisps)
|
||||
|
||||
Reference in New Issue
Block a user