dsh-ring 0.1.0 → 0.1.1

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.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,20 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.1.1
4
+
5
+ - Make `expired` terminal for direct decisions: `ack()` and `resolve()` on an
6
+ expired case now throw `E_STATE` instead of moving it back to an active state.
7
+ The only in-place way to reopen a case is an explicit `escalate(id, { to })`
8
+ late page; otherwise raise a new case. A case decided after it expired is
9
+ still marked `late`.
10
+ - Keep `tick()` from ever re-escalating a `resolved` case (already enforced;
11
+ now covered by a regression test), and never revive a closed case.
12
+ - Make receipts immutable evidence: stored entries are frozen, append-only and
13
+ never rewritten; every read and every `tick()` result returns defensive
14
+ copies, so mutating a returned receipt cannot change the ledger.
15
+ - Add state-machine tests for expired ack/resolve refusal, late pages, and
16
+ resolved-case ticks.
17
+
3
18
  ## 0.1.0
4
19
 
5
20
  - Add `RingService` at `ctx.ring`: `raise`, `tick`, `ack`, `escalate`, `resolve`,
package/README.md CHANGED
@@ -3,7 +3,7 @@
3
3
  > **Approval SLA, not a notification app.** Raise a blocking approval, page on a
4
4
  > fixed t0–t3 schedule, stop on ack, record every step as a local receipt.
5
5
 
6
- **Status: 0.1.0 — SLA state machine MVP.** Cases advance only through explicit
6
+ **Status: 0.1.1 — SLA state machine MVP.** Cases advance only through explicit
7
7
  `tick(now)` calls, and every delivery is recorded locally. **No notification is
8
8
  actually sent.** IM (webhook) and voice channels are planned for **0.2.0**.
9
9
  **v0 only acknowledges; it never approves remotely** — ack is not approval, and
@@ -44,7 +44,7 @@ const receipts = ctx.ring.receipts(kase.id)
44
44
  | `tick(now?)` | Advance every open case to `now`. Returns `{ now, receipts, cases }`; at most one catch-up escalation per case per call. |
45
45
  | `ack(id, { by })` | Claim the case (`acked`), stop escalation, keep a receipt. |
46
46
  | `escalate(id, { to? })` | Move to `escalated` at a chain level (`1`, `"t2"`) or record a free-form target label. Omit `to` to advance one level. |
47
- | `resolve(id, { decision })` | Record the human outcome (`resolved`). A decision after expiry is kept and marked `late`. |
47
+ | `resolve(id, { decision })` | Record the human outcome (`resolved`). An expired case must be re-paged first; a decision recorded after expiry is marked `late`. |
48
48
  | `list({ status? })` | Case snapshots, optionally filtered by one status or an array of statuses. |
49
49
  | `receipts(id)` | All receipts for a case, in insertion order. |
50
50
 
@@ -62,14 +62,18 @@ replacement when passed to `raise`; entries may be numbers (`afterMs`) or
62
62
  pending --t0--> notified --ack--> acked --decision--> resolved
63
63
  | | |
64
64
  +--t1..t3------> escalated ------+ (ack stops further escalation)
