@sudoke/kernel 0.5.0 → 0.5.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/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sudoke/kernel",
3
- "version": "0.5.0",
3
+ "version": "0.5.1",
4
4
  "description": "SUDOKE kernel — the 9-stage command gate, ledger, registries and async storage port behind every sudoke app",
5
5
  "type": "module",
6
6
  "files": [
@@ -0,0 +1,29 @@
1
+ /**
2
+ * The single reader of a ledger row's operation envelope — the undo planner, the redelivery
3
+ * rights checks and the rebuilding projection all parse `row.meta` through here, so the
4
+ * envelope-vs-row precedence can never drift between two readers.
5
+ *
6
+ * eventVersion precedence (the kernel contract): the envelope's value wins; the row's own version
7
+ * column is the fallback. Rows carrying neither are legacy and answer undefined — callers resolve
8
+ * that as format version 1.
9
+ */
10
+ import type { EventOperationMeta } from './types.js'
11
+ import type { LedgerRow } from './storage.js'
12
+
13
+ /** The operation envelope a row carries — undefined when absent or non-JSON (a hand-edited row);
14
+ * the read never fails. */
15
+ export type OperationMeta = Partial<EventOperationMeta>
16
+
17
+ export function operationMetaOf(row: LedgerRow): OperationMeta | undefined {
18
+ if (!row.meta) return undefined
19
+ try {
20
+ return JSON.parse(row.meta) as OperationMeta
21
+ } catch {
22
+ return undefined
23
+ }
24
+ }
25
+
26
+ /** The event format version a stored row carries — envelope first, then the row's version column. */
27
+ export function ledgerEventVersionOf(row: LedgerRow): number | undefined {
28
+ return operationMetaOf(row)?.eventVersion ?? row.version
29
+ }
@@ -1,3 +1,4 @@
1
+ import { ledgerEventVersionOf } from './operation-meta.js'
1
2
  import { storageOf } from './storage.js'
2
3
  import { assertOpenFor, defaultKernelState, type RegisteredProjector } from './state.js'
3
4
  import type { DomainEvent } from './types.js'
@@ -102,17 +103,7 @@ export async function rebuildProjections(): Promise<void> {
102
103
  proj.initTables,
103
104
  async () => {
104
105
  for (const r of await storageOf().domainRows()) {
105
- // eventVersion reaches replay through the envelope (operation-ledger engines) or the legacy
106
- // version column; rows carrying neither are version 1 by definition
107
- let eventVersion: number | undefined = r.version
108
- if (r.meta) {
109
- try {
110
- const parsed = JSON.parse(r.meta) as { eventVersion?: number }
111
- if (parsed.eventVersion !== undefined) eventVersion = parsed.eventVersion
112
- } catch {
113
- // a non-JSON envelope on a hand-edited row falls back to the version column — the read never fails
114
- }
115
- }
106
+ const eventVersion = ledgerEventVersionOf(r)
116
107
  await applyDomainEvent(
117
108
  {
118
109
  type: r.type,
package/src/undo.ts CHANGED
@@ -32,6 +32,7 @@ import { appPolicy } from './policy.js'
32
32
  import { completeAssembly, lookupCommand, undoHandlerOf, undoPolicyOf } from './registry.js'
33
33
  import { commandRevisionOf, responseMetaOf } from './catalog.js'
34
34
  import { canonicalJson } from './canonical.js'
35
+ import { ledgerEventVersionOf, operationMetaOf } from './operation-meta.js'
35
36
  import {
36
37
  assertLiveRoleAllows,
37
38
  assertRecordedDelegationCovers,
@@ -65,21 +66,12 @@ function capability(): OperationLedgerCapability {
65
66
  return cap
66
67
  }
67
68
 
68
- const parseMeta = (row: LedgerRow): { operationId?: string; commandName?: string; commandVersion?: string; commandRevision?: string; eventVersion?: number; policyTarget?: string } | undefined => {
69
- if (!row.meta) return undefined
70
- try {
71
- return JSON.parse(row.meta)
72
- } catch {
73
- return undefined
74
- }
75
- }
76
-
77
69
  /** Resolves the exact source operation behind a sequence — the whole operation, never a substitute row */
78
70
  async function resolveSource(cap: OperationLedgerCapability, sourceSeq: number): Promise<{ source: SourceOperation; operationId: string }> {
79
71
  const row = await cap.domainRowBySeq(sourceSeq)
80
72
  if (!row || row.kind !== 'domain')
81
73
  throw new GateError(0, 'registry', `No domain event at seq ${sourceSeq} (audit rows are never undo targets)`, { code: 'undo.source_not_found' })
82
- const meta = parseMeta(row)
74
+ const meta = operationMetaOf(row)
83
75
  if (meta?.operationId) {
84
76
  const rows = await cap.eventsOfOperation(meta.operationId)
85
77
  return { source: buildSource(rows.length > 0 ? rows : [row], sourceSeq, false), operationId: meta.operationId }
@@ -89,7 +81,7 @@ async function resolveSource(cap: OperationLedgerCapability, sourceSeq: number):
89
81
  }
90
82
 
91
83
  function buildSource(rows: LedgerRow[], sourceSeq: number, legacy: boolean): SourceOperation {
92
- const first = parseMeta(rows[0])
84
+ const first = operationMetaOf(rows[0])
93
85
  return {
94
86
  operationId: legacy ? `legacy:${sourceSeq}` : first?.operationId ?? `legacy:${sourceSeq}`,
95
87
  sourceSeq,
@@ -98,10 +90,7 @@ function buildSource(rows: LedgerRow[], sourceSeq: number, legacy: boolean): Sou
98
90
  ...(first?.commandVersion ? { commandVersion: first.commandVersion } : {}),
99
91
  ...(first?.commandRevision ? { commandRevision: first.commandRevision } : {}),
100
92
  events: rows.map((r) => {
101
- const meta = parseMeta(r)
102
- // envelope first, then the row's version column — the SAME precedence replay uses, so the
103
- // planner and a rebuilding projection never disagree about which format version a row carries
104
- const eventVersion = meta?.eventVersion !== undefined ? meta.eventVersion : r.version
93
+ const eventVersion = ledgerEventVersionOf(r)
105
94
  return {
106
95
  seq: r.seq,
107
96
  type: r.type,
@@ -414,7 +403,7 @@ async function assertUndoReadRights(sourceSeq: number, identity: Identity): Prom
414
403
  const cap = capability()
415
404
  const compSeq = (await cap.compensationsOf(computed.operationId))[0]
416
405
  const row = compSeq !== undefined ? await cap.domainRowBySeq(compSeq) : undefined
417
- const meta = row ? parseMeta(row) : undefined
406
+ const meta = row ? operationMetaOf(row) : undefined
418
407
  const def = meta?.commandName ? lookupCommand(meta.commandName) : undefined
419
408
  if (!def || !row)
420
409
  throw new GateError(