Packages
A minimal kernel for preserving user edits across upstream regeneration cycles
Current section
Files
Jump to
Current section
Files
README.md
# Tamale
[](https://zread.ai/SynapticStrings/Tamal)
zongzi isn't 🫔 — this one is.
A minimal kernel for preserving **user edits across upstream regeneration
cycles**. What the user writes is a patch relative to an upstream base;
the base regenerates; after each regeneration every patch must be judged
*still applicable / applicable after transform / dead*. That is a
three-way merge with an explicit merge-base — the same problem `git
patch + base + transform rules` solves — and this kernel is its smallest
honest answer.
Tamale is a greenfield successor designed from a review of
[zongzi](https://github.com/SynapticStrings/Zongzi): it keeps zongzi's two-phase survival doctrine and
compresses its Anchor + Intervention + Timeline subsystems into a single
transport mechanism.
## Quick Start
Tamale separates two questions:
1. *Did the edited thing survive the upstream change?*
2. *Does the edit still apply to the new content?*
Let's Start with an upstream document.
```elixir
source = %{s1: "Hello world."}
{:ok, space} = Space.new([:s1])
```
The user creates a translation for the original text(`s1`):
```elixir
anchor = %Ordinal{
refs: [:s1],
at_version: space.version
}
{:ok, patch} =
Patch.new(
source.s1,
%{lang: :zh, text: "你好，世界。"}
)
```
At this point, the patch means:
> "Apply `你好，世界。` to `s1`, but only if `s1` is still based on `Hello world.`."
Suppose the upstream generator splits `s1`:
```elixir
{:ok, space} =
Space.apply_op(
space,
%Tamale.Op.Split{
id: :s1,
children: [:s1, :s1b]
}
)
source = %{
s1: "Hello",
s1b: " world."
}
```
The important part is that the **identity** of the first child survives the split:
```text
s1
│
├── s1 ← original identity survives
└── s1b
```
Then transport the user's anchor.
```elixir
{:ok, anchor} = Transport.transport(anchor, space)
```
The anchor survived the structural change, so the translation is still attached to `s1`.
Dive to 2nd phase, check whether the patch still applies.
```elixir
case Patch.resolve(patch, source.s1) do
{:ok, payload} ->
IO.puts("APPLY: #{payload.text}")
{:conflict, :base_changed} ->
IO.puts("CONFLICT: the source changed")
{:error, reason} ->
IO.puts("ERROR: #{inspect(reason)}")
end
```
The result is:
```text
CONFLICT: the source changed
```
This is intentional.
The anchor survived the split, but `s1` is no longer the text the user originally edited:
```text
base: "Hello world."
current: "Hello"
```
So Tamale reports:
```text
structural survival → yes
semantic survival → no
```
That distinction is the core of Tamale's two-phase survival model.
## Architecture
### Layering
Tamale couldn't works without your task, so it needs combination with kernel, policy & adapters/host.
```plain
kernel : Space(id, order, version) · Op · Anchor/Transport · Patch ← this package
policy : relocation choice, clip-vs-conflict, digest chunk granularity ← callbacks
adapters : Tempo→Warp · curve samplers · windowing · score theory · engine bindings
```
The kernel holds no domain data and no engine contract.
### Core Concepts
Tamale has four small building blocks:
* **`Tamale.Space` — where things live**
A `Space` is the versioned world being edited. It gives stable ids
to objects and records every change as an `Op` in a linear log.
```elixir
{:ok, space} = Space.new([:a, :b, :c])
```
After an edit, the space gets a new version and the edit is added to
its log. The log is what lets Tamale move old anchors through later
changes.
* **`Tamale.Op` — what changed**
An `Op` describes an edit explicitly:
```text
Insert Delete Split Merge Move Retime
```
Tamale works from these edit intents rather than trying to infer
changes by comparing two states.
A raw `diff(old, new)` adapter exists for callers that only have
snapshots, but it is a fallback rather than the kernel's source of
truth.
* **`Tamale.Anchor` + `Tamale.Transport` — where an edit should go**
A patch is attached to an `Anchor`, not directly to a particular
version of the source.
When the source changes, `Transport` moves that anchor through the
`Space`'s op log:
```elixir
{:ok, anchor}
{:clip, covered, lost}
{:ambiguous, candidates}
{:undefined, reason}
```
Tamale supports three anchor shapes:
* `Ordinal` — identifies objects and their structural position.
* `Metric` — identifies coordinate intervals and moves through a
`Tamale.Warp`.
* `Relative` — identifies an interval relative to another object.
Coordinates use exact rationals (`Tamale.Coord`); floats are rejected.
* **`Tamale.Patch` — whether the edit still applies**
A patch is a payload together with the digest of the content it was
created from:
```text
patch = (base_digest, payload)
```
Resolving a patch is deliberately strict:
```elixir
{:ok, payload}
{:conflict, :base_changed}
```
If the current content has the same digest as the original base, the
patch applies. Otherwise, it conflicts.
There is no fuzzy matching or tolerance knob in the kernel.
#### How they fit together
The whole flow is:
```text
Op
│
▼
Space ──────► new version
│
│ transport
▼
Anchor
│
│ locate
▼
Patch
│
│ resolve
▼
apply / conflict
```
This gives Tamale two deliberately separate questions:
```text
1. Did the edited location survive the upstream change?
→ Anchor + Transport
2. Does the edit still apply to the new content?
→ Patch + Digest
```
That separation is the core of Tamale's two-phase survival model.
## Invariants
- Edit intent is first-class; heuristics live only in the `diff` fallback.
- Structural survival (transport, at edit time) and semantic survival
(`Patch.resolve`, at render time) are separate phases.
- No tolerance knobs; conflicts surface explicitly.
- Single writer: one linear log. (Offline/collaboration would
reintroduce tombstones — as a deliberate extension, not a heuristic.)
- Kernel conventions, not policy: a split's first child inherits the
parent id; a merge's `into` is `hd(ids)`; ids are never reused.
## Status: scaffold
Working and tested:
- `Space` op application with validation, versioning, log, truncation
- `Transport` for all three anchor shapes:
- `Ordinal` (delete/split/merge/move/retime, conjunctive refs,
head-state adjacency, `boundary_merged` when a merge collapses an
`adjacent?` anchor's refs, truncated/future versions)
- `Metric` (warp-fold transport; warps come from a Caller provider —
the kernel holds no spans; partial survival surfaces as first-class
`{:clip, covered, lost}`; the folded warp is available via
`Transport.fold_warp/4` for `ChannelAdapter.warp_payload/2`)
- `Relative` (Ordinal-rule host transport; absolute interval derived
via `Anchor.project/3`; offsets may be negative and overhang the
host)
- `Warp` algebra over exact rational coordinates (`Tamale.Coord`):
`from_segments/1` (monotonicity-validated assembly), `compose/2`,
`invert/1`, `map_interval/2` — a 1/3 tempo produces thirds, never
float dust
- `Patch` digest resolve over canonical digests (`Tamale.Digest` —
floats/structs/tuples rejected; atom keys encoded by name; spec +
worked examples in `docs/spec/canonical-digest.md`)
- `ChannelAdapter.warp_payload/2` — the single channel-adapter callback
- JSON conformance vectors (`test/conformance/`, format v1): 40 scenarios
across space/ordinal/metric/relative/digest/resolve, seeded from
zongzi's `GOLDEN_SCENARIOS.md` including the deliberate semantic flips
(G-AN-02 merge, G-INT-05 seconds anchor). Coordinates travel as
integers or `"num/den"` strings; the metric family pins exact rational
arithmetic (thirds, composed fractional scales). The Elixir
implementation is now the reference runner; other languages implement
against the vectors.
Guides and specs:
- `docs/zh/guide/caller-guide-zh.md` — the Caller orchestration contract
(also the equinox migration manual): trio layout, edit-loop op
conventions, two-phase survival, warp/digest obligations, engine
protocol requirements, self-check list
- `docs/spec/canonical-digest.md` — portable digest spec v1
Done (implemented in the downstream `coconut` editor core):
- Warp-provider reference example — `Coconut.Edit.WarpProvider`
constructs tick/frame warps from tempo maps and span tables, including
the `T_new ∘ W_tick ∘ T_old⁻¹` composition for frame-addressed,
score-following anchors.
- `diff(old, new)` fallback adapter — `Coconut.Edit.Diff` infers the
six canonical ops from raw state pairs for import/reload/collaboration.
Not yet:
- Chunked digest helper — the pattern is settled
(`docs/decisions/0006`); an optional helper module may follow when
projection scale makes monolithic digest materialization expensive.
Design decisions: `docs/decisions/`.
## License
MIT (same as zongzi).