trekoon 0.3.3 → 0.3.5

package/docs/machine-contracts.md

@@ -1,11 +1,11 @@
 # Machine contracts
 
-Use `--toon` for production agent loops. Use `--json` only when an integration
-explicitly requires JSON.
+Use `--toon` for agent loops. Use `--json` only when an integration explicitly
+requires JSON.
 
 ## Base envelope
 
-All machine responses use the same top-level shape:
+Every machine response uses the same top-level shape:
 
 ```text
 ok: true|false
@@ -16,23 +16,20 @@ metadata:
   requestId: req-<stable-id>
 ```
 
-Most subcommand identifiers are dot-namespaced, such as `task.list` or
-`sync.pull`. Root-level commands may use single-token IDs such as `help`,
-`init`, `quickstart`, `wipe`, or `version`.
+Most subcommand IDs are dot-namespaced (`task.list`, `sync.pull`). Root-level
+commands use single tokens (`help`, `init`, `quickstart`, `wipe`, `version`).
 
-Additional metadata may appear when relevant:
+Additional metadata appears when relevant:
 
 - `metadata.compatibility` when `--compat` mode is active
 - `meta.storageRootDiagnostics` when storage resolves from a non-canonical cwd
 
-## Ready queue contract
+## Ready queue
 
 ```bash
 trekoon --toon task ready --limit 3
 ```
 
-Payload fields:
-
 ```text
 ok: true
 command: task.ready
@@ -58,8 +55,6 @@ data:
 trekoon --toon dep reverse <task-or-subtask-id>
 ```
 
-Payload fields:
-
 ```text
 ok: true
 command: dep.reverse
@@ -69,22 +64,19 @@ data:
   blockedNodes[]: { id, kind, distance, isDirect }
 ```
 
-## Pagination contract for list calls
+## Pagination
 
 ```bash
 trekoon --toon task list --status todo --limit 2
 trekoon --toon task list --status todo --limit 2 --cursor 2
 ```
 
-Cursor rules:
+Rules:
 
 - `--cursor <n>` is offset-like pagination for `epic list`, `task list`, and
   `subtask list`
-- do not combine `--all` with `--cursor`
-- machine consumers should page using `meta.pagination.hasMore` and
-  `meta.pagination.nextCursor`
-
-Payload fields:
+- Don't combine `--all` with `--cursor`
+- Page using `meta.pagination.hasMore` and `meta.pagination.nextCursor`
 
 ```text
 ok: true
@@ -98,14 +90,14 @@ meta:
   pagination: { hasMore, nextCursor }
 ```
 
-## Descendant cascade update contract
+## Descendant cascade update
 
 ```bash
 trekoon --toon epic update <epic-id> --all --status done
 trekoon --toon task update <task-id> --all --status todo
 ```
 
-Success payload fields for epic/task cascade mode:
+Success:
 
 ```text
 ok: true
@@ -129,7 +121,7 @@ data:
       changedSubtasks
 ```
 
-Failure contract for blocked epic/task cascade mode:
+Failure (blocked descendants):
 
 ```text
 ok: false
@@ -157,16 +149,13 @@ data:
 
 Notes:
 
-- `subtask update <subtask-id> --all --status done|todo` is accepted, but it
-  returns the normal single-subtask `subtask.update` payload because there are
-  no descendants to traverse
-- Cascade mode is reserved for status-only close/reopen operations; combine
-  append/title/description changes in separate commands
+- `subtask update <subtask-id> --all --status done|todo` is accepted but
+  returns the normal single-subtask payload (no descendants to traverse)
+- Cascade is status-only; use separate commands for append/title/description
 
-## Batch create and expand payloads
+## Batch create and expand
 
-Trekoon uses stable batch payloads for one-shot graph creation and sibling batch
-creation commands.
+Stable batch payloads for one-shot graph creation and sibling batch commands.
 
 ### `epic create` and `epic expand`
 
@@ -175,8 +164,6 @@ trekoon --toon epic create --title "..." --description "..." --task "..."
 trekoon --toon epic expand <epic-id> --task "..."
 ```
 
-Payload fields:
-
 ```text
 ok: true
 command: epic.create | epic.expand
@@ -197,8 +184,6 @@ data:
 trekoon --toon task create-many --epic <epic-id> --task "..."
 ```
 
-Payload fields:
-
 ```text
 ok: true
 command: task.create-many
@@ -215,8 +200,6 @@ data:
 trekoon --toon subtask create-many --task <task-id> --subtask "..."
 ```
 