65
- any open state --expiresAt--> expired --late decision--> resolved
65
+ any open state --expiresAt--> expired --escalate(to)--> escalated --decision--> resolved
66
66
  ```
67
67
 
68
68
  - `expired` and `resolved` are not touched by later ticks.
69
69
  - Acking, escalating or resolving a closed case throws `E_STATE`.
70
- - An acked case is never escalated automatically. An expired case can only be
71
- escalated with an explicit `to` target (a late page), never by `tick`; later
72
- ticks leave that page open for a decision.
70
+ - Expired is terminal for direct decisions: `ack()` and `resolve()` on an
71
+ expired case throw `E_STATE`. The only in-place way to reopen it is an
72
+ explicit late page — `escalate(id, { to })` — after which a decision is
73
+ accepted (and marked `late`); otherwise raise a new case. `tick` never
74
+ revives an expired case.
75
+ - An acked case is never escalated automatically. A late page is never
76
+ repeated by `tick`; later ticks leave that page open for a decision.
73
77
  - Every tick records at most one escalation receipt — the highest due level —
74
78
  so jumping straight to t3 emits t0 plus one t3 catch-up instead of a burst.
75
79
  - Nothing is sent over a network, spawned, or written to the session log.
@@ -82,8 +86,12 @@ any open state --expiresAt--> expired --late decision--> resolved
82
86
 
83
87
  `kind` is one of `delivery` (t0), `escalation` (t1–t3), `ack`, `decision` or
84
88
  `expiry`. `channel` is the recorded target channel; `by` is the acknowledging
85
- principal; `to` is the SLA level or explicit escalation target. Receipts are
86
- evidence only — they do not prove a channel delivered anything.
89
+ principal; `to` is the SLA level or explicit escalation target.
90
+
91
+ Receipts are immutable, append-only evidence: stored entries are frozen and
92
+ never rewritten, and every read (and every `tick()` result) returns defensive
93
+ copies, so mutating a returned receipt cannot change the ledger. Receipts prove
94
+ what the ledger recorded, not that a channel delivered anything.
87
95
 
88
96
  ## Agent tools
89
97
 
package/index.js CHANGED
@@ -207,8 +207,11 @@ export class RingService {
207
207
  if (!isObject(options)) fail('E_INPUT', 'resolve options must be an object')
208
208
  const decision = readText(options.decision, 'decision', 'E_INPUT', 64)
209
209
  if (kase.state === 'resolved') fail('E_STATE', 'case is already resolved')
210
+ if (kase.state === 'expired') {
211
+ fail('E_STATE', 'cannot resolve an expired case; escalate it with an explicit target or raise a new case')
212
+ }
210
213
  const at = readTimestamp(this.clock(), 'clock')
211
- const late = kase.state === 'expired' || at > kase.expiresAt
214
+ const late = kase.expiredAt !== undefined || at > kase.expiresAt
212
215
  kase.state = 'resolved'
213
216
  kase.decision = decision
214
217
  kase.resolvedAt = at
@@ -276,7 +279,9 @@ export class RingService {
276
279
  }
277
280
 
278
281
  #record(kase, kind, at, extra = {}) {
279
- const receipt = { id: randomUUID(), caseId: kase.id, kind, at, ...extra }
282
+ // Receipts are append-only evidence: freeze the stored entry so no later
283
+ // code path can rewrite history, and hand callers a mutable copy.
284
+ const receipt = Object.freeze({ id: randomUUID(), caseId: kase.id, kind, at, ...extra })
280
285
  this.#receipts.push(receipt)
281
286
  return clone(receipt)
282
287
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "dsh-ring",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Approval SLA and escalation receipts for DeepSeek Harness: ack, escalate, audit.",
5
5
  "type": "module",
6
6
  "main": "index.js",
@@ -34,16 +34,36 @@
34
34
  },
35
35
  "engines": {
36
36
  "node": "^22.19.0 || >=24.9.0",
37
- "dsh": ">=0.2.1-rc.2 <0.3.0 || >=0.2.2-0 <0.3.0"
37
+ "dsh": ">=0.2.1-rc.2 <0.3.0-0"
38
38
  },
39
39
  "dsh": {
40
40
  "manifestVersion": 1,
41
41
  "bundle": {
42
42
  "patch": "./cordis.patch.yml"
43
+ },
44
+ "os": {
45
+ "service": "ring",
46
+ "provides": [
47
+ "ring"
48
+ ],
49
+ "capabilities": [
50
+ "notify"
51
+ ],
52
+ "tools": [
53
+ "ring_raise",
54
+ "ring_ack",
55
+ "ring_escalate",
56
+ "ring_list",
57
+ "ring_receipts"
58
+ ],
59
+ "ui": null,
60
+ "stability": "experimental",
61
+ "since": "0.1.0"
43
62
  }
44
63
  },
45
64
  "publishConfig": {
46
- "access": "public"
65
+ "access": "public",
66
+ "registry": "https://registry.npmjs.org/"
47
67
  },
48
68
  "scripts": {
49
69
  "test": "node --test"