@kubun/protocol 0.9.0 → 0.11.0

package/lib/errors.d.ts

@@ -6,5 +6,7 @@ export declare const KubunErrorCodes: {
     readonly KB05: "Transaction error";
     readonly KB06: "Internal error";
     readonly KB07: "Access denied";
+    readonly KB08: "Sync access denied";
+    readonly KB09: "Document ID mismatch";
 };
 export type KubunErrorCode = keyof typeof KubunErrorCodes;

package/lib/errors.js

@@ -1 +1,11 @@
-export const KubunErrorCodes={KB01:"Validation error",KB02:"Not found",KB03:"Unauthorized",KB04:"Invalid operation",KB05:"Transaction error",KB06:"Internal error",KB07:"Access denied"};
+export const KubunErrorCodes = {
+    KB01: 'Validation error',
+    KB02: 'Not found',
+    KB03: 'Unauthorized',
+    KB04: 'Invalid operation',
+    KB05: 'Transaction error',
+    KB06: 'Internal error',
+    KB07: 'Access denied',
+    KB08: 'Sync access denied',
+    KB09: 'Document ID mismatch'
+};

package/lib/executor.js

@@ -1 +1,6 @@
-export{};
+/**
+ * Shared interface for graph management and execution.
+ * Implemented by KubunEngine (local) and KubunClient (remote).
+ * Consumers that need graph operations (MCP, CLI, etc.) depend on this
+ * interface rather than a specific implementation.
+ */ export { };

package/lib/index.js

@@ -1 +1,12 @@
-export{KubunErrorCodes}from"./errors.js";export*from"./models/catalog.js";export*from"./models/cluster.js";export*from"./models/document.js";export*from"./models/graph.js";export*from"./models/group.js";export*from"./models/json-schema.js";export*from"./models/optimal-clusters.js";export*from"./models/value.js";export{KubunAttributeKeys,KubunSpanNames}from"./semantic.js";export*from"./services/graph.js";export*from"./types.js";
+export { KubunErrorCodes } from './errors.js';
+export * from './models/catalog.js';
+export * from './models/cluster.js';
+export * from './models/document.js';
+export * from './models/graph.js';
+export * from './models/group.js';
+export * from './models/json-schema.js';
+export * from './models/optimal-clusters.js';
+export * from './models/value.js';
+export { KubunAttributeKeys, KubunSpanNames } from './semantic.js';
+export * from './services/graph.js';
+export * from './types.js';

package/lib/models/catalog.js

@@ -1 +1,6 @@
-export{};
+/**
+ * Declarative filter criteria for a catalog.
+ * All fields are optional — omitted fields mean "no constraint on this dimension."
+ * Multiple values in an array are OR'd (any match).
+ * Multiple fields are AND'd (all must match).
+ */ export { };

package/lib/models/cluster.d.ts

@@ -1,6 +1,6 @@
-import { type FromSchema } from '@enkaku/schema';
 import { DocumentModelID } from '@kubun/id';
 import { type Logger } from '@kubun/logger';
