Home

rosetta

Two documents that say the same thing will, sooner or later, say different things, and this package exists for that day.

rosetta (the rosetta-core package) is a small Python tool that keeps a compact machine-readable prompt packet and a human-readable Markdown document in sync, and that stops with a conflict, instead of guessing, when both have changed.

简体中文： rosetta-core 为同一份提示词维护两种形式，给模型读的紧凑数据包（.cpn）和给人读的 Markdown 文档；一方改动后 rosetta sync 同步另一方，两边都改了则报告冲突而不自动合并。

繁體中文： rosetta-core 為同一份提示詞維護兩種形式，給模型讀的精簡資料包（.cpn）與給人讀的 Markdown 文件；一方變更後 rosetta sync 同步另一方，兩邊都改了則回報衝突而不自動合併。

At a glance

What it is	A synchronizer for a prompt packet (.cpn) and its Markdown twin, with hash-based conflict detection and JSON Schema validation
Language	Python 3.11 or later (run here on 3.12.10); one dependency, jsonschema
Tests	50 tests, all passing, no network or API key needed
Status	Version 0.1.0. One artifact kind (PacketSpec) is implemented; the ProgramSpec kind in the design notes is not. Token savings are not measured
Licence	Apache-2.0

Why it matters

A prompt that matters tends to exist twice, once as the compact text a model reads and once as the explanation a person reads, and the two drift apart the first time someone fixes one and forgets the other. rosetta makes the drift visible and refuses to resolve it silently: an edit to one copy flows to the other, and an edit to both stops the run and names the fields that differ. The result is a small tool with a narrow promise, which is why its limits can be stated exactly.

Skills shown

• State-machine design for synchronization: four outcomes (bootstrap, one-way update in either direction, conflict, no-op) decided from two stored hashes.
• Canonical serialization: sorted keys, a fixed float format, LF endings, and a trailing newline, so that equal meaning gives equal bytes.
• Schema validation with a deliberate bridge: packet values are always text, so numbers are coerced to the type the JSON Schema declares before validation.
• A fallback path with explicit ordering: the loader serves the packet when it is valid and the Markdown only as a full replacement.
• Test design: 50 tests that exercise every sync outcome, both fallback conditions, and the schema coercion.
• Scoping and honest limits, including a verified case where sync notices nothing.

Results

All 50 tests pass. The example artifact in examples/rosetta_build/ was run through the command line for this wiki, and the outputs below are what the tool printed.

Action	Output	Exit code
Edit DECISION_COUNT=3 to 4 in the packet, then rosetta sync	sync: machine-to-human	0
rosetta validate afterward	valid	0
Edit the same field in both the packet and the Markdown, then rosetta sync	CONFLICT: conflicting fields: DECISION_COUNT	1
Edit only rosetta_build.fields.json, then rosetta sync	sync: no-op	0

The last row is a limit and not a feature: an edit made only to the fields store goes unnoticed, and Limits and Next Steps says why. No measurement of token savings exists; the companion benchmark, rosetta-bench, was built to test that claim and has not been run against a real model.

Pages

• Getting Started: install, run the tests, change a field and sync.
• How It Works: the files, the sync decision, and one edit followed through.
• Evidence: tests, a command-line session, and known failures.
• Design Decisions: why the store, the hashes, and the refusal to merge.
• Limits and Next Steps: what the tool does not do.