Extract base substrate from Claude Code module

[Meldrey]

PR: Extract base substrate from Claude Code module

The problem

Every flex module — regardless of what it ingests — must declare substrate: "claude_code" and inherit CC-specific tables, enrichment, and validation. A Matrix chat module gets _edges_tool_ops and _types_message tables it will never write to. A Telegram module would get _edges_delegations for agent spawns that don't exist in chat history.

The generic storage layer (chunks, sources, content, FTS) is tangled with Claude Code's domain-specific extensions (tool operations, message threading, agent delegation, file bodies). New module authors must either accept the baggage or work around it.

The fix

Separate the generic flex storage contract from CC-specific extensions. Four changes, zero breakage:

1. Split _ensure_core_tables() → _ensure_base_tables() + _ensure_cc_tables()

The base tables are the shared contract any module needs:

• _raw_chunks, _raw_sources, _edges_source — core chunk storage
• _meta, _presets — cell metadata and query presets
• chunks_fts — full-text search

The CC tables are domain-specific:

• _edges_tool_ops — tool call metadata (tool_name, target_file, success)
• _types_message — message threading (role, sidechain, branch)
• _edges_delegations — agent spawn tracking
• _edges_soft_ops, _file_body_index, _types_file_body

_ensure_core_tables() remains as a backward-compatible wrapper.

2. Extract insert_base_chunk() from insert_chunk_atom()

insert_base_chunk(conn, chunk, source_type) writes only to _raw_chunks and _edges_source. Any module can call this without CC extension tables.

insert_chunk_atom() calls insert_base_chunk() internally, then writes CC-specific tables. No behavior change.

3. Rename bootstrap_claude_code_cell() → bootstrap_cell(substrate=...)

New substrate parameter:

• substrate='claude_code' (default) — base + CC + content + SOMA. Existing behavior.
• substrate='base' — base + content only. Clean generic cell.

bootstrap_claude_code_cell remains as an alias.

4. Make run_from_spec() substrate-aware

• Reads substrate from the module spec (defaults to 'claude_code')
• Applies enrichment stubs conditionally (base stubs vs full CC stubs)
• Runs CC enrichment pipeline only for CC substrate
• Validates against the appropriate contract (base vs coding-agent)

New exports: BASE_ENRICHMENT_STUBS, validate_base_cell(), REQUIRED_BASE_TABLES.

What this enables

A non-coding-agent module can now declare:

MODULE = {
    "cell_type": "matrix",
    "substrate": "base",
    "views_from": ("matrix",),
    "presets_from": ("matrix",),
    ...
}

And get a clean cell with only the tables it needs. Its worker calls insert_base_chunk() instead of insert_chunk_atom() and creates its own domain-specific extension tables.

Backward compatibility

Existing code	Status
from ... import bootstrap_claude_code_cell	Works (alias)
from ... import insert_chunk_atom	Works (calls insert_base_chunk internally)
substrate: "claude_code" in any module spec	Works (default)
ENRICHMENT_STUBS import	Works (base + CC combined)
validate_coding_agent_cell()	Works (unchanged)

Tested

• Existing claude_code cell (134K chunks, 2.4K sources) queries correctly
• Existing hermes_agent cell queries correctly
• New substrate='base' cell creates with 7 base tables, zero CC tables
• Base contract validation passes
• All imports resolve, alias identity confirmed