@ggui-ai/protocol 0.1.0-rc.1

package/dist/schema-learning/merge.js

@@ -0,0 +1,146 @@
+/** Infer a JSON Schema from a single JSON value. */
+export function inferSchema(value) {
+    if (value === null)
+        return { type: "null" };
+    if (typeof value === "boolean")
+        return { type: "boolean" };
+    if (typeof value === "number") {
+        return { type: Number.isInteger(value) ? "integer" : "number" };
+    }
+    if (typeof value === "string")
+        return { type: "string" };
+    if (Array.isArray(value)) {
+        if (value.length === 0)
+            return { type: "array" };
+        // Fold all elements into a single item schema.
+        let items = inferSchema(value[0]);
+        for (let i = 1; i < value.length; i++) {
+            items = mergeTwoSchemas(items, inferSchema(value[i]));
+        }
+        return { type: "array", items };
+    }
+    // Object
+    const obj = value;
+    const keys = Object.keys(obj);
+    const properties = {};
+    for (const k of keys) {
+        properties[k] = inferSchema(obj[k]);
+    }
+    return {
+        type: "object",
+        properties,
+        required: keys.slice().sort(),
+    };
+}
+/**
+ * Merge a new observed sample into an existing schema. If `existing` is null,
+ * returns the schema inferred from `sample` alone.
+ */
+export function mergeSchema(existing, sample) {
+    const inferred = inferSchema(sample);
+    if (!existing)
+        return inferred;
+    return mergeTwoSchemas(existing, inferred);
+}
+/**
+ * Merge two schemas into one that accepts values satisfying either. Exported
+ * for the seeder path (combining two known schemas without sampling).
+ */
+export function mergeTwoSchemas(a, b) {
+    // null + X → X nullable
+    if (a.type === "null" && b.type !== "null")
+        return withNullable(b);
+    if (b.type === "null" && a.type !== "null")
+        return withNullable(a);
+    if (a.type === "null" && b.type === "null")
+        return { type: "null" };
+    // Same type — structural merge.
+    if (a.type === b.type) {
+        if (a.type === "object")
+            return mergeObjects(a, b);
+        if (a.type === "array")
+            return mergeArrays(a, b);
+        // Primitives — keep a's metadata as the canonical one; carry nullability forward.
+        const merged = { type: a.type };
+        if (a.nullable || b.nullable)
+            merged.nullable = true;
+        if (a.format && b.format && a.format === b.format)
+            merged.format = a.format;
+        return merged;
+    }
+    // integer + number → number (widen)
+    if ((a.type === "integer" && b.type === "number") || (a.type === "number" && b.type === "integer")) {
+        const merged = { type: "number" };
+        if (a.nullable || b.nullable)
+            merged.nullable = true;
+        return merged;
+    }
+    // Conflicting types — union via anyOf.
+    return { anyOf: dedupeAnyOf([...flattenAnyOf(a), ...flattenAnyOf(b)]) };
+}
+function mergeObjects(a, b) {
+    const aProps = a.properties ?? {};
+    const bProps = b.properties ?? {};
+    const allKeys = new Set([...Object.keys(aProps), ...Object.keys(bProps)]);
+    const merged = {};
+    for (const k of allKeys) {
+        const pa = aProps[k];
+        const pb = bProps[k];
+        if (pa && pb)
+            merged[k] = mergeTwoSchemas(pa, pb);
+        else
+            merged[k] = (pa ?? pb);
+    }
+    // Required = intersection. A field missing from either sample cannot be required.
+    const aReq = new Set(a.required ?? []);
+    const bReq = b.required ?? [];
+    const requiredSet = new Set();
+    for (const k of bReq)
+        if (aReq.has(k))
+            requiredSet.add(k);
+    const required = Array.from(requiredSet).sort();
+    const out = { type: "object", properties: merged };
+    if (required.length > 0)
+        out.required = required;
+    if (a.nullable || b.nullable)
+        out.nullable = true;
+    return out;
+}
+function mergeArrays(a, b) {
+    const items = a.items && b.items ? mergeTwoSchemas(a.items, b.items) : (a.items ?? b.items);
+    const out = { type: "array" };
+    if (items)
+        out.items = items;
+    if (a.nullable || b.nullable)
+        out.nullable = true;
+    return out;
+}
+function withNullable(s) {
+    if (s.nullable)
+        return s;
+    return { ...s, nullable: true };
+}
+function flattenAnyOf(s) {
+    if (s.anyOf && s.anyOf.length > 0)
+        return s.anyOf.slice();
+    return [s];
+}
+function dedupeAnyOf(list) {
+    const seen = new Map();
+    for (const s of list) {
+        const key = canonicalKey(s);
+        if (!seen.has(key))
+            seen.set(key, s);
+    }
+    return Array.from(seen.values());
+}
+/** Deterministic stable key — recursive, sorts object keys at every depth. */
+function canonicalKey(v) {
+    if (v === null || typeof v !== "object")
+        return JSON.stringify(v);
+    if (Array.isArray(v))
+        return "[" + v.map(canonicalKey).join(",") + "]";
+    const obj = v;
+    const keys = Object.keys(obj).sort();
+    return "{" + keys.map((k) => JSON.stringify(k) + ":" + canonicalKey(obj[k])).join(",") + "}";
+}