-Payload fields:
-
 ```text
 ok: true
 command: subtask.create-many
@@ -229,57 +212,54 @@ data:
 
 ## Sync compatibility mode
 
-Compatibility mode exists for integrations that still consume legacy sync
-command IDs:
+For integrations that still use legacy sync command IDs:
 
 ```bash
 trekoon --json --compat legacy-sync-command-ids sync status
 trekoon --toon --compat legacy-sync-command-ids sync pull --from main
 ```
 
-Behavior:
+- Default output uses canonical dotted IDs (`sync.status`)
+- Compat mode rewrites to legacy forms (`sync_status`)
+- Machine-only, valid only for `sync` commands
+- Output includes `metadata.compatibility` with migration guidance and removal
+  timing
 
-- default output uses canonical dotted IDs such as `sync.status`
-- compatibility mode rewrites sync command IDs to legacy forms such as
-  `sync_status`
-- compatibility mode is machine-only and valid only for `sync` commands
-- machine output includes `metadata.compatibility` with migration guidance and
-  removal timing
-
-## Compact envelope mode
+## Compact envelope
 
 ```bash
 trekoon --toon --compact task list
 ```
 
-When `--compact` is passed, the `metadata` key is omitted from the TOON/JSON
-envelope. The `ok`, `command`, `data`, `error`, and `meta` keys are unaffected.
+`--compact` omits the `metadata` key from the envelope. `ok`, `command`, `data`,
+`error`, and `meta` are unaffected.
 
-## Status transition error contract
+## Status transition errors
 
-Invalid status transitions return:
+Invalid transitions return:
 
 ```text
 ok: false
 error:
   code: status_transition_invalid
   message: "cannot transition <kind> <id> from '<from>' to '<to>'"
-  details:
-    entity: epic|task|subtask
-    id: <entity-id>
-    fromStatus: <current-status>
-    toStatus: <attempted-status>
-    allowedTransitions[]: <valid targets from current status>
+data:
+  entity: epic|task|subtask
+  id: <entity-id>
+  fromStatus: <current-status>
+  toStatus: <attempted-status>
+  allowedTransitions[]: <valid targets from current status>
 ```
 
-## Epic progress contract
+Transition details are in `data`, not `error.details`. `error` only has `code`
+and `message`.
+
+## Epic progress
 
 ```bash
 trekoon --toon epic progress <epic-id>
 ```
 
-Payload fields:
-
 ```text
 ok: true
 command: epic.progress
@@ -295,14 +275,12 @@ data:
   nextCandidate: { id, title } | null
 ```
 
-## Task done enhanced contract
+## Task done (enhanced)
 
 ```bash
 trekoon --toon task done <task-id>
 ```
 
-Payload fields:
-
 ```text
 ok: true
 command: task.done
@@ -324,14 +302,12 @@ data:
     blockedCount
 ```
 
-## Suggest command contract
+## Suggest
 
 ```bash
 trekoon --toon suggest [--epic <epic-id>]
 ```
 
-Payload fields:
-
 ```text
 ok: true
 command: suggest
@@ -352,9 +328,9 @@ data:
     pendingConflicts
 ```
 
-## Owner field in update payloads
+## Owner field in updates
 
-Task and subtask update payloads now include `owner` in their event data:
+Task and subtask update payloads include `owner`:
 
 ```text
 data:
@@ -366,6 +342,202 @@ data:
 The board API accepts `owner` on `PATCH /api/tasks/{id}` and
 `PATCH /api/subtasks/{id}`.
 
