@kubun/protocol 0.11.0 → 0.12.0

package/lib/errors.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Every error code kubun may attach to a thrown error. Also the allowlist of
+ * codes a handler refusal may carry to a remote caller: an error with no
+ * registered code is treated as internal and stays opaque on the wire, so
+ * adding a forwardable reason is an edit to this table rather than a decision
+ * made at a throw site.
+ */
 export declare const KubunErrorCodes: {
     readonly KB01: "Validation error";
     readonly KB02: "Not found";
@@ -8,5 +15,12 @@ export declare const KubunErrorCodes: {
     readonly KB07: "Access denied";
     readonly KB08: "Sync access denied";
     readonly KB09: "Document ID mismatch";
+    readonly KB10: "HLC drift exceeded";
+    readonly KB11: "Owner change rejected";
+    readonly KB12: "Unsupported mutation type";
+    readonly KB13: "Mutation schema validation error";
+    readonly KB14: "Group control denied";
+    readonly KB15: "Model not deployed";
 };
 export type KubunErrorCode = keyof typeof KubunErrorCodes;
+export declare function isKubunErrorCode(value: unknown): value is KubunErrorCode;

package/lib/errors.js

@@ -1,4 +1,10 @@
-export const KubunErrorCodes = {
+/**
+ * Every error code kubun may attach to a thrown error. Also the allowlist of
+ * codes a handler refusal may carry to a remote caller: an error with no
+ * registered code is treated as internal and stays opaque on the wire, so
+ * adding a forwardable reason is an edit to this table rather than a decision
+ * made at a throw site.
+ */ export const KubunErrorCodes = {
     KB01: 'Validation error',
     KB02: 'Not found',
     KB03: 'Unauthorized',
@@ -7,5 +13,14 @@ export const KubunErrorCodes = {
     KB06: 'Internal error',
     KB07: 'Access denied',
     KB08: 'Sync access denied',
-    KB09: 'Document ID mismatch'
+    KB09: 'Document ID mismatch',
+    KB10: 'HLC drift exceeded',
+    KB11: 'Owner change rejected',
+    KB12: 'Unsupported mutation type',
+    KB13: 'Mutation schema validation error',
+    KB14: 'Group control denied',
+    KB15: 'Model not deployed'
 };
+export function isKubunErrorCode(value) {
+    return typeof value === 'string' && Object.hasOwn(KubunErrorCodes, value);
+}

package/lib/index.d.ts

@@ -1,6 +1,6 @@
 import type { AnyClientMessageOf, AnyServerMessageOf, ClientTransportOf, ServerTransportOf } from '@enkaku/protocol';
 import type { GraphProtocol } from './services/graph.js';
-export { type KubunErrorCode, KubunErrorCodes } from './errors.js';
+export { isKubunErrorCode, type KubunErrorCode, KubunErrorCodes } from './errors.js';
 export type { GraphQLOperationParams, GraphQLSource, GraphQLSourceParams, GraphQLSourceProvider, GraphsProvider, } from './executor.js';
 export * from './models/catalog.js';
 export * from './models/cluster.js';

package/lib/index.js

@@ -1,4 +1,4 @@
-export { KubunErrorCodes } from './errors.js';
+export { isKubunErrorCode, KubunErrorCodes } from './errors.js';
 export * from './models/catalog.js';
 export * from './models/cluster.js';
 export * from './models/document.js';

package/lib/models/document.js

@@ -455,7 +455,6 @@ export class DocumentModelNormalizer {
         }
         // Handle other JSON Schema references like #/properties/, #/items/, etc.
         const segments = ref.split('/').slice(1);
-        // biome-ignore lint/suspicious/noExplicitAny: mixed type
         let current = this.#root;
         for (const segment of segments){
             if (current == null || typeof current !== 'object') {

package/lib/types.d.ts

@@ -122,6 +122,28 @@ export type GroupedAggregateValue = {
     keys: Record<string, unknown>;
 } & AggregateValues;
 export type DocumentData = Record<string, unknown>;
+/**
+ * Document fields carried in signed document data and synced, but excluded from
+ * model-schema validation. Model schemas are normalized with
+ * `additionalProperties: false` and never declare these, so the apply path
+ * validates only model-declared fields and preserves reserved fields through
+ * patches unchanged.
+ */
+export declare const RESERVED_DOCUMENT_FIELDS: readonly ["accessPermissions"];
+export declare function isAccessLevel(value: unknown): value is AccessLevel;
+export declare function isValidAccessRule(value: unknown): boolean;
+/**
+ * True when `value` is a well-formed `accessPermissions` object: an object whose
+ * present `read`/`write` entries each carry a known `level` and, when present,
+ * `allowedDIDs`/`allowedCircles`/`allowedGroups` that are string arrays (or
+ * null). Unknown keys are ignored, mirroring the engine's tolerant parser.
+ *
+ * This is the shape contract for the reserved `accessPermissions` document
+ * field. It is enforced strictly when a mutation is minted (authoring time), so
+ * a producer bug is caught at signing rather than persisted as garbage that
+ * unguarded consumers (e.g. the SQL read predicate) could mis-read.
+ */
+export declare function isValidAccessPermissions(value: unknown): boolean;
 export type DocumentNode = {
     id: string;
     model: string;

package/lib/types.js

@@ -1 +1,45 @@
-export { };
+/**
+ * Document fields carried in signed document data and synced, but excluded from
+ * model-schema validation. Model schemas are normalized with
+ * `additionalProperties: false` and never declare these, so the apply path
+ * validates only model-declared fields and preserves reserved fields through
+ * patches unchanged.
+ */ export const RESERVED_DOCUMENT_FIELDS = [
+    'accessPermissions'
+];
+export function isAccessLevel(value) {
+    return value === 'only_owner' || value === 'anyone' || value === 'restricted';
+}
+function isStringArrayOrNull(value) {
+    return value == null || Array.isArray(value) && value.every((item)=>typeof item === 'string');
+}
+export function isValidAccessRule(value) {
+    if (value == null || typeof value !== 'object') {
+        return false;
+    }
+    const rule = value;
+    return isAccessLevel(rule.level) && isStringArrayOrNull(rule.allowedDIDs) && isStringArrayOrNull(rule.allowedCircles) && isStringArrayOrNull(rule.allowedGroups);
+}
+/**
+ * True when `value` is a well-formed `accessPermissions` object: an object whose
+ * present `read`/`write` entries each carry a known `level` and, when present,
+ * `allowedDIDs`/`allowedCircles`/`allowedGroups` that are string arrays (or
+ * null). Unknown keys are ignored, mirroring the engine's tolerant parser.
+ *
+ * This is the shape contract for the reserved `accessPermissions` document
+ * field. It is enforced strictly when a mutation is minted (authoring time), so
+ * a producer bug is caught at signing rather than persisted as garbage that
+ * unguarded consumers (e.g. the SQL read predicate) could mis-read.
+ */ export function isValidAccessPermissions(value) {
+    if (value == null || typeof value !== 'object') {
+        return false;
+    }
+    const perms = value;
+    if (perms.read !== undefined && !isValidAccessRule(perms.read)) {
+        return false;
+    }
+    if (perms.write !== undefined && !isValidAccessRule(perms.write)) {
+        return false;
+    }
+    return true;
+}

package/package.json

@@ -1,39 +1,39 @@
 {
   "name": "@kubun/protocol",
-  "version": "0.11.0",
-  "license": "see LICENSE.md",
+  "version": "0.12.0",
   "keywords": [],
+  "license": "see LICENSE.md",
+  "sideEffects": false,
   "type": "module",
-  "main": "lib/index.js",
-  "types": "lib/index.d.ts",
   "exports": {
     ".": "./lib/index.js"
   },
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
   "files": [
     "lib/*",
     "LICENSE.md"
   ],
-  "sideEffects": false,
   "dependencies": {
-    "@sozai/codec": "^0.1.0",
-    "@enkaku/protocol": "^0.18.1",
-    "@sozai/schema": "^0.1.0",
+    "@enkaku/protocol": "^0.20.0",
+    "@sozai/codec": "^0.4.0",
+    "@sozai/schema": "^0.1.1",
     "change-case": "^5.4.4",
-    "@kubun/id": "^0.11.0",
-    "@kubun/logger": "^0.11.0"
+    "@kubun/id": "^0.12.0",
+    "@kubun/logger": "^0.12.0"
   },
   "devDependencies": {
     "graphql": "^16.14.2",
     "json-schema-typed": "^8.0.2"
   },
   "scripts": {
+    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
     "build:clean": "del lib",
     "build:js": "swc src -d ./lib --config-file ../../node_modules/@kigu/dev/swc.json --strip-leading-paths",
     "build:types": "tsc --emitDeclarationOnly --skipLibCheck",
     "build:types:ci": "tsc --emitDeclarationOnly --declarationMap false",
-    "build": "pnpm run build:clean && pnpm run build:js && pnpm run build:types",
+    "test": "pnpm run test:types && pnpm run test:unit",
     "test:types": "tsc --noEmit -p tsconfig.test.json",
-    "test:unit": "vitest run",
-    "test": "pnpm run test:types && pnpm run test:unit"
+    "test:unit": "vitest run"
   }
 }