@kubun/protocol 0.10.0 → 0.11.0

package/lib/models/json-schema.js

@@ -1 +1,320 @@
-export const booleanModel={type:"object",properties:{type:{type:"string",const:"boolean"},default:{type:"boolean"}},required:["type"],additionalProperties:!1};export const integerModel={type:"object",properties:{type:{type:"string",const:"integer"},default:{type:"integer"},minimum:{type:"integer"},maximum:{type:"integer"}},required:["type"],additionalProperties:!1};export const numberModel={type:"object",properties:{type:{type:"string",const:"number"},default:{type:"number"},min:{type:"number"},max:{type:"number"}},required:["type"],additionalProperties:!1};export const stringConstModel={type:"object",properties:{type:{type:"string",const:"string"},title:{type:"string"},const:{type:"string"},default:{type:"string"}},required:["type","const"],additionalProperties:!1};let e={type:"string",pattern:"^[A-Z]+[A-Z_]+[A-Z]$"};export const stringEnumModel={type:"object",properties:{type:{type:"string",const:"string"},title:{type:"string"},enum:{type:"array",items:e},default:e},required:["type","title","enum"],additionalProperties:!1};export const supportedStringFormat={type:"string",enum:["date","date-time","duration","email","time","uri"]};export const stringFormatModel={type:"object",properties:{type:{type:"string",const:"string"},format:supportedStringFormat,title:{type:"string"},default:{type:"string"},minLength:{type:"integer"},maxLength:{type:"integer"}},required:["type","format"],additionalProperties:!1};export const stringCustomModel={type:"object",properties:{type:{type:"string",const:"string"},title:{type:"string"},pattern:{type:"string"},default:{type:"string"},minLength:{type:"integer"},maxLength:{type:"integer"}},required:["type"],additionalProperties:!1};export const stringModel={anyOf:[stringConstModel,stringCustomModel,stringEnumModel,stringFormatModel]};export const scalarModel={anyOf:[booleanModel,integerModel,numberModel,stringModel]};export const refModel={type:"object",properties:{$ref:{type:"string"}},required:["$ref"],additionalProperties:!1};export const nameString={type:"string",pattern:"^[A-Z]+[A-Za-z0-9]+$"};export const arrayModel={type:"object",properties:{type:{type:"string",const:"array"},title:nameString,items:refModel,uniqueItems:{type:"boolean"},minItems:{type:"integer"},maxItems:{type:"integer"}},required:["type","title","items"],additionalProperties:!1};export const baseObjectModel={type:"object",properties:{type:{type:"string",const:"object"},properties:{type:"object",patternProperties:{"^[a-z]+[A-Za-z0-9]+$":refModel},additionalProperties:!1},required:{type:"array",items:{type:"string"}},additionalProperties:{type:"boolean"}},required:["type","properties","required","additionalProperties"],additionalProperties:!1};export const objectModel={type:"object",properties:{...baseObjectModel.properties,title:nameString},required:[...baseObjectModel.required,"title"],additionalProperties:!1};export const jsonObjectModel={type:"object",properties:{type:{type:"string",const:"object"},title:{type:"string",const:"JSONObject"},additionalProperties:{type:"boolean",const:!0}},required:["type","title","additionalProperties"],additionalProperties:!1};export const shapeModel={anyOf:[arrayModel,objectModel,jsonObjectModel]};export const typeModel={anyOf:[scalarModel,shapeModel]};export const referencesRecordModel={type:"object",additionalProperties:typeModel};
+export const booleanModel = {
+    type: 'object',
+    properties: {
+        type: {
+            type: 'string',
+            const: 'boolean'
+        },
+        default: {
+            type: 'boolean'
+        }
+    },
+    required: [
+        'type'
+    ],
+    additionalProperties: false
+};
+export const integerModel = {
+    type: 'object',
+    properties: {
+        type: {
+            type: 'string',
+            const: 'integer'
+        },
+        default: {
+            type: 'integer'
+        },
+        minimum: {
+            type: 'integer'
+        },
+        maximum: {
+            type: 'integer'
+        }
+    },
+    required: [
+        'type'
+    ],
+    additionalProperties: false
+};
+export const numberModel = {
+    type: 'object',
+    properties: {
+        type: {
+            type: 'string',
+            const: 'number'
+        },
+        default: {
+            type: 'number'
+        },
+        min: {
+            type: 'number'
+        },
+        max: {
+            type: 'number'
+        }
+    },
+    required: [
+        'type'
+    ],
+    additionalProperties: false
+};
+export const stringConstModel = {
+    type: 'object',
+    properties: {
+        type: {
+            type: 'string',
+            const: 'string'
+        },
+        title: {
+            type: 'string'
+        },
+        const: {
+            type: 'string'
+        },
+        default: {
+            type: 'string'
+        }
+    },
+    required: [
+        'type',
+        'const'
+    ],
+    additionalProperties: false
+};
+// Uppercase characters and "_" to match GraphQL enum
+const enumString = {
+    type: 'string',
+    pattern: '^[A-Z]+[A-Z_]+[A-Z]$'
+};
+export const stringEnumModel = {
+    type: 'object',
+    properties: {
+        type: {
+            type: 'string',
+            const: 'string'
+        },
+        title: {
+            type: 'string'
+        },
+        enum: {
+            type: 'array',
+            items: enumString
+        },
+        default: enumString
+    },
+    required: [
+        'type',
+        'title',
+        'enum'
+    ],
+    additionalProperties: false
+};
+export const supportedStringFormat = {
+    type: 'string',
+    enum: [
+        'date',
+        'date-time',
+        'duration',
+        'email',
+        'time',
+        'uri'
+    ]
+};
+export const stringFormatModel = {
+    type: 'object',
+    properties: {
+        type: {
+            type: 'string',
+            const: 'string'
+        },
+        format: supportedStringFormat,
+        title: {
+            type: 'string'
+        },
+        default: {
+            type: 'string'
+        },
+        minLength: {
+            type: 'integer'
+        },
+        maxLength: {
+            type: 'integer'
+        }
+    },
+    required: [
+        'type',
+        'format'
+    ],
+    additionalProperties: false
+};
+export const stringCustomModel = {
+    type: 'object',
+    properties: {
+        type: {
+            type: 'string',
+            const: 'string'
+        },
+        title: {
+            type: 'string'
+        },
+        pattern: {
+            type: 'string'
+        },
+        default: {
+            type: 'string'
+        },
+        minLength: {
+            type: 'integer'
+        },
+        maxLength: {
+            type: 'integer'
+        }
+    },
+    required: [
+        'type'
+    ],
+    additionalProperties: false
+};
+export const stringModel = {
+    anyOf: [
+        stringConstModel,
+        stringCustomModel,
+        stringEnumModel,
+        stringFormatModel
+    ]
+};
+export const scalarModel = {
+    anyOf: [
+        booleanModel,
+        integerModel,
+        numberModel,
+        stringModel
+    ]
+};
+export const refModel = {
+    type: 'object',
+    properties: {
+        $ref: {
+            type: 'string'
+        }
+    },
+    required: [
+        '$ref'
+    ],
+    additionalProperties: false
+};
+// Valid GraphQL name
+export const nameString = {
+    type: 'string',
+    pattern: '^[A-Z]+[A-Za-z0-9]+$'
+};
+export const arrayModel = {
+    type: 'object',
+    properties: {
+        type: {
+            type: 'string',
+            const: 'array'
+        },
+        title: nameString,
+        items: refModel,
+        uniqueItems: {
+            type: 'boolean'
+        },
+        minItems: {
+            type: 'integer'
+        },
+        maxItems: {
+            type: 'integer'
+        }
+    },
+    required: [
+        'type',
+        'title',
+        'items'
+    ],
+    additionalProperties: false
+};
+export const baseObjectModel = {
+    type: 'object',
+    properties: {
+        type: {
+            type: 'string',
+            const: 'object'
+        },
+        properties: {
+            type: 'object',
+            patternProperties: {
+                '^[a-z]+[A-Za-z0-9]+$': refModel
+            },
+            additionalProperties: false
+        },
+        required: {
+            type: 'array',
+            items: {
+                type: 'string'
+            }
+        },
+        additionalProperties: {
+            type: 'boolean'
+        }
+    },
+    required: [
+        'type',
+        'properties',
+        'required',
+        'additionalProperties'
+    ],
+    additionalProperties: false
+};
+export const objectModel = {
+    type: 'object',
+    properties: {
+        ...baseObjectModel.properties,
+        title: nameString
+    },
+    required: [
+        ...baseObjectModel.required,
+        'title'
+    ],
+    additionalProperties: false
+};
+export const jsonObjectModel = {
+    type: 'object',
+    properties: {
+        type: {
+            type: 'string',
+            const: 'object'
+        },
+        title: {
+            type: 'string',
+            const: 'JSONObject'
+        },
+        additionalProperties: {
+            type: 'boolean',
+            const: true
+        }
+    },
+    required: [
+        'type',
+        'title',
+        'additionalProperties'
+    ],
+    additionalProperties: false
+};
+export const shapeModel = {
+    anyOf: [
+        arrayModel,
+        objectModel,
+        jsonObjectModel
+    ]
+};
+export const typeModel = {
+    anyOf: [
+        scalarModel,
+        shapeModel
+    ]
+};
+export const referencesRecordModel = {
+    type: 'object',
+    additionalProperties: typeModel
+};