package/dist/schemas/blueprint.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Zod schema mirror of {@link Blueprint}. Structural-mirror discipline
+ * matches `data-contract.ts`'s posture: the TS interface in
+ * `../types/blueprint.ts` is the declared source of truth; the schema
+ * here is `z.ZodType<Blueprint>` so any drift fails compile.
+ */
+import { z } from 'zod';
+import type { AppBlueprintSearchConfig, Blueprint, BlueprintSearchWeights, BlueprintVariance } from '../types/blueprint';
+/** Zod mirror of {@link BlueprintVariance}. */
+export declare const blueprintVarianceSchema: z.ZodType<BlueprintVariance>;
+/**
+ * Zod mirror of {@link Blueprint}. Required fields are listed first;
+ * `passthrough()` is intentionally NOT applied — blueprint rows are
+ * a closed shape (every field is enumerated here), and stray fields
+ * in persisted rows are a bug worth surfacing rather than tolerating.
+ */
+export declare const blueprintSchema: z.ZodType<Blueprint>;
+/**
+ * Zod mirror of {@link BlueprintSearchWeights}. Every axis is a
+ * non-negative finite number. Per-axis defaults are applied at the
+ * impl layer (see `DEFAULT_BLUEPRINT_SEARCH_WEIGHTS` in
+ * `@ggui-ai/mcp-server-core`); this schema only validates the shape
+ * an operator passes through `App.blueprintSearchConfig.weights`
+ * when the operator provides EVERY axis.
+ */
+export declare const blueprintSearchWeightsSchema: z.ZodType<BlueprintSearchWeights>;
+/**
+ * Zod mirror of {@link AppBlueprintSearchConfig}. All fields optional;
+ * server applies the global default for any axis the operator omits.
+ */
+export declare const appBlueprintSearchConfigSchema: z.ZodType<AppBlueprintSearchConfig>;
+//# sourceMappingURL=blueprint.d.ts.map

package/dist/schemas/blueprint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blueprint.d.ts","sourceRoot":"","sources":["../../src/schemas/blueprint.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AACxB,OAAO,KAAK,EACV,wBAAwB,EACxB,SAAS,EACT,sBAAsB,EACtB,iBAAiB,EAClB,MAAM,oBAAoB,CAAC;AAG5B,+CAA+C;AAC/C,eAAO,MAAM,uBAAuB,EAAE,CAAC,CAAC,OAAO,CAAC,iBAAiB,CAOtB,CAAC;AAE5C;;;;;GAKG;AACH,eAAO,MAAM,eAAe,EAAE,CAAC,CAAC,OAAO,CAAC,SAAS,CAwBd,CAAC;AAEpC;;;;;;;GAOG;AACH,eAAO,MAAM,4BAA4B,EAAE,CAAC,CAAC,OAAO,CAAC,sBAAsB,CAQ3B,CAAC;AAmBjD;;;GAGG;AACH,eAAO,MAAM,8BAA8B,EAAE,CAAC,CAAC,OAAO,CAAC,wBAAwB,CAM7B,CAAC"}