+## Sync resolve dry-run
+
+```bash
+trekoon --toon sync resolve <conflict-id> --use ours|theirs --dry-run
+```
+
+```text
+ok: true
+command: sync.resolve
+data:
+  conflictId: <conflict-id>
+  resolution: ours|theirs
+  entityKind: epic|task|subtask
+  entityId: <entity-id>
+  fieldName: <conflicted field>
+  oursValue: <current DB value>
+  theirsValue: <source branch value>
+  wouldWrite: <value that would be written>
+  dryRun: true
+```
+
+No mutation occurs. The conflict stays pending.
+
+## Sync batch resolve
+
+```bash
+trekoon --toon sync resolve --all --use ours|theirs [--entity <id>] [--field <name>]
+```
+
+```text
+ok: true
+command: sync.resolve
+data:
+  resolution: ours|theirs
+  resolvedCount: <number>
+  resolvedIds: [<conflict-id>, ...]
+  filters:
+    entity: <entity-id> | null
+    field: <field-name> | null
+```
+
+Human-mode note: `sync resolve --all --use theirs` asks for confirmation before
+execution. Cancellation returns `error.code: cancelled` with the requested
+`resolution`, `cancelled: true`, and the normalized `filters`.
+
+When confirmation is required, execution is bound to the previewed conflict ID
+set. If another process resolves one of those conflicts before the confirmed
+write happens, the command fails with `error.code: conflict_set_changed`
+instead of partially resolving a drifted batch.
+
+## Sync batch resolve dry-run
+
+```bash
+trekoon --toon sync resolve --all --use ours|theirs [--entity <id>] [--field <name>] --dry-run
+```
+
+```text
+ok: true
+command: sync.resolve
+data:
+  resolution: ours|theirs
+  matchedCount: <number>
+  matchedIds: [<conflict-id>, ...]
+  filters:
+    entity: <entity-id> | null
+    field: <field-name> | null
+  dryRun: true
+```
+
+No mutation occurs. Returns `no_matching_conflicts` error when no pending
+conflicts match the filters.
+
+## Sync resolve hardening errors
+
+Recent `sync.resolve` hardening added explicit machine-visible failure modes for
+race conditions and invalid persisted conflict targets.
+
+### Single resolve — cancelled
+
+Returned in human mode when the user rejects or times out a confirmation prompt.
+Single-conflict prompts only appear for `--use theirs`.
+
+```text
+ok: false
+command: sync.resolve
+data:
+  conflictId: <conflict-id>
+  resolution: ours|theirs
+  cancelled: true
+error:
+  code: cancelled
+  message: "Resolution cancelled by user."
+```
+
+### Batch resolve — cancelled
+
+Returned in human mode when the user rejects or times out the batch prompt.
+
+```text
+ok: false
+command: sync.resolve
+data:
+  resolution: ours|theirs
+  cancelled: true
+  filters:
+    entity: <entity-id> | null
+    field: <field-name> | null
+error:
+  code: cancelled
+  message: "Batch resolution cancelled by user."
+```
+
+### Single resolve — already_resolved
+
+Returned when a conflict is still pending at preview time but another process
+resolves it before the confirmed write happens.
+
+```text
+ok: false
+command: sync.resolve
+data:
+  conflictId: <conflict-id>
+  resolution: ours|theirs
+  reason: already_resolved
+error:
+  code: already_resolved
+  message: "Conflict '<conflict-id>' already resolved."
+```
+
+### Resolve write hardening errors
+
+These surface as domain failures when persisted conflict metadata no longer maps
+to a valid writable target.
+
+```text
+ok: false
+command: sync.resolve
+data:
+  reason: unsupported_entity_kind | disallowed_field | row_not_found
+  ...details
+error:
+  code: unsupported_entity_kind | disallowed_field | row_not_found
+  message: <stable human-readable message>
+```
+
+Per-code details:
+
+- `unsupported_entity_kind`
+  - `data.entityKind`
+- `disallowed_field`
+  - `data.tableName`
+  - `data.fieldName`
+- `row_not_found`
+  - `data.tableName`
+  - `data.entityKind`
+  - `data.entityId`
+
+## Sync batch resolve — no_matching_conflicts error
+
+Applies to both the execute and dry-run variants of `sync resolve --all`.
+Returned when the given filters match zero pending conflicts.
+
+```text
+ok: false
+command: sync.resolve
+data:
+  filters:
+    entity: <entity-id> | null
+    field: <field-name> | null
+  reason: no_matching_conflicts
+error:
+  code: no_matching_conflicts
+  message: "No pending conflicts match the given filters."
+```
+
+## Sync batch resolve — conflict_set_changed error
+
+Returned in human mode when batch confirmation was based on one pending conflict
+set but one or more of those conflicts were resolved before the confirmed write
+was applied.
+
+```text
+ok: false
+command: sync.resolve
+data:
+  filters:
+    entity: <entity-id> | null
+    field: <field-name> | null
+  expectedConflictIds: [<conflict-id>, ...]
+  availableConflictIds: [<conflict-id>, ...]
+  reason: conflict_set_changed
+error:
+  code: conflict_set_changed
+  message: "Pending conflicts changed before batch resolution could be applied."
+```
+
 ## Related docs
 
 - [Quickstart](quickstart.md)