@spooky-sync/cli 0.0.1-canary.180 → 0.0.1-canary.182

package/AGENTS.md

@@ -51,6 +51,10 @@ In your `.surql` source, comment annotations attached to `DEFINE FIELD` / `DEFIN
 - `-- @crdt text` (above a `DEFINE FIELD`) — marks a field as a Loro CRDT text field. Consumers must use `useCrdtField` to read/write it; plain `useQuery` will see stale or unmerged content.
 - `-- @parent` (suffix on `DEFINE FIELD ... TYPE record<...>`) — marks the column as the parent side of a relationship; written automatically from the auth context, never by client code.
 - `-- @nosync` (above a `DEFINE TABLE`) — marks a table as server-only: it is omitted from generated types and relations (and any `record<...>` link pointing at it is dropped), no sync events are emitted for it, and the scheduler/SSP exclude it from snapshots and bootstrap. The table still lives in the main DB and is still backed up. The CLI bakes a `COMMENT 'sp00ky:nosync'` marker onto the server-side `DEFINE TABLE` so the runtime services detect it via `INFO FOR DB`. Distinct from `PERMISSIONS FOR select WHERE false`, which only locks reads — a permission-locked table is still synced.
+- `-- @nosync` (above a `DEFINE FIELD`) — marks a single field server-only: omitted from generated types and from the client's local cache schema, omitted from sync event payloads, and omitted from the scheduler replica and SSP bootstrap row scans. **Not a read barrier**: a client's down-sync `SELECT` still returns the column over the wire, and it is only discarded on arrival (`cleanRecord`). For real secrecy use `PERMISSIONS FOR select WHERE false` on the field, or move it to a `@nosync` table.
+- `-- @opaque` (above a `DEFINE FIELD`) — the field IS synced to the client (it stays in generated types and the local cache, flagged `opaque: true` on the column) but no server-side component stores the value. Intended for large blobs you render but never query on. Because nothing holds the value it cannot be evaluated: using it in `where`/`orderBy`/a join throws in the query builder and is rejected with a 400 at SSP registration, and a schema whose `PERMISSIONS` or `DEFINE INDEX` references one fails to build. Delivery works because sync payloads carry ids + versions, not field values — the client reads the row body straight from SurrealDB.
+
+All three field-level exclusions (`@nosync`, `@crdt`, `@opaque`) get `COMMENT 'sp00ky:opaque'` baked onto the server `DEFINE FIELD` (`schema_builder::add_opaque_field_markers`). The scheduler replica and the SSP bootstrap read that marker from `INFO FOR TABLE` and turn it into a `SELECT * OMIT ...` projection. Both halves are required: skipping a field from the ingest payload while the bootstrap still loads it makes the SSP circuit and the scheduler replica disagree about the row's key set permanently (the replica applies updates with `MERGE`, the circuit replaces the whole row), which shows up as an unfixable `spky verify` mismatch.
 
 Example:
 ```sql
@@ -61,10 +65,15 @@ DEFINE FIELD content ON TABLE thread TYPE string ASSERT $value != NONE;
 
 DEFINE FIELD author ON TABLE thread TYPE record<user>; -- @parent
 
+-- @opaque
+DEFINE FIELD preview_png ON TABLE thread TYPE option<bytes>;
+
 -- @nosync
 DEFINE TABLE audit_log SCHEMALESS;
 ```
 
+A descriptor must sit directly above its statement (no blank line between). One that attaches to nothing is warned about, not silently dropped (`annotations::warn_unattached_annotations`).
+
 ## Docker dev apps (`type: docker`)
 
 Besides `backend`/`frontend` apps, `sp00ky.yml` can declare `type: docker` apps —

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spooky-sync/cli",
-  "version": "0.0.1-canary.180",
+  "version": "0.0.1-canary.182",
   "description": "Generate TypeScript/Dart types from SurrealDB schema files",
   "type": "module",
   "main": "./dist/syncgen.cjs",
@@ -61,10 +61,10 @@
     "vitest": "^1.0.0"
   },
   "optionalDependencies": {
-    "@spooky-sync/cli-darwin-arm64": "0.0.1-canary.180",
-    "@spooky-sync/cli-darwin-x64": "0.0.1-canary.180",
-    "@spooky-sync/cli-linux-arm64": "0.0.1-canary.180",
-    "@spooky-sync/cli-linux-x64": "0.0.1-canary.180",
-    "@spooky-sync/cli-win32-x64": "0.0.1-canary.180"
+    "@spooky-sync/cli-darwin-arm64": "0.0.1-canary.182",
+    "@spooky-sync/cli-darwin-x64": "0.0.1-canary.182",
+    "@spooky-sync/cli-linux-arm64": "0.0.1-canary.182",
+    "@spooky-sync/cli-linux-x64": "0.0.1-canary.182",
+    "@spooky-sync/cli-win32-x64": "0.0.1-canary.182"
   }
 }