+import { type FromSchema } from '@sozai/schema';
 import type { DocumentModel, DocumentModelInput, DocumentModelsCluster, DocumentModelsRecord } from './document.js';
 export declare const clusterModel: {
     readonly $id: "urn:kubun:protocol:model:cluster";
@@ -1118,7 +1118,7 @@ export declare const clusterModel: {
 export type ClusterModel = FromSchema<typeof clusterModel>;
 export type ClustersRecord = Record<string, ClusterModel>;
 export declare function clusterToRecord(cluster: ClusterModel): ClustersRecord;
-export declare const validateClusterModel: import("@enkaku/schema").Validator<{
+export declare const validateClusterModel: import("@sozai/schema").Validator<{
     digest: string;
     models: ({
         name: string;

package/lib/models/cluster.js

@@ -1 +1,186 @@
-import{fromB64 as e,toB64 as t}from"@enkaku/codec";import{assertType as r,createValidator as l}from"@enkaku/schema";import{ClusterModelID as o,DocumentModelID as i,digestJSON as s}from"@kubun/id";import{getKubunLogger as n}from"@kubun/logger";import{DocumentModelNormalizer as u,documentModelsCluster as d}from"./document.js";import{binaryStringValue as a}from"./value.js";export const clusterModel={$id:"urn:kubun:protocol:model:cluster",type:"object",properties:{digest:a,models:d,record:{type:"object",patternProperties:{"^k[0-9a-z]{56}$":{type:"integer",minimum:0}},additionalProperties:!1}},required:["digest","models","record"],additionalProperties:!1};export function clusterToRecord(t){let r=e(t.digest);return{[o.fromDigest(r).toString()]:t}}export const validateClusterModel=l(clusterModel);export function verifyCluster(e){r(validateClusterModel,e);let l=s(e.models);if(e.digest!==t(l))throw Error("Invalid cluster: digest mismatch");let o=Object.entries(e.record);if(o.length!==e.models.length)throw Error("Invalid cluster: record length mismatch");let n={};for(let[t,r]of o){let o=new i(l,r).toString();if(t!==o)throw Error(`Invalid cluster: record key mismatch, expected ${o}, got ${t}`);let s=e.models[r];if(null==s)throw Error(`Invalid cluster: missing model at index ${r}`);n[t]=s}return n}export class ClusterBuilder{#e=[];#t={};#r=new Map;#l;constructor(e={}){for(let t of(this.#l=e.logger??n("protocol"),Object.values(e.externalClusters??{}))){let e=verifyCluster(t),r={};for(let t of Object.keys(e)){let e=i.fromString(t);r[i.local(e.index).toString()]=t}for(let[t,l]of Object.entries(e))this.#t[t]=l,this.#r.set(t,r)}}get cluster(){return this.#e}get length(){return this.#e.length}build(){let e=this.#e;if(0===e.length)throw Error("Cluster is empty");let r=s(e),l={};for(let t=0;t<e.length;t++)l[new i(r,t).toString()]=t;return{digest:t(r),models:e,record:l}}get(e){let t;if("number"==typeof e)t=e;else if("string"==typeof e&&"#"===e[0]){if(Number.isNaN(t=Number.parseInt(e.slice(1),10)))throw Error(`Invalid DocumentModelID: ${e}`)}else{let r="string"==typeof e?i.fromString(e):e;if(!r.isLocal){let t="string"==typeof e?e:e.toString(),r=this.#t[t];if(null!=r)return r;throw Error(`External model not found: ${t}`)}t=r.index}let r=this.#e[t];if(null==r)throw RangeError(`Invalid cluster index: ${t}`);return r}add(e){let t=(e.interfaces??[]).map(e=>{if(e.startsWith("#")){let t=Number.parseInt(e.slice(1),10);if(Number.isNaN(t))throw Error(`Invalid DocumentModelID: ${e}`);return i.local(t).toString()}return e}),r=new u({inputModel:e,interfaceModels:t.map(e=>{let t=this.get(e),r=this.#r.get(e);return null!=r?this.#o(t,r):t}),logger:this.#l,normalizedInterfaceIDs:t}).toDocumentModel(),l=this.#e.length;return this.#e.push(r),i.local(l)}#o(e,t){let r=e.interfaces.map(e=>t[e]??e),l={...e.fieldsMeta};for(let[e,r]of Object.entries(l))"document"===r.type&&null!=r.model&&null!=t[r.model]&&(l[e]={...r,model:t[r.model]});return{...e,interfaces:r,fieldsMeta:l}}addAll(e){return e.map(e=>this.add(e))}}
+import { ClusterModelID, DocumentModelID, digestJSON } from '@kubun/id';
+import { getKubunLogger } from '@kubun/logger';
+import { fromB64, toB64 } from '@sozai/codec';
+import { assertType, createValidator } from '@sozai/schema';
+import { DocumentModelNormalizer, documentModelsCluster } from './document.js';
+import { binaryStringValue } from './value.js';
+export const clusterModel = {
+    $id: 'urn:kubun:protocol:model:cluster',
+    type: 'object',
+    properties: {
+        digest: binaryStringValue,
+        models: documentModelsCluster,
+        record: {
+            type: 'object',
+            patternProperties: {
+                '^k[0-9a-z]{56}$': {
+                    type: 'integer',
+                    minimum: 0
+                }
+            },
+            additionalProperties: false
+        }
+    },
+    required: [
+        'digest',
+        'models',
+        'record'
+    ],
+    additionalProperties: false
+};
+export function clusterToRecord(cluster) {
+    const digestBytes = fromB64(cluster.digest);
+    const id = ClusterModelID.fromDigest(digestBytes);
+    return {
+        [id.toString()]: cluster
+    };
+}
+export const validateClusterModel = createValidator(clusterModel);
+export function verifyCluster(cluster) {
+    assertType(validateClusterModel, cluster);
+    const digest = digestJSON(cluster.models);
+    if (cluster.digest !== toB64(digest)) {
+        throw new Error('Invalid cluster: digest mismatch');
+    }
+    const recordEntries = Object.entries(cluster.record);
+    if (recordEntries.length !== cluster.models.length) {
+        throw new Error('Invalid cluster: record length mismatch');
+    }
+    const record = {};
+    for (const [id, index] of recordEntries){
+        const expectedID = new DocumentModelID(digest, index).toString();
+        if (id !== expectedID) {
+            throw new Error(`Invalid cluster: record key mismatch, expected ${expectedID}, got ${id}`);
+        }
+        const model = cluster.models[index];
+        if (model == null) {
+            throw new Error(`Invalid cluster: missing model at index ${index}`);
+        }
+        record[id] = model;
+    }
+    return record;
+}
+export class ClusterBuilder {
+    #cluster = [];
+    #externalModels = {};
+    #externalIDMaps = new Map();
+    #logger;
+    constructor(params = {}){
+        this.#logger = params.logger ?? getKubunLogger('protocol');
+        for (const cluster of Object.values(params.externalClusters ?? {})){
+            const record = verifyCluster(cluster);
+            // Build local-to-global map for this cluster
+            const localToGlobal = {};
+            for (const globalID of Object.keys(record)){
+                const parsed = DocumentModelID.fromString(globalID);
+                localToGlobal[DocumentModelID.local(parsed.index).toString()] = globalID;
+            }
+            // Store each model and its cluster's map
+            for (const [globalID, model] of Object.entries(record)){
+                this.#externalModels[globalID] = model;
+                this.#externalIDMaps.set(globalID, localToGlobal);
+            }
+        }
+    }
+    get cluster() {
+        return this.#cluster;
+    }
+    get length() {
+        return this.#cluster.length;
+    }
+    build() {
+        const models = this.#cluster;
+        if (models.length === 0) {
+            throw new Error('Cluster is empty');
+        }
+        const digest = digestJSON(models);
+        const record = {};
+        for(let index = 0; index < models.length; index++){
+            const id = new DocumentModelID(digest, index);
+            record[id.toString()] = index;
+        }
+        return {
+            digest: toB64(digest),
+            models,
+            record
+        };
+    }
+    get(id) {
+        let index;
+        if (typeof id === 'number') {
+            index = id;
+        } else if (typeof id === 'string' && id[0] === '#') {
+            index = Number.parseInt(id.slice(1), 10);
+            if (Number.isNaN(index)) {
+                throw new Error(`Invalid DocumentModelID: ${id}`);
+            }
+        } else {
+            const docID = typeof id === 'string' ? DocumentModelID.fromString(id) : id;
+            if (!docID.isLocal) {
+                const idStr = typeof id === 'string' ? id : id.toString();
+                const external = this.#externalModels[idStr];
+                if (external != null) {
+                    return external;
+                }
+                throw new Error(`External model not found: ${idStr}`);
+            }
+            index = docID.index;
+        }
+        const model = this.#cluster[index];
+        if (model == null) {
+            throw new RangeError(`Invalid cluster index: ${index}`);
+        }
+        return model;
+    }
+    add(inputModel) {
+        const interfaceIDs = inputModel.interfaces ?? [];
+        const normalizedInterfaceIDs = interfaceIDs.map((id)=>{
+            if (id.startsWith('#')) {
+                const index = Number.parseInt(id.slice(1), 10);
+                if (Number.isNaN(index)) {
+                    throw new Error(`Invalid DocumentModelID: ${id}`);
+                }
+                return DocumentModelID.local(index).toString();
+            }
+            return id;
+        });
+        const interfaceModels = normalizedInterfaceIDs.map((id)=>{
+            const model = this.get(id);
+            const idMap = this.#externalIDMaps.get(id);
+            return idMap != null ? this.#resolveExternalModel(model, idMap) : model;
+        });
+        const model = new DocumentModelNormalizer({
+            inputModel,
+            interfaceModels,
+            logger: this.#logger,
+            normalizedInterfaceIDs
+        }).toDocumentModel();
+        const index = this.#cluster.length;
+        this.#cluster.push(model);
+        return DocumentModelID.local(index);
+    }
+    #resolveExternalModel(model, idMap) {
+        // Resolve transitive interface IDs from local to global
+        const interfaces = model.interfaces.map((id)=>idMap[id] ?? id);
+        // Resolve fieldsMeta document references from local to global
+        const fieldsMeta = {
+            ...model.fieldsMeta
+        };
+        for (const [key, field] of Object.entries(fieldsMeta)){
+            if (field.type === 'document' && field.model != null && idMap[field.model] != null) {
+                fieldsMeta[key] = {
+                    ...field,
+                    model: idMap[field.model]
+                };
+            }
+        }
+        return {
+            ...model,
+            interfaces,
+            fieldsMeta
+        };
+    }
+    addAll(models) {
+        return models.map((input)=>this.add(input));
+    }
+}

package/lib/models/document.d.ts

@@ -1,5 +1,5 @@
-import { type FromSchema } from '@enkaku/schema';
 import type { Logger } from '@kubun/logger';
+import { type FromSchema } from '@sozai/schema';
 import type { JSONSchema } from 'json-schema-typed';
 export declare const documentModelVersion: {
     readonly type: "string";
@@ -5378,7 +5378,7 @@ export declare const documentMutation: {
     }];
 };
 export type DocumentMutation = FromSchema<typeof documentMutation>;
-export declare const validateDocumentModel: import("@enkaku/schema").Validator<{
+export declare const validateDocumentModel: import("@sozai/schema").Validator<{
     name: string;
     version: "1.0";
     schema: {