package/lib/models/optimal-clusters.js

@@ -1 +1,324 @@
-import{DocumentModelID as e,digestJSON as t}from"@kubun/id";import{ClusterBuilder as l,clusterToRecord as n}from"./cluster.js";function r(e){if(!e.startsWith("#"))return null;let t=Number.parseInt(e.slice(1),10);return Number.isNaN(t)?null:t}export function extractFieldsMetaDeps(e){return e.map(e=>{let t=new Set;for(let l of Object.values(e.fieldsMeta??{}))if("document"===l.type&&null!=l.model){let e=r(l.model);null!=e&&t.add(e)}return t})}export function extractInterfaceDeps(e){return e.map(e=>{let t=new Set;for(let l of e.interfaces??[]){let e=r(l);null!=e&&t.add(e)}return t})}export function findStronglyConnectedComponents(e){let t=e.length,l=Array(t).fill(-1),n=Array(t).fill(-1),r=Array(t).fill(!1),o=[],s=[],f=0;for(let i=0;i<t;i++)-1===l[i]&&function i(a){for(let s of(l[a]=f,n[a]=f,f++,o.push(a),r[a]=!0,e[a]))!(s>=t)&&(-1===l[s]?(i(s),n[a]=Math.min(n[a],n[s])):r[s]&&(n[a]=Math.min(n[a],l[s])));if(n[a]===l[a]){let e=[],t=o.pop();for(;null!=t&&(r[t]=!1,e.push(t),t!==a);)t=o.pop();s.push(e)}}(i);return s.map(e=>e.sort((e,t)=>e-t)).sort((e,t)=>e[0]-t[0])}export function findClusters(e){return findStronglyConnectedComponents(extractFieldsMetaDeps(e))}export class GraphBuilder{#e=[];#t;constructor(e={}){this.#t=e.externalClusters??{}}add(e){return this.#e.push(e),this}addAll(e){return this.#e.push(...e),this}build(){let o=Object.keys(this.#t).length>0?this.#t:void 0,s=function(o,s){if(0===o.length)return[];let f=extractFieldsMetaDeps(o),i=extractInterfaceDeps(o),a=findStronglyConnectedComponents(f),u=function(e,t,l){let n=new Map;for(let t=0;t<e.length;t++)for(let l of e[t])n.set(l,t);let r=Array.from({length:e.length},()=>new Set);for(let o=0;o<e.length;o++)for(let s of e[o]){for(let e of t[s]){let t=n.get(e);null!=t&&t!==o&&r[o].add(t)}for(let e of l[s]){let t=n.get(e);null!=t&&t!==o&&r[o].add(t)}}let o=r.map(e=>e.size),s=o.map((e,t)=>0===e?t:-1).filter(e=>e>=0),f=[];for(;s.length>0;){let e=s.shift();if(null==e)break;f.push(e);for(let t=0;t<r.length;t++)r[t].has(e)&&(o[t]--,0===o[t]&&s.push(t))}return f}(a,i,f),d=new Map,p={...s??{}},m=[];for(let s of u){let f=a[s],u=function(e,t,l,n){let o=new Set(t),s=new Map;for(let e of t){let t=new Set;for(let n of l[e])o.has(n)&&t.add(n);s.set(e,t)}let f=new Map;for(let e of t)f.set(e,s.get(e)?.size??0);let i=[],a=t.filter(e=>(f.get(e)??0)===0).map(t=>({originalIndex:t,model:e[t]})).sort((e,t)=>e.model.name.localeCompare(t.model.name));for(;a.length>0;){let t=a.shift();if(null==t)break;for(let[l,n]of(i.push(t),s))if(n.has(t.originalIndex)){let t=(f.get(l)??1)-1;if(f.set(l,t),0===t){let t={originalIndex:l,model:e[l]},n=a.findIndex(e=>e.model.name.localeCompare(t.model.name)>0);-1===n?a.push(t):a.splice(n,0,t)}}}let u=new Map;for(let e=0;e<i.length;e++)u.set(i[e].originalIndex,e);return i.map(({model:e})=>{let t={...e};if(null!=t.interfaces&&(t.interfaces=t.interfaces.map(e=>{let t=r(e);if(null==t)return e;let l=n.get(t);if(null!=l)return l;let o=u.get(t);return null!=o?`#${o}`:e})),null!=t.fieldsMeta){let e={...t.fieldsMeta};for(let[t,l]of Object.entries(e))if("document"===l.type&&null!=l.model){let o=r(l.model);if(null==o)continue;let s=n.get(o);if(null!=s){e[t]={...l,model:s};continue}let f=u.get(o);null!=f&&(e[t]={...l,model:`#${f}`})}t.fieldsMeta=e}return t})}(o,f,i,d),c=new l({externalClusters:Object.keys(p).length>0?p:void 0});c.addAll(u);let h=c.build();m.push(h);let g=t(h.models);for(let t=0;t<f.length;t++){let l=f[t],n=o[l].name,r=h.models.findIndex(e=>e.name===n);if(-1!==r){let t=new e(g,r);d.set(l,t.toString())}}Object.assign(p,n(h))}return m}(this.#e,o),f={};for(let e of s)Object.assign(f,n(e));return f}}
+import { DocumentModelID, digestJSON } from '@kubun/id';
+import { ClusterBuilder, clusterToRecord } from './cluster.js';
+/**
+ * Parse local index from a reference string like '#0', '#1', etc.
+ * Returns null if the reference is not a local index.
+ */ function parseLocalIndex(ref) {
+    if (!ref.startsWith('#')) return null;
+    const index = Number.parseInt(ref.slice(1), 10);
+    return Number.isNaN(index) ? null : index;
+}
+/**
+ * Extract fieldsMeta document reference dependencies for each model.
+ * Returns directed edges only (A→B does not imply B→A).
+ * Used for SCC grouping — only circular fieldsMeta forces co-location.
+ */ export function extractFieldsMetaDeps(models) {
+    return models.map((model)=>{
+        const deps = new Set();
+        for (const meta of Object.values(model.fieldsMeta ?? {})){
+            if (meta.type === 'document' && meta.model != null) {
+                const index = parseLocalIndex(meta.model);
+                if (index != null) deps.add(index);
+            }
+        }
+        return deps;
+    });
+}
+/**
+ * Extract interface implementation dependencies for each model.
+ * These form a DAG (no circular interfaces). Used for ordering
+ * within a cluster so ClusterBuilder can resolve interfaces eagerly.
+ */ export function extractInterfaceDeps(models) {
+    return models.map((model)=>{
+        const deps = new Set();
+        for (const iface of model.interfaces ?? []){
+            const index = parseLocalIndex(iface);
+            if (index != null) deps.add(index);
+        }
+        return deps;
+    });
+}
+/**
+ * Find strongly connected components using Tarjan's algorithm.
+ * Used on fieldsMeta directed graph — only circular references (A→B→A)
+ * force models into the same cluster. One-way refs don't group.
+ * Returns arrays of model indices, one per SCC.
+ */ export function findStronglyConnectedComponents(deps) {
+    const n = deps.length;
+    const indices = new Array(n).fill(-1);
+    const lowlinks = new Array(n).fill(-1);
+    const onStack = new Array(n).fill(false);
+    const stack = [];
+    const sccs = [];
+    let currentIndex = 0;
+    function strongConnect(node) {
+        indices[node] = currentIndex;
+        lowlinks[node] = currentIndex;
+        currentIndex++;
+        stack.push(node);
+        onStack[node] = true;
+        for (const dep of deps[node]){
+            if (dep >= n) continue;
+            if (indices[dep] === -1) {
+                strongConnect(dep);
+                lowlinks[node] = Math.min(lowlinks[node], lowlinks[dep]);
+            } else if (onStack[dep]) {
+                lowlinks[node] = Math.min(lowlinks[node], indices[dep]);
+            }
+        }
+        if (lowlinks[node] === indices[node]) {
+            const scc = [];
+            let member = stack.pop();
+            while(member != null){
+                onStack[member] = false;
+                scc.push(member);
+                if (member === node) break;
+                member = stack.pop();
+            }
+            sccs.push(scc);
+        }
+    }
+    for(let i = 0; i < n; i++){
+        if (indices[i] === -1) {
+            strongConnect(i);
+        }
+    }
+    // Sort each SCC internally and sort SCCs by smallest index
+    return sccs.map((scc)=>scc.sort((a, b)=>a - b)).sort((a, b)=>a[0] - b[0]);
+}
+/**
+ * Find cluster groups from model definitions.
+ * Groups are determined by strongly connected components in the
+ * fieldsMeta directed graph. Only circular fieldsMeta references
+ * force models into the same cluster.
+ */ export function findClusters(models) {
+    const fieldsMetaDeps = extractFieldsMetaDeps(models);
+    return findStronglyConnectedComponents(fieldsMetaDeps);
+}
+/**
+ * Sort models within a cluster group by interface deps (topological)
+ * with name as tiebreaker. Rewrite intra-cluster index refs to new
+ * positions. Cross-cluster refs are rewritten to global DocumentModelID
+ * strings using the provided mapping.
+ */ function prepareClusterModels(models, group, interfaceDeps, globalIDMap) {
+    const groupSet = new Set(group);
+    // Topological sort on interface deps within this group, name tiebreaker
+    const localInterfaceDeps = new Map();
+    for (const origIdx of group){
+        const filtered = new Set();
+        for (const dep of interfaceDeps[origIdx]){
+            if (groupSet.has(dep)) filtered.add(dep);
+        }
+        localInterfaceDeps.set(origIdx, filtered);
+    }
+    const remaining = new Map();
+    for (const origIdx of group){
+        remaining.set(origIdx, localInterfaceDeps.get(origIdx)?.size ?? 0);
+    }
+    const sorted = [];
+    const ready = group.filter((idx)=>(remaining.get(idx) ?? 0) === 0).map((idx)=>({
+            originalIndex: idx,
+            model: models[idx]
+        })).sort((a, b)=>a.model.name.localeCompare(b.model.name));
+    while(ready.length > 0){
+        const next = ready.shift();
+        if (next == null) break;
+        sorted.push(next);
+        for (const [origIdx, deps] of localInterfaceDeps){
+            if (deps.has(next.originalIndex)) {
+                const count = (remaining.get(origIdx) ?? 1) - 1;
+                remaining.set(origIdx, count);
+                if (count === 0) {
+                    const entry = {
+                        originalIndex: origIdx,
+                        model: models[origIdx]
+                    };
+                    const insertIdx = ready.findIndex((r)=>r.model.name.localeCompare(entry.model.name) > 0);
+                    if (insertIdx === -1) {
+                        ready.push(entry);
+                    } else {
+                        ready.splice(insertIdx, 0, entry);
+                    }
+                }
+            }
+        }
+    }
+    // Build mapping: original index → new cluster-internal index
+    const internalIndexMap = new Map();
+    for(let newIndex = 0; newIndex < sorted.length; newIndex++){
+        internalIndexMap.set(sorted[newIndex].originalIndex, newIndex);
+    }
+    // Rewrite references
+    return sorted.map(({ model })=>{
+        const rewritten = {
+            ...model
+        };
+        // Rewrite interface references
+        if (rewritten.interfaces != null) {
+            rewritten.interfaces = rewritten.interfaces.map((ref)=>{
+                const origIndex = parseLocalIndex(ref);
+                if (origIndex == null) return ref;
+                // Cross-cluster: use global ID
+                const globalID = globalIDMap.get(origIndex);
+                if (globalID != null) return globalID;
+                // Intra-cluster: use new position
+                const newIndex = internalIndexMap.get(origIndex);
+                if (newIndex != null) return `#${newIndex}`;
+                return ref;
+            });
+        }
+        // Rewrite fieldsMeta document references
+        if (rewritten.fieldsMeta != null) {
+            const newFieldsMeta = {
+                ...rewritten.fieldsMeta
+            };
+            for (const [key, meta] of Object.entries(newFieldsMeta)){
+                if (meta.type === 'document' && meta.model != null) {
+                    const origIndex = parseLocalIndex(meta.model);
+                    if (origIndex == null) continue;
+                    // Cross-cluster: use global ID
+                    const globalID = globalIDMap.get(origIndex);
+                    if (globalID != null) {
+                        newFieldsMeta[key] = {
+                            ...meta,
+                            model: globalID
+                        };
+                        continue;
+                    }
+                    // Intra-cluster: use new position
+                    const newIndex = internalIndexMap.get(origIndex);
+                    if (newIndex != null) {
+                        newFieldsMeta[key] = {
+                            ...meta,
+                            model: `#${newIndex}`
+                        };
+                    }
+                }
+            }
+            rewritten.fieldsMeta = newFieldsMeta;
+        }
+        return rewritten;
+    });
+}
+/**
+ * Topologically sort cluster groups by inter-group dependencies
+ * (interfaces + one-way fieldsMeta). Returns group indices in build order.
+ */ function sortGroupsByDeps(groups, interfaceDeps, fieldsMetaDeps) {
+    // Map each model index to its group index
+    const modelToGroup = new Map();
+    for(let gi = 0; gi < groups.length; gi++){
+        for (const modelIdx of groups[gi]){
+            modelToGroup.set(modelIdx, gi);
+        }
+    }
+    // Build inter-group dependency graph
+    const groupDeps = Array.from({
+        length: groups.length
+    }, ()=>new Set());
+    for(let gi = 0; gi < groups.length; gi++){
+        for (const modelIdx of groups[gi]){
+            // Interface deps
+            for (const dep of interfaceDeps[modelIdx]){
+                const depGroup = modelToGroup.get(dep);
+                if (depGroup != null && depGroup !== gi) {
+                    groupDeps[gi].add(depGroup);
+                }
+            }
+            // One-way fieldsMeta deps (to models outside this group)
+            for (const dep of fieldsMetaDeps[modelIdx]){
+                const depGroup = modelToGroup.get(dep);
+                if (depGroup != null && depGroup !== gi) {
+                    groupDeps[gi].add(depGroup);
+                }
+            }
+        }
+    }
+    // Kahn's topological sort
+    const remaining = groupDeps.map((deps)=>deps.size);
+    const ready = remaining.map((count, idx)=>count === 0 ? idx : -1).filter((idx)=>idx >= 0);
+    const sorted = [];
+    while(ready.length > 0){
+        const next = ready.shift();
+        if (next == null) break;
+        sorted.push(next);
+        for(let gi = 0; gi < groupDeps.length; gi++){
+            if (groupDeps[gi].has(next)) {
+                remaining[gi]--;
+                if (remaining[gi] === 0) {
+                    ready.push(gi);
+                }
+            }
+        }
+    }
+    return sorted;
+}
+function buildOptimalClusters(models, externalClusters) {
+    if (models.length === 0) {
+        return [];
+    }
+    const fieldsMetaDeps = extractFieldsMetaDeps(models);
+    const interfaceDeps = extractInterfaceDeps(models);
+    const groups = findStronglyConnectedComponents(fieldsMetaDeps);
+    const buildOrder = sortGroupsByDeps(groups, interfaceDeps, fieldsMetaDeps);
+    // Track global IDs of already-built models: original input index → global DocumentModelID string
+    const globalIDMap = new Map();
+    // Accumulate built clusters for use as externalClusters by later groups
+    const builtClusters = {
+        ...externalClusters ?? {}
+    };
+    const result = [];
+    for (const groupIdx of buildOrder){
+        const group = groups[groupIdx];
+        const prepared = prepareClusterModels(models, group, interfaceDeps, globalIDMap);
+        const builder = new ClusterBuilder({
+            externalClusters: Object.keys(builtClusters).length > 0 ? builtClusters : undefined
+        });
+        builder.addAll(prepared);
+        const cluster = builder.build();
+        result.push(cluster);
+        // Record global IDs for models in this cluster
+        const clusterDigest = digestJSON(cluster.models);
+        for(let i = 0; i < group.length; i++){
+            // Find which cluster-internal index corresponds to this original model
+            // prepareClusterModels sorts by interface deps + name, so we match by name
+            const origIdx = group[i];
+            const modelName = models[origIdx].name;
+            const clusterInternalIdx = cluster.models.findIndex((m)=>m.name === modelName);
+            if (clusterInternalIdx !== -1) {
+                const globalID = new DocumentModelID(clusterDigest, clusterInternalIdx);
+                globalIDMap.set(origIdx, globalID.toString());
+            }
+        }
+        Object.assign(builtClusters, clusterToRecord(cluster));
+    }
+    return result;
+}
+/**
+ * Higher-level builder that produces optimally-split clusters from model
+ * definitions. Independent models get their own cluster; cross-referencing
+ * models are grouped together. This maximizes content-addressed
+ * deduplication while keeping the ClusterBuilder as an internal detail.
+ */ export class GraphBuilder {
+    #models = [];
+    #externalClusters;
+    constructor(params = {}){
+        this.#externalClusters = params.externalClusters ?? {};
+    }
+    add(model) {
+        this.#models.push(model);
+        return this;
+    }
+    addAll(models) {
+        this.#models.push(...models);
+        return this;
+    }
+    build() {
+        const externalClusters = Object.keys(this.#externalClusters).length > 0 ? this.#externalClusters : undefined;
+        const clusters = buildOptimalClusters(this.#models, externalClusters);
+        const record = {};
+        for (const cluster of clusters){
+            Object.assign(record, clusterToRecord(cluster));
+        }
+        return record;
+    }
+}

package/lib/models/value.js

@@ -1 +1,16 @@
-export const binaryStringValue={title:"KubunBinaryValue",type:"string",pattern:"^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$"};export const didStringValue={title:"KubunDIDValue",type:"string",pattern:"^did:[a-z0-9]+:"};export const signedJWTStringValue={title:"KubunSignedJWTValue",type:"string",pattern:"^[a-zA-Z0-9_-]+.[a-zA-Z0-9_-]+.[a-zA-Z0-9_-]+$"};
+export const binaryStringValue = {
+    title: 'KubunBinaryValue',
+    type: 'string',
+    // Base 64 encoding
+    pattern: '^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$'
+};
+export const didStringValue = {
+    title: 'KubunDIDValue',
+    type: 'string',
+    pattern: '^did:[a-z0-9]+:'
+};
+export const signedJWTStringValue = {
+    title: 'KubunSignedJWTValue',
+    type: 'string',
+    pattern: '^[a-zA-Z0-9_-]+.[a-zA-Z0-9_-]+.[a-zA-Z0-9_-]+$'
+};

package/lib/semantic.js

@@ -1 +1,23 @@
-export const KubunSpanNames={GRAPH_QUERY:"kubun.graph.query",GRAPH_MUTATE:"kubun.graph.mutate",GRAPH_SUBSCRIBE:"kubun.graph.subscribe",GRAPH_DEPLOY:"kubun.graph.deploy",GRAPHQL_EXECUTE:"kubun.graphql.execute",DATA_QUERY:"kubun.data.query",DATA_MUTATE:"kubun.data.mutate",DATA_TRANSACTION:"kubun.data.transaction"};export const KubunAttributeKeys={GRAPH_ID:"kubun.graph.id",GRAPHQL_OPERATION_TYPE:"graphql.operation.type",GRAPHQL_DOCUMENT:"graphql.document",GRAPHQL_VARIABLES:"graphql.variables",MODEL_ID:"kubun.model.id",DOCUMENT_ID:"kubun.document.id",DOCUMENTS_COUNT:"kubun.documents.count",MUTATION_TYPE:"kubun.mutation.type",MUTATION_DATA:"kubun.mutation.data",QUERY_FILTER:"kubun.query.filter",ERROR_CODE:"kubun.error.code"};
+export const KubunSpanNames = {
+    GRAPH_QUERY: 'kubun.graph.query',
+    GRAPH_MUTATE: 'kubun.graph.mutate',
+    GRAPH_SUBSCRIBE: 'kubun.graph.subscribe',
+    GRAPH_DEPLOY: 'kubun.graph.deploy',
+    GRAPHQL_EXECUTE: 'kubun.graphql.execute',
+    DATA_QUERY: 'kubun.data.query',
+    DATA_MUTATE: 'kubun.data.mutate',
+    DATA_TRANSACTION: 'kubun.data.transaction'
+};
+export const KubunAttributeKeys = {
+    GRAPH_ID: 'kubun.graph.id',
+    GRAPHQL_OPERATION_TYPE: 'graphql.operation.type',
+    GRAPHQL_DOCUMENT: 'graphql.document',
+    GRAPHQL_VARIABLES: 'graphql.variables',
+    MODEL_ID: 'kubun.model.id',
+    DOCUMENT_ID: 'kubun.document.id',
+    DOCUMENTS_COUNT: 'kubun.documents.count',
+    MUTATION_TYPE: 'kubun.mutation.type',
+    MUTATION_DATA: 'kubun.mutation.data',
+    QUERY_FILTER: 'kubun.query.filter',
+    ERROR_CODE: 'kubun.error.code'
+};