@skaile/workspaces 3.26.0 → 3.27.0

package/dist/{chunk-CP62G5PK.js → chunk-53ORCYPJ.js}

@@ -1,5 +1,189 @@
 import * as z from 'zod';
 
+// factory-assets/connectors/flow/contract/classifier.ts
+var RESERVED_CLASSIFIER_FIELDS = ["confidence", "calibrated"];
+var MAX_CHOICE_OPTIONS = 255;
+var MIN_SCORE_LEVELS = 2;
+var MAX_SCORE_LEVELS = 10;
+function declaredOutputProperties(outputSchema) {
+  if (typeof outputSchema !== "object" || outputSchema === null) return [];
+  const properties = outputSchema.properties;
+  if (typeof properties !== "object" || properties === null) return [];
+  return Object.keys(properties);
+}
+function declaresReservedClassifierField(outputSchema) {
+  const declared = declaredOutputProperties(outputSchema);
+  return RESERVED_CLASSIFIER_FIELDS.some((name) => declared.includes(name));
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function typeSet(schema) {
+  const type = schema.type;
+  if (typeof type === "string") return /* @__PURE__ */ new Set([type]);
+  if (Array.isArray(type) && type.every((entry) => typeof entry === "string")) {
+    return new Set(type);
+  }
+  return void 0;
+}
+function sameSet(actual, expected) {
+  return actual !== void 0 && actual.size === expected.length && expected.every((entry) => actual.has(entry));
+}
+function decisionOf(field, schema) {
+  if (!isRecord(schema)) return { issue: `decision property ${field} must be a schema object` };
+  const types = typeSet(schema);
+  if (sameSet(types, ["boolean"]) && schema.enum === void 0 && schema.oneOf === void 0) {
+    return {
+      decision: {
+        kind: "binary",
+        field,
+        ...typeof schema.description === "string" ? { description: schema.description } : {}
+      }
+    };
+  }
+  if (Array.isArray(schema.enum)) {
+    if (types !== void 0 && !sameSet(types, ["string"])) {
+      return { issue: `decision property ${field}: an enum decision must be typed string` };
+    }
+    const labels = schema.enum;
+    if (!labels.every((label) => typeof label === "string" && label.length > 0)) {
+      return { issue: `decision property ${field}: every enum label must be a non-empty string` };
+    }
+    if (new Set(labels).size !== labels.length) {
+      return { issue: `decision property ${field}: enum labels must be unique` };
+    }
+    if (labels.length < 2 || labels.length > MAX_CHOICE_OPTIONS) {
+      return {
+        issue: `decision property ${field}: a choice needs 2\u2013${MAX_CHOICE_OPTIONS} labels`
+      };
+    }
+    return {
+      decision: {
+        kind: "choice",
+        field,
+        options: Object.fromEntries(labels.map((label) => [label, null]))
+      }
+    };
+  }
+  if (Array.isArray(schema.oneOf)) {
+    const entries = schema.oneOf;
+    if (!entries.every(
+      (entry) => isRecord(entry) && Object.keys(entry).every((key) => key === "const" || key === "description") && "const" in entry && (entry.description === void 0 || typeof entry.description === "string")
+    )) {
+      return {
+        issue: `decision property ${field}: every oneOf entry must be { "const": \u2026, "description": "\u2026" }`
+      };
+    }
+    const consts = entries.map(
+      (entry) => entry.const
+    );
+    if (new Set(consts).size !== consts.length) {
+      return { issue: `decision property ${field}: oneOf consts must be unique` };
+    }
+    if (consts.every((value) => typeof value === "string" && value.length > 0)) {
+      if (types !== void 0 && !sameSet(types, ["string"])) {
+        return {
+          issue: `decision property ${field}: a string-labelled choice must be typed string`
+        };
+      }
+      if (consts.length < 2 || consts.length > MAX_CHOICE_OPTIONS) {
+        return {
+          issue: `decision property ${field}: a choice needs 2\u2013${MAX_CHOICE_OPTIONS} options`
+        };
+      }
+      return {
+        decision: {
+          kind: "choice",
+          field,
+          options: Object.fromEntries(
+            entries.map((entry) => [
+              entry.const,
+              entry.description ?? null
+            ])
+          )
+        }
+      };
+    }
+    if (consts.every((value) => typeof value === "number" && Number.isInteger(value))) {
+      if (types !== void 0 && !sameSet(types, ["integer"])) {
+        return { issue: `decision property ${field}: a score must be typed integer` };
+      }
+      if (consts.length < MIN_SCORE_LEVELS || consts.length > MAX_SCORE_LEVELS) {
+        return {
+          issue: `decision property ${field}: a score needs ${MIN_SCORE_LEVELS}\u2013${MAX_SCORE_LEVELS} levels`
+        };
+      }
+      const ordered = [...entries].sort(
+        (a, b) => a.const - b.const
+      );
+      return {
+        decision: {
+          kind: "score",
+          field,
+          levels: ordered.map((entry) => entry.description ?? String(entry.const)),
+          values: ordered.map((entry) => entry.const)
+        }
+      };
+    }
+    return {
+      issue: `decision property ${field}: oneOf consts must be all non-empty strings (choice) or all integers (score)`
+    };
+  }
+  return {
+    issue: `decision property ${field} must be a boolean, a string enum, or a oneOf of { const, description }`
+  };
+}
+function checkClassifierShape(outputSchema) {
+  if (!declaresReservedClassifierField(outputSchema)) return { classifier: false };
+  const schema = outputSchema;
+  const properties = schema.properties;
+  const issues = [];
+  if (schema.type !== "object") issues.push('the output schema must be "type": "object"');
+  if (schema.additionalProperties !== false) {
+    issues.push("the output schema must set additionalProperties: false");
+  }
+  const confidence = properties.confidence;
+  if (!isRecord(confidence) || !sameSet(typeSet(confidence), ["number", "null"])) {
+    issues.push('confidence must be typed ["number", "null"]');
+  }
+  const calibrated = properties.calibrated;
+  if (!isRecord(calibrated) || !sameSet(typeSet(calibrated), ["boolean"])) {
+    issues.push('calibrated must be typed "boolean"');
+  }
+  const decisionFields = Object.keys(properties).filter(
+    (name) => !RESERVED_CLASSIFIER_FIELDS.includes(name)
+  );
+  let decision;
+  if (decisionFields.length !== 1) {
+    issues.push(
+      `a classifier node declares exactly one decision property besides confidence and calibrated (found ${decisionFields.length})`
+    );
+  } else {
+    const result = decisionOf(decisionFields[0], properties[decisionFields[0]]);
+    if ("issue" in result) issues.push(result.issue);
+    else decision = result.decision;
+  }
+  const required = Array.isArray(schema.required) ? schema.required : [];
+  const expectedRequired = [...decisionFields.slice(0, 1), ...RESERVED_CLASSIFIER_FIELDS];
+  if (required.length !== expectedRequired.length || !expectedRequired.every((name) => required.includes(name))) {
+    issues.push(`required must be exactly [${expectedRequired.map((n) => `"${n}"`).join(", ")}]`);
+  }
+  if (issues.length > 0 || !decision) return { classifier: true, issues };
+  return { classifier: true, decision };
+}
+function classifierDecision(outputSchema) {
+  const check = checkClassifierShape(outputSchema);
+  return check.classifier && "decision" in check ? check.decision : void 0;
+}
+function withoutReservedClassifierFields(outputSchema) {
+  const properties = { ...outputSchema.properties };
+  for (const name of RESERVED_CLASSIFIER_FIELDS) delete properties[name];
+  const required = Array.isArray(outputSchema.required) ? outputSchema.required.filter(
+    (name) => !RESERVED_CLASSIFIER_FIELDS.includes(String(name))
+  ) : void 0;
+  return { ...outputSchema, properties, ...required ? { required } : {} };
+}
+
 // factory-assets/connectors/flow/contract/expression.ts
 var FLOW_EXPRESSION_LIMITS = Object.freeze({
   maxLength: 4096,
@@ -235,20 +419,32 @@ function assertBooleanOperand(value, position) {
   if (!isBooleanOperand(value)) throw expressionError("requires boolean operands", position);
 }
 var Parser = class {
-  constructor(tokens, context, onPath, onBooleanPath, onEvaluatedPath) {
+  constructor(tokens, context, onPath, onBooleanPath, onEvaluatedPath, onComparison) {
     this.tokens = tokens;
     this.context = context;
     this.onPath = onPath;
     this.onBooleanPath = onBooleanPath;
     this.onEvaluatedPath = onEvaluatedPath;
+    this.onComparison = onComparison;
   }
   tokens;
   context;
   onPath;
   onBooleanPath;
   onEvaluatedPath;
+  onComparison;
   index = 0;
   nesting = 0;
+  /** Literal `path == true` conjuncts already parsed, one frame per enclosing `&&` chain. */
+  guardFrames = [];
+  /**
+   * Guards the operand {@link parseComparison} just parsed establishes when true:
+   * its own path for a literal `path == true`, or every guard of a parenthesized
+   * `&&` group, which is true only when all its conjuncts are.
+   */
+  lastGuards = [];
+  /** Guards of the `&&` / `||` chain that just finished; empty once a `||` joined it. */
+  lastChainGuards = [];
   parse(evaluate2 = true) {
     const value = this.parseOr(evaluate2);
     const trailing = this.peek();
@@ -272,7 +468,9 @@ var Parser = class {
   }
   parseOr(evaluate2) {
     let value = this.parseAnd(evaluate2);
+    let disjunction = false;
     while (this.peek().value === "||") {
+      disjunction = true;
       const operator = this.take();
       assertBooleanOperand(value, operator.position);
       if (isStaticPath(value)) this.onBooleanPath?.(value.path);
@@ -282,31 +480,51 @@ var Parser = class {
       if (isStaticPath(right)) this.onBooleanPath?.(right.path);
       value = evaluate2 ? value === true || right === true : STATIC_BOOLEAN;
     }
+    if (disjunction) this.lastChainGuards = [];
     return value;
   }
   parseAnd(evaluate2) {
-    let value = this.parseComparison(evaluate2);
-    while (this.peek().value === "&&") {
-      const operator = this.take();
-      assertBooleanOperand(value, operator.position);
-      if (isStaticPath(value)) this.onBooleanPath?.(value.path);
-      const evaluateRight = evaluate2 && value === true;
-      const right = this.parseComparison(evaluateRight);
-      assertBooleanOperand(right, operator.position);
-      if (isStaticPath(right)) this.onBooleanPath?.(right.path);
-      value = evaluate2 ? value === true && right === true : STATIC_BOOLEAN;
+    const guards = [];
+    this.guardFrames.push(guards);
+    try {
+      let value = this.parseComparison(evaluate2);
+      guards.push(...this.lastGuards);
+      while (this.peek().value === "&&") {
+        const operator = this.take();
+        assertBooleanOperand(value, operator.position);
+        if (isStaticPath(value)) this.onBooleanPath?.(value.path);
+        const evaluateRight = evaluate2 && value === true;
+        const right = this.parseComparison(evaluateRight);
+        guards.push(...this.lastGuards);
+        assertBooleanOperand(right, operator.position);
+        if (isStaticPath(right)) this.onBooleanPath?.(right.path);
+        value = evaluate2 ? value === true && right === true : STATIC_BOOLEAN;
+      }
+      this.lastChainGuards = [...guards];
+      return value;
+    } finally {
+      this.guardFrames.pop();
     }
-    return value;
   }
   parseComparison(evaluate2) {
+    const group = this.peek().value === "(";
     const left = this.parseUnary(evaluate2);
     const token = this.peek();
     if (token.kind !== "operator" || !["==", "!=", "<", "<=", ">", ">=", "in"].includes(String(token.value))) {
+      this.lastGuards = group ? this.lastChainGuards : [];
       return left;
     }
     this.take();
     const right = this.parseUnary(evaluate2);
-    return evaluate2 ? compare(String(token.value), left, right, token.position) : STATIC_BOOLEAN;
+    const operator = String(token.value);
+    this.onComparison?.({
+      operator,
+      left: isStaticPath(left) ? { path: left.path } : { literal: left },
+      right: isStaticPath(right) ? { path: right.path } : { literal: right },
+      guards: this.guardFrames.flat()
+    });
+    this.lastGuards = operator === "==" && isStaticPath(left) && right === true ? [left.path] : [];
+    return evaluate2 ? compare(operator, left, right, token.position) : STATIC_BOOLEAN;
   }
   parseUnary(evaluate2) {
     const operator = this.accept("!");
@@ -360,6 +578,21 @@ var Parser = class {
     }
   }
 };
+function inspectFlowExpressionComparisons(expression) {
+  const tokens = tokenize(expression);
+  if (expression.trim() === "default") return [];
+  const comparisons = [];
+  const context = { flow: { input: {} }, nodes: {} };
+  new Parser(
+    tokens,
+    context,
+    void 0,
+    void 0,
+    void 0,
+    (comparison) => comparisons.push(comparison)
+  ).parse(false);
+  return comparisons;
+}
 function inspectFlowExpression(expression, requireBoolean = true) {
   const tokens = tokenize(expression);
   if (expression.trim() === "default") return [];
@@ -949,6 +1182,7 @@ var FlowDefinitionSchema = FlowDefinitionObjectSchema.superRefine((flow, context
       }
     }
   }
+  validateClassifierRules(flow, context);
   const state = /* @__PURE__ */ new Map();
   for (const nodeId of nodeIds) {
     if (state.has(nodeId)) continue;
@@ -973,6 +1207,103 @@ var FlowDefinitionSchema = FlowDefinitionObjectSchema.superRefine((flow, context
     }
   }
 });
+var ORDERING_OPERATORS = /* @__PURE__ */ new Set(["<", "<=", ">", ">="]);
+function validateClassifierRules(flow, context) {
+  const classifierIds = /* @__PURE__ */ new Set();
+  for (const [nodeIndex, node] of flow.nodes.entries()) {
+    const outputSchema = node.contract?.output?.fields;
+    const path = ["nodes", nodeIndex, "contract", "output", "fields"];
+    if (node.run.kind === "subprompt") {
+      const check = checkClassifierShape(outputSchema);
+      if (!check.classifier) continue;
+      classifierIds.add(node.id);
+      if ("issues" in check) {
+        context.addIssue({
+          code: "custom",
+          path,
+          message: `subprompt ${node.id} declares a reserved classifier field but is not classifier-shaped: ${check.issues.join("; ")}`
+        });
+      }
+      continue;
+    }
+    if ((node.run.kind === "agent" || node.run.kind === "sub-flow") && declaresReservedClassifierField(outputSchema)) {
+      const names = RESERVED_CLASSIFIER_FIELDS.filter(
+        (name) => declaredOutputProperties(outputSchema).includes(name)
+      );
+      context.addIssue({
+        code: "custom",
+        path,
+        message: `${names.join(" and ")} ${names.length > 1 ? "are" : "is"} reserved for classifier-shaped subprompt nodes; ${node.run.kind} node ${node.id} cannot declare ${names.length > 1 ? "them" : "it"}`
+      });
+    }
+  }
+  if (classifierIds.size === 0) return;
+  const reservedRead = (path) => {
+    const segments = path.split(".");
+    if (segments.length !== 5 || segments[0] !== "nodes" || segments[2] !== "output" || segments[3] !== "fields" || !classifierIds.has(segments[1]) || !RESERVED_CLASSIFIER_FIELDS.includes(segments[4])) {
+      return void 0;
+    }
+    return { producer: segments[1], field: segments[4] };
+  };
+  const readsReserved = (expression) => {
+    try {
+      return inspectFlowExpression(expression, false).some(({ path }) => reservedRead(path));
+    } catch {
+      return false;
+    }
+  };
+  const checkGuards = (expression, path) => {
+    let comparisons;
+    try {
+      comparisons = inspectFlowExpressionComparisons(expression);
+    } catch {
+      return;
+    }
+    for (const comparison of comparisons) {
+      if (!ORDERING_OPERATORS.has(comparison.operator)) continue;
+      for (const operand of [comparison.left, comparison.right]) {
+        if (!("path" in operand)) continue;
+        const read = reservedRead(operand.path);
+        if (read?.field !== "confidence") continue;
+        const guard = `nodes.${read.producer}.output.fields.calibrated`;
+        if (comparison.guards.includes(guard)) continue;
+        context.addIssue({
+          code: "custom",
+          path,
+          message: `${operand.path} is null when the classifier is uncalibrated, so an ordering comparison on it must be guarded: put the literal conjunct \`${guard} == true\` earlier in the same && chain, optionally parenthesized (\`true == \u2026\`, \`!= false\` and a guard inside \`||\` are not accepted)`
+        });
+      }
+    }
+  };
+  for (const [nodeIndex, node] of flow.nodes.entries()) {
+    for (const [requireIndex, requirement] of node.contract?.requires?.entries() ?? []) {
+      if (!readsReserved(requirement.expr)) continue;
+      context.addIssue({
+        code: "custom",
+        path: ["nodes", nodeIndex, "contract", "requires", requireIndex, "expr"],
+        message: "a contract.requires guard cannot read a classifier's confidence or calibrated; decide on a classifier's answer at a router, which has a default route"
+      });
+    }
+    for (const [bindingName2, binding] of Object.entries(node.contract?.input ?? {})) {
+      for (const expression of collectFlowBindingExpressions(binding)) {
+        checkGuards(expression, ["nodes", nodeIndex, "contract", "input", bindingName2]);
+      }
+    }
+    if (node.run.kind !== "router") continue;
+    const routes = node.run.routes;
+    for (const [routeIndex, route] of routes.entries()) {
+      checkGuards(route.when, ["nodes", nodeIndex, "run", "routes", routeIndex, "when"]);
+    }
+    const readsAny = routes.some((route) => readsReserved(route.when));
+    if (readsAny && routes.at(-1)?.when.trim() !== "default") {
+      context.addIssue({
+        code: "custom",
+        path: ["nodes", nodeIndex, "run", "routes"],
+        message: `router ${node.id} reads a classifier's confidence or calibrated, so its last route must be the unconditional "default": on the uncalibrated fallback every guarded route is false, and without a default the router would settle nowhere`
+      });
+    }
+  }
+}
 var successfullyParsedDefinitions = /* @__PURE__ */ new WeakMap();
 function valueFingerprint(value, ancestors) {
   if (value === null) return "null";
@@ -1279,6 +1610,6 @@ function parseFlowDefinition(data) {
   return normalizeV1(data);
 }
 
-export { FLOW_EXPRESSION_LIMITS, FlowDefinitionSchema, FlowExpressionError, InputSchema, collectFlowBindingExpressions, evaluate, evaluateFlowExpression, inspectFlowExpression, normalizeV1, parseFlowDefinition, resolveFlowBindings, stableFlowJson };
-//# sourceMappingURL=chunk-CP62G5PK.js.map
-//# sourceMappingURL=chunk-CP62G5PK.js.map
+export { FLOW_EXPRESSION_LIMITS, FlowDefinitionSchema, FlowExpressionError, InputSchema, RESERVED_CLASSIFIER_FIELDS, checkClassifierShape, classifierDecision, collectFlowBindingExpressions, declaresReservedClassifierField, evaluate, evaluateFlowExpression, inspectFlowExpression, inspectFlowExpressionComparisons, normalizeV1, parseFlowDefinition, resolveFlowBindings, stableFlowJson, withoutReservedClassifierFields };
+//# sourceMappingURL=chunk-53ORCYPJ.js.map
+//# sourceMappingURL=chunk-53ORCYPJ.js.map