@jjanczur/tyran 0.1.12 → 0.1.13

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -11,7 +11,7 @@
11
11
  {
12
12
  "name": "tyran",
13
13
  "description": "A task conductor for Claude Code: multi-agent orchestration with an enforced evidence contract, repo-specific learning, and update-safe local evolution.",
14
- "version": "0.1.12",
14
+ "version": "0.1.13",
15
15
  "source": "./",
16
16
  "author": {
17
17
  "name": "Jacek Janczura",
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "tyran",
3
- "version": "0.1.12",
3
+ "version": "0.1.13",
4
4
  "description": "A task conductor for Claude Code: multi-agent orchestration with an enforced evidence contract, repo-specific learning, and update-safe local evolution.",
5
5
  "author": {
6
6
  "name": "Jacek Janczura",
package/CHANGELOG.md CHANGED
@@ -1,5 +1,50 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.13 — 2026-08-13
4
+
5
+ ### Six concurrent decisions, two ids
6
+
7
+ `append` took the write lock; issuing the `D-<n>` or `F-<n>` a caller omitted
8
+ happened before it, in the CLI. Issuing an id is read-compute-write, so every
9
+ concurrent writer read the same journal, computed the same next number, and
10
+ then serialized on the lock to write it. Measured on a fresh journal, seven
11
+ runs of six simultaneous `decision` appends: **1 to 4 distinct ids for 6
12
+ events**, and in the worst run all six carried the same id. Ids are how the
13
+ ledger references itself — "see D-2" —
14
+ in a file that is never rewritten, so every collision is ambiguous
15
+ permanently: neither `validate` nor the projections can say which `D-2` a
16
+ later event meant, and the premise of the whole design is many agents writing
17
+ one ledger at once.
18
+
19
+ The id is now issued inside the lock, from the snapshot that call has already
20
+ read for the timestamp clamp and the spawn guard — no second read per append,
21
+ which a long journal would pay for on every event. The contract is unchanged:
22
+ an explicit `data.id` still wins, `"id":""` is still treated as absent, and
23
+ only `decision` and `finding` are issued one. The same six-process race now
24
+ measures 6 distinct ids for 6 events, and eight genuinely concurrent
25
+ processes pin it in the suite.
26
+
27
+ The exported `append()` moved with the CLI, not behind it: before this release
28
+ a `decision` without `data.id` was rejected outright — `invalid event: data.id
29
+ is required for ev "decision"` — so every programmatic caller had to compute an
30
+ id first and then carry it across exactly the gap this release closes. Omitting
31
+ `data.id` is now the safe call rather than an error.
32
+
33
+ What is atomic is exactly the ids `append` ISSUES — `decision` and `finding`,
34
+ where `data.id` was omitted or empty: two of those, concurrent, can no longer
35
+ be handed one number. Nothing else moved. `next-id` previews a value while
36
+ holding nothing, so an id read there and appended later still loses to any
37
+ writer that appended in between — both journal doc surfaces say so, and a
38
+ caller that can let `append` issue the id should. An explicit `data.id` is
39
+ written verbatim and stays the caller's to keep unique: a journal whose three
40
+ `decision` events all carry `D-2` validates `ok`. `ticket.created` is
41
+ deliberately outside the issued set — a ticket id comes from the plan, which
42
+ numbers its own stories — so there is no atomic path for a `T-` id at all, and
43
+ `skills/run/SKILL.md` now says the conductor is the single writer for ticket
44
+ creation. And an id at or past 2^53 saturates `max+1`: seeded with
45
+ `D-9007199254740992`, `append` issues that same number to every decision after
46
+ it, and a 400-digit id yields `D-Infinity` — arithmetic byte-identical to the
47
+ previous release, named here rather than changed here.
3
48
  ## 0.1.12 — 2026-08-13
4
49
 
5
50
  ### The board: every ticket in a lane, every question in front of you
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@jjanczur/tyran",
3
- "version": "0.1.12",
3
+ "version": "0.1.13",
4
4
  "description": "Command-line scripts for the Tyran task conductor (doctor, journal, schema, and repo tooling) for CI and terminals outside Claude Code. Installing this package does NOT install the Claude Code plugin — add that separately with `/plugin marketplace add jjanczur/tyran` inside Claude Code.",
5
5
  "type": "module",
6
6
  "engines": {
@@ -122,6 +122,14 @@ export const CAPPED_DATA_KEYS = Object.freeze({ detail: 2000, claim: 2000, proof
122
122
  */
123
123
  const q = (value) => escapeInvisible(String(value));
124
124
 
125
+ /**
126
+ * A `data` payload of the shape the envelope requires. Arrays are excluded on
127
+ * purpose: they are objects to `typeof`, they accept string properties, and
128
+ * anything that ADDS a key to one would turn a rejected event into a written
129
+ * one of a shape the caller never wrote.
130
+ */
131
+ const isDataObject = (data) => typeof data === 'object' && data !== null && !Array.isArray(data);
132
+
125
133
  /** Validate a single event object. Returns [] when valid, else error strings. */
126
134
  export function validateEvent(event) {
127
135
  const errors = [];
@@ -143,7 +151,7 @@ export function validateEvent(event) {
143
151
  if (typeof event.actor !== 'string' || event.actor.length === 0) {
144
152
  errors.push('actor must be a non-empty string');
145
153
  }
146
- if (typeof event.data !== 'object' || event.data === null || Array.isArray(event.data)) {
154
+ if (!isDataObject(event.data)) {
147
155
  errors.push('data must be a JSON object (may be empty)');
148
156
  } else if (DATA_REQUIRED[event.ev]) {
149
157
  for (const key of DATA_REQUIRED[event.ev]) {
@@ -463,6 +471,31 @@ function appendUnderLock(file, event, preread = null) {
463
471
  if (lastTs && Date.parse(ts) < Date.parse(lastTs)) ts = lastTs;
464
472
  }
465
473
  const stamped = { ...event, ts };
474
+ // An id the caller omitted is ISSUED, not demanded — and issued HERE, from
475
+ // the same snapshot this write is about to extend. Issuing one is
476
+ // read-compute-write, so anywhere outside the lock every concurrent writer
477
+ // reads the same journal, computes the same "next" number, and then queues up
478
+ // to write it: measured over seven runs, six concurrent `decision` appends
479
+ // against one journal issued between 1 and 4 distinct ids for 6 events.
480
+ // Nothing detects that later — history is append-only, so "see D-2" stays
481
+ // ambiguous forever.
482
+ //
483
+ // `skills/run/SKILL.md` is emphatic that IDs never come from memory, because
484
+ // after a compaction memory hands out the same number twice — and `append`
485
+ // once REJECTED a missing `data.id`, leaving the conductor to remember a
486
+ // separate `next-id` call. Measured in the field: 12 decision IDs
487
+ // hand-assigned from memory in one initiative, which is the exact failure the
488
+ // rule names, with nothing objecting. A rule in prose loses to a mechanism
489
+ // that makes the mistake impossible.
490
+ //
491
+ // An explicit id still wins — but `"id":""` is not explicit: a conductor
492
+ // recovering from next-id's usage error supplied exactly that, three times,
493
+ // and the ledger kept three permanently blank ids nothing can reference.
494
+ const issuePrefix = ID_ISSUED_FOR[stamped.ev];
495
+ if (issuePrefix !== undefined && isDataObject(stamped.data) && (stamped.data.id === undefined || stamped.data.id === '')) {
496
+ // a fresh object: the `data` the caller passed in stays the caller's
497
+ stamped.data = { ...stamped.data, id: nextIdFrom(read().events, issuePrefix) };
498
+ }
466
499
  const errors = validateEvent(stamped);
467
500
  if (errors.length > 0) {
468
501
  throw new Error('invalid event: ' + errors.join('; '));
@@ -506,6 +539,9 @@ function appendUnderLock(file, event, preread = null) {
506
539
  *
507
540
  * `spawn` additionally must not duplicate an agent name that is still open
508
541
  * (ADR-18) — see `duplicateSpawnMessage` for how to get unstuck.
542
+ *
543
+ * Returns the event as written, including any `data.id` issued for it: the
544
+ * CLI prints that, and it is the only place the issued id is reported.
509
545
  */
510
546
  export function append(file, event) {
511
547
  mkdirSync(dirname(resolve(file)), { recursive: true });
@@ -631,14 +667,15 @@ export function validateJournal(file) {
631
667
  }
632
668
 
633
669
  /**
634
- * Next free ID for a prefix, derived from the journal — never from memory.
635
- * Scans data.id fields shaped `<PREFIX>-<number>` and returns max+1.
670
+ * Next free ID for a prefix, over events already read. Separate from `nextId`
671
+ * only so the locked append path can issue an id from the snapshot it is
672
+ * holding: re-reading the file there would be a second full read on every
673
+ * append, which a long journal pays for on every event.
636
674
  */
637
- export function nextId(file, prefix) {
675
+ function nextIdFrom(events, prefix) {
638
676
  if (!/^[A-Za-z][A-Za-z0-9]*$/.test(prefix)) {
639
677
  throw new Error(`invalid id prefix "${prefix}" — use letters/digits, starting with a letter`);
640
678
  }
641
- const { events } = readJournal(file);
642
679
  let max = 0;
643
680
  const re = new RegExp(`^${prefix}-(\\d+)$`);
644
681
  for (const e of events) {
@@ -648,6 +685,19 @@ export function nextId(file, prefix) {
648
685
  return `${prefix}-${max + 1}`;
649
686
  }
650
687
 
688
+ /**
689
+ * Next free ID for a prefix, derived from the journal — never from memory.
690
+ * Scans data.id fields shaped `<PREFIX>-<number>` and returns max+1.
691
+ *
692
+ * A PREVIEW, not a reservation: nothing is written and no lock is held, so an
693
+ * id read here and appended later collides with any writer that appended in
694
+ * between. `append` issues ids under its own write lock; a caller that can
695
+ * let it do so has no window at all.
696
+ */
697
+ export function nextId(file, prefix) {
698
+ return nextIdFrom(readJournal(file).events, prefix);
699
+ }
700
+
651
701
  /** Latest checkpoint + still-open leases — the resume surface. */
652
702
  export function tail(file) {
653
703
  const { events } = readJournal(file);
@@ -744,23 +794,9 @@ function main() {
744
794
  const [file, ev, init] = rest;
745
795
  if (!file || !ev || !init) throw new UsageError();
746
796
  const data = flags.data ? JSON.parse(flags.data) : {};
747
- // An id the caller omitted is ISSUED, not demanded.
748
- //
749
- // `skills/run/SKILL.md` is emphatic that IDs never come from memory,
750
- // because after a compaction memory hands out the same number twice —
751
- // and then `append` REJECTED a missing `data.id` and left the conductor
752
- // to remember a separate `next-id` call. Measured in the field: 12
753
- // decision IDs hand-assigned from memory in one initiative, which is
754
- // the exact failure the rule names, with nothing objecting.
755
- //
756
- // A rule in prose loses to a mechanism that makes the mistake
757
- // impossible. This is that mechanism, and an explicit id still wins —
758
- // but `"id":""` is not explicit: a conductor recovering from next-id's
759
- // usage error supplied exactly that, three times, and the ledger kept
760
- // three permanently blank ids nothing can reference.
761
- if (ID_ISSUED_FOR[ev] !== undefined && (data.id === undefined || data.id === '')) {
762
- data.id = nextId(file, ID_ISSUED_FOR[ev]);
763
- }
797
+ // An omitted id is issued by `append`, inside its write lock, and comes
798
+ // back on the event this prints — issuing one out here would be outside
799
+ // that lock, which is where concurrent writers hand out one id twice.
764
800
  const written = append(file, { ev, init, actor: flags.actor ?? 'conductor', data });
765
801
  console.log(emit(written));
766
802
  return;
@@ -158,9 +158,14 @@ open one.
158
158
  away from having never happened.
159
159
  - **IDs never come from memory** — omit `id` from a `decision` event's
160
160
  `--data` (or leave it empty) and `append` issues the next one itself.
161
+ `append` issues it under the same lock it writes with, so two concurrent
162
+ appends can no longer be handed one number — prefer omitting `id`
163
+ wherever you do not need the value beforehand.
161
164
  `journal.mjs next-id <file> <prefix>` exists to preview a value ahead of
162
165
  time (prefix `D` → `D-7`); it is not a required preliminary step before
163
- `append`. After a compaction, memory hands out the same number twice.
166
+ `append`, and it holds nothing — an id read there and appended later
167
+ still loses to any writer that appended in between. After a compaction,
168
+ memory hands out the same number twice.
164
169
  - **Authorizations and stops are `decision` events.** What you may do
165
170
  without asking, and the CLOSED list of situations where you halt, live
166
171
  in the journal with the date and the operator's own words. Outside that