LCOV - code coverage report
Current view: top level - src/workbench/extensions/agent/crdt - schemaGuard.ts Coverage Total Hit
Test: ComfyUI E2E Coverage Lines: 9.1 % 11 1
Test Date: 2026-11-17 04:17:53

            Line data    Source code
       1              : /**
       2              :  * Read-time schema-version gate (CRDT keep-alive invariant KA-11).
       3              :  *
       4              :  * KA-11: "Schema-version discipline, ENFORCED ON READ. Bump `SCHEMA_VERSION`
       5              :  * when an old reader would mis-project a new doc; fail-closed on an unreadable
       6              :  * schema."
       7              :  *
       8              :  * Before this file the follower had no read-side gate at all: the only mention
       9              :  * of the version anywhere was `expect(SCHEMA_VERSION).toBe(1)` in a test, which
      10              :  * pins the BUILD-TIME constant of the package the frontend compiled against and
      11              :  * says nothing about the version of the document that actually arrived over the
      12              :  * socket. A doc-host advancing to schema v2 would have been read with a v1
      13              :  * reader — whatever keys still parsed would render, silently and wrongly. That
      14              :  * is fail-OPEN, the exact failure KA-11 names.
      15              :  *
      16              :  * The version is read through the shared package's PUBLIC api
      17              :  * (`readSchemaVersion`, `SCHEMA_VERSION`) — never through a deep/internal
      18              :  * import — so the key name and the expected value cannot drift from the
      19              :  * writer: they are the same symbols the cloud doc-host uses. The package's own `migrate()` is deliberately
      20              :  * NOT called: it is host-only (it mutates the doc), and a follower must never
      21              :  * write the shared doc (KA-6 / FORECLOSE #5).
      22              :  */
      23              : import { SCHEMA_VERSION, readSchemaVersion } from '@comfyorg/comfy-multi-player'
      24              : import type * as Y from 'yjs'
      25              : 
      26              : import { assert } from '@/base/assert'
      27              : 
      28              : /** Thrown by {@link assertReadableSchema}; carries the version actually found. */
      29            1 : export class FollowerSchemaError extends Error {
      30              :   constructor(
      31            0 :     readonly found: unknown,
      32              :     message: string
      33              :   ) {
      34            0 :     super(message)
      35            0 :     this.name = 'FollowerSchemaError'
      36              :   }
      37              : }
      38              : 
      39              : /**
      40              :  * Fail closed unless the merged doc declares exactly the schema version this
      41              :  * build was written against.
      42              :  *
      43              :  * A MISSING `meta.schema_version` fails too, and deliberately: every doc the
      44              :  * host produces is seeded by the shared package (`initDoc`/`mint` both write
      45              :  * the key), so an absent version means the bytes are not a document this
      46              :  * reader understands — which is precisely "unreadable schema".
      47              :  *
      48              :  * @throws FollowerSchemaError when the doc is not readable at this version.
      49              :  */
      50            0 : export function assertReadableSchema(doc: Y.Doc): void {
      51            0 :   const found = readSchemaVersion(doc)
      52            0 :   if (found === SCHEMA_VERSION) return
      53              : 
      54            0 :   const message =
      55              :     `CRDT follower: doc meta.schema_version=${String(found)} is not the ` +
      56              :     `v${SCHEMA_VERSION} layout this build reads — refusing to project it ` +
      57              :     `(fail-closed, keep-alive invariant KA-11).`
      58              : 
      59            0 :   try {
      60              :     // Route through the repo's central invariant channel: console.error in
      61              :     // every environment, Sentry reporter in production.
      62            0 :     assert(
      63              :       false,
      64              :       'CRDT follower: doc meta.schema_version is not the layout this build reads — refusing to project it (fail-closed, keep-alive invariant KA-11)',
      65              :       { found }
      66              :     )
      67              :   } catch {
      68              :     // Swallowed on purpose. `assert` throws only under DEV, so it is NOT a
      69              :     // fail-closed mechanism by itself — outside DEV it returns normally and
      70              :     // the caller would carry on projecting an unreadable doc. The typed throw
      71              :     // below is what actually closes the gate, in every environment.
      72              :   }
      73            0 :   throw new FollowerSchemaError(found, message)
      74              : }
        

Generated by: LCOV version 2.0-1