package/dist/schemas/blueprint.js

@@ -0,0 +1,92 @@
+/**
+ * Zod schema mirror of {@link Blueprint}. Structural-mirror discipline
+ * matches `data-contract.ts`'s posture: the TS interface in
+ * `../types/blueprint.ts` is the declared source of truth; the schema
+ * here is `z.ZodType<Blueprint>` so any drift fails compile.
+ */
+import { z } from 'zod';
+import { dataContractSchema, jsonValueSchema } from './data-contract.js';
+/** Zod mirror of {@link BlueprintVariance}. */
+export const blueprintVarianceSchema = z
+    .object({
+    persona: z.string().optional(),
+    aesthetic: z.string().optional(),
+    context: z.record(z.string(), jsonValueSchema).optional(),
+    seedPrompt: z.string().optional(),
+})
+    .strict();
+/**
+ * Zod mirror of {@link Blueprint}. Required fields are listed first;
+ * `passthrough()` is intentionally NOT applied — blueprint rows are
+ * a closed shape (every field is enumerated here), and stray fields
+ * in persisted rows are a bug worth surfacing rather than tolerating.
+ */
+export const blueprintSchema = z
+    .object({
+    blueprintId: z.string().min(1),
+    contractHash: z.string().min(1),
+    appId: z.string().min(1),
+    codeS3Url: z.string().optional(),
+    codeHash: z.string().optional(),
+    generator: z.string().min(1),
+    validatorScore: z.number().min(0).max(1).optional(),
+    variance: blueprintVarianceSchema,
+    // `true | undefined` — store-level invariant: at most one row per
+    // `(appId, contractHash)` carries the flag. `z.literal(true)` enforces
+    // the "never false" half of the type.
+    isOperatorDefault: z.literal(true).optional(),
+    createdAt: z.string().min(1),
+    createdBy: z.enum(['agent', 'operator']),
+    contract: dataContractSchema,
+    // Optional cached embedding vector. Written by BlueprintStore.put
+    // when an EmbeddingProvider is wired; read by BlueprintSearch on
+    // the embed axis. `readonly number[]` on the TS side; zod can't
+    // express readonly so a plain array survives the assignability
+    // check via the outer `as z.ZodType<Blueprint>` cast.
+    contractEmbedding: z.array(z.number()).optional(),
+})
+    .strict();
+/**
+ * Zod mirror of {@link BlueprintSearchWeights}. Every axis is a
+ * non-negative finite number. Per-axis defaults are applied at the
+ * impl layer (see `DEFAULT_BLUEPRINT_SEARCH_WEIGHTS` in
+ * `@ggui-ai/mcp-server-core`); this schema only validates the shape
+ * an operator passes through `App.blueprintSearchConfig.weights`
+ * when the operator provides EVERY axis.
+ */
+export const blueprintSearchWeightsSchema = z
+    .object({
+    hash: z.number().min(0),
+    embed: z.number().min(0),
+    struct: z.number().min(0),
+    variance: z.number().min(0),
+    intent: z.number().min(0),
+})
+    .strict();
+/**
+ * Zod mirror of the partial-weights shape on
+ * {@link AppBlueprintSearchConfig.weights}. Built directly rather
+ * than as `.partial()` on `blueprintSearchWeightsSchema` because
+ * that schema is typed `z.ZodType<...>` for cross-zod-version
+ * compatibility — `.partial()` only exists on `z.ZodObject`.
+ */
+const partialBlueprintSearchWeightsSchema = z
+    .object({
+    hash: z.number().min(0).optional(),
+    embed: z.number().min(0).optional(),
+    struct: z.number().min(0).optional(),
+    variance: z.number().min(0).optional(),
+    intent: z.number().min(0).optional(),
+})
+    .strict();
+/**
+ * Zod mirror of {@link AppBlueprintSearchConfig}. All fields optional;
+ * server applies the global default for any axis the operator omits.
+ */
+export const appBlueprintSearchConfigSchema = z
+    .object({
+    weights: partialBlueprintSearchWeightsSchema.optional(),
+    threshold: z.number().min(0).max(1).optional(),
+    topK: z.number().int().min(1).optional(),
+})
+    .strict();