@almadar/core 10.10.0 → 10.11.0

package/dist/{compose-behaviors-CQCfFBnR.d.ts → compose-behaviors-D9bQEgqN.d.ts}

@@ -1,4 +1,4 @@
-import { a as OrbitalDefinition, O as OrbitalSchema } from './schema-C4ia6wFF.js';
+import { a as OrbitalDefinition, O as OrbitalSchema } from './schema-CtOoanon.js';
 
 /**
  * Event Wiring

package/dist/factory/index.d.ts

@@ -1,6 +1,6 @@
-import { g as FactoryParamValue, c as FactoryConfigTier, b as FactoryConfigParam, F as FactoryCallSite, h as FactorySignature, R as RuleOverlay, p as RuleOverlayEntry, o as PresentationOverlay, q as TraitOverlay } from '../types-DzmFPbo4.js';
-export { a as FactoryCallSiteParams, d as FactoryEntitySignature, e as FactoryEventSignature, f as FactoryPageSignature, i as FactorySignatureCatalog, j as FactorySignatureEntityField, k as FactoryTraitSignature, m as JsonSchema, n as JsonSchemaType, J as JsonValue, O as OwnershipOverlayEntry, P as PresentationNavItem, S as SchemaFieldType, r as TraitOverlayEntry, s as TraitOverlayListener } from '../types-DzmFPbo4.js';
-import { g as EntityPersistence, f as EntityField, j as TraitReference } from '../trait-CKueAwP9.js';
+import { g as FactoryParamValue, c as FactoryConfigTier, b as FactoryConfigParam, F as FactoryCallSite, h as FactorySignature, R as RuleOverlay, p as RuleOverlayEntry, o as PresentationOverlay, q as TraitOverlay } from '../types-COc0mLs1.js';
+export { a as FactoryCallSiteParams, d as FactoryEntitySignature, e as FactoryEventSignature, f as FactoryPageSignature, i as FactorySignatureCatalog, j as FactorySignatureEntityField, k as FactoryTraitSignature, m as JsonSchema, n as JsonSchemaType, J as JsonValue, O as OwnershipOverlayEntry, P as PresentationNavItem, S as SchemaFieldType, r as TraitOverlayEntry, s as TraitOverlayListener } from '../types-COc0mLs1.js';
+import { g as EntityPersistence, f as EntityField, j as TraitReference } from '../trait-BB1dc5A_.js';
 import 'zod';
 import '../expression-BUIi9ezJ.js';
 import '@almadar/patterns';
@@ -27,14 +27,32 @@ import '@almadar/patterns';
  * + input widget keyed off `inputType` + `suggestedAnswers` (and, for
  * structured types, `itemSchema` / `objectSchema`); the answer fills
  * the matching `mutationTemplate`.
+ *
+ * ### Surfacing flag
+ * `advanced` is `true` for questions whose tier is NOT `domain` or
+ * `policy` (i.e. `infra`, `presentation`, untagged, or any non-canonical
+ * value). The UI collapses advanced questions under a disclosure panel;
+ * questions with `advanced` absent or `false` render inline.
+ *
+ * ### Entity-field multiselect
+ * When `inputType` is `'multiselect'` and `mutationTemplate.kind` is
+ * `'set-orbital-entity-fields'`, the answer is the subset of
+ * `suggestedAnswers` the user checked. The UI maps selected names back
+ * to `EntityField[]` via `fieldCandidates` (keyed by field name) before
+ * submitting to `answersToMutations`. `fieldDescriptions` carries each
+ * field's semantic description for the checkbox label.
  */
 interface DomainQuestion {
     /** Unique within a session. Keys the answer record. */
     id: string;
     /** Natural-language prompt shown to the user. */
     question: string;
-    /** One short sentence — why this question matters. */
-    reason: string;
+    /**
+     * One short sentence explaining WHY this question is being asked —
+     * distinct from `helpText`. Never set to the same string as `helpText`.
+     * Undefined when no distinct rationale exists.
+     */
+    reason?: string;
     /** Orbital this question scopes to (matches
      *  `FactoryCallSite.orbital`). */
     orbitalName: string;
@@ -54,9 +72,14 @@ interface DomainQuestion {
      *  pre-fills the input, the user can confirm or override. */
     defaultValue?: DomainQuestionAnswer;
     /** Closed-enum or curated suggestions. Empty when the input is
-     *  free-form. */
+     *  free-form. For entity-field multiselect this is the candidate
+     *  field name list (see `fieldCandidates`). */
     suggestedAnswers?: ReadonlyArray<string>;
-    /** Free-text help shown under the input. */
+    /**
+     * How-to-answer caption shown under the input widget. Set from
+     * `FactoryConfigParam.description` (the knob's own authored caption).
+     * Never set to the same text as `reason`.
+     */
     helpText?: string;
     /** Per-element schema for array-of-objects (`listOfObjects`) and
      *  free-form chip lists (`tagList`). Propagated from
@@ -70,6 +93,14 @@ interface DomainQuestion {
      *  `@tier` annotation — the studio treats undefined as
      *  `'presentation'`. */
     tier?: FactoryConfigTier;
+    /**
+     * `true` when this question is NOT a primary domain/policy decision —
+     * i.e. `tier` is absent, `'infra'`, `'presentation'`, or any
+     * non-canonical value. The UI collapses advanced questions under a
+     * disclosure panel. Domain and policy questions always have
+     * `advanced` absent (falsy).
+     */
+    advanced?: boolean;
     /** Impact weight derived from `tier` (policy/domain high, infra medium,
      *  presentation low). Drives the studio's Confidence score — answering a
      *  high-weight question moves the needle more. */
@@ -78,6 +109,20 @@ interface DomainQuestion {
      *  (deterministic); the studio server may boost it by prompt relevance.
      *  Higher = surfaced earlier. */
     priority?: number;
+    /**
+     * Full `EntityField` candidates keyed by field name. Present only on
+     * entity-field multiselect questions (`inputType: 'multiselect'`,
+     * `mutationTemplate.kind: 'set-orbital-entity-fields'`). The UI maps
+     * the user's selected field names back to `EntityField[]` via this
+     * record before calling `answersToMutations`.
+     */
+    fieldCandidates?: Readonly<Record<string, EntityField>>;
+    /**
+     * Human-readable description for each candidate field name. Keyed by
+     * field name (same keys as `fieldCandidates`). The UI shows this as
+     * the checkbox sublabel.
+     */
+    fieldDescriptions?: Readonly<Record<string, string>>;
 }
 /**
  * Narrow set of widget kinds the studio renders.
@@ -175,7 +220,14 @@ type DomainQuestionAnswers = Readonly<Record<string, DomainQuestionAnswer>>;
  * @packageDocumentation
  */
 
-declare function generateQuestions(plan: ReadonlyArray<FactoryCallSite>, catalog: ReadonlyArray<FactorySignature>, ruleOverlay?: RuleOverlay): DomainQuestion[];
+declare function generateQuestions(plan: ReadonlyArray<FactoryCallSite>, catalog: ReadonlyArray<FactorySignature>, ruleOverlay?: RuleOverlay, 
+/**
+ * Optional user-authored prompt from the current session. Carried
+ * through so downstream consumers (route handlers, ranking passes)
+ * can re-order questions by relevance without re-generating. Does
+ * not affect the emitted set — only threading and ordering.
+ */
+_userPrompt?: string): DomainQuestion[];
 /**
  * Pick a widget for a config-key question from the param's typed
  * declaration + its structural carriers. The type tag is lifted

package/dist/factory/index.js

@@ -1,5 +1,5 @@
 // src/factory/questions/generate.ts
-function generateQuestions(plan, catalog, ruleOverlay) {
+function generateQuestions(plan, catalog, ruleOverlay, _userPrompt) {
   const out = [];
   const ruleCapabilities = collectRuleCapabilities(ruleOverlay);
   for (const call of plan) {
@@ -38,12 +38,14 @@ function buildConfigKeyQuestion(call, trait, param) {
   const question = `${label}?`;
   const callSiteOverride = callSiteOverrideValue(call, trait.name, param.key);
   const effectiveDefault = callSiteOverride !== void 0 ? callSiteOverride : param.default;
-  const reason = param.description ?? `Customizes "${param.key}" on the ${trait.name} trait. ` + (effectiveDefault !== void 0 ? `Default: ${stringifyDefault(effectiveDefault)}.` : `No default \u2014 leave blank to inherit the factory's behavior.`);
+  const helpText = param.description;
+  const syntheticReason = `Customizes "${param.key}" on the ${trait.name} trait. ` + (effectiveDefault !== void 0 ? `Default: ${stringifyDefault(effectiveDefault)}.` : `No default \u2014 leave blank to inherit the factory's behavior.`);
+  const reason = helpText !== void 0 ? void 0 : syntheticReason;
+  const isAdvanced = !isPrimaryTier(param.tier);
   const out = {
     id: `${call.orbital}.${trait.name}.${param.key}`,
     orbitalName: call.orbital,
     question,
-    reason,
     inputType: deriveInputType(param),
     mutationTemplate: {
       kind: "set-trait-override-config",
@@ -52,6 +54,12 @@ function buildConfigKeyQuestion(call, trait, param) {
       configKey: param.key
     }
   };
+  if (reason !== void 0) {
+    out.reason = reason;
+  }
+  if (helpText !== void 0) {
+    out.helpText = helpText;
+  }
   if (effectiveDefault !== void 0) {
     out.defaultValue = effectiveDefault;
   }
@@ -67,8 +75,8 @@ function buildConfigKeyQuestion(call, trait, param) {
   if (param.tier) {
     out.tier = param.tier;
   }
-  if (param.description) {
-    out.helpText = param.description;
+  if (isAdvanced) {
+    out.advanced = true;
   }
   const weight = tierWeight(param.tier);
   out.weight = weight;
@@ -89,6 +97,9 @@ function tierWeight(tier) {
       return 1;
   }
 }
+function isPrimaryTier(tier) {
+  return tier === "domain" || tier === "policy";
+}
 function callSiteOverrideValue(call, traitName, configKey) {
   const override = call.params.traitOverrides?.[traitName];
   if (!override?.config) return void 0;
@@ -144,27 +155,42 @@ function entityFieldQuestions(call, signature) {
   if (signature.entities.length === 0) return [];
   const entity = signature.entities[0];
   const entityName = call.params.entityName ?? entity.name;
-  const defaultFields = entity.fields.map(
-    signatureFieldToEntityField
-  );
-  const weight = tierWeight("domain");
-  return [
-    {
-      id: `${call.orbital}.__entityFields`,
-      orbitalName: call.orbital,
-      question: `What fields should a ${entityName} have?`,
-      reason: `Defines the data model for ${entityName}. Add domain-specific fields or confirm the canonical defaults.`,
-      inputType: "fieldList",
-      mutationTemplate: {
-        kind: "set-orbital-entity-fields",
-        orbitalName: call.orbital
-      },
-      defaultValue: defaultFields,
-      tier: "domain",
-      weight,
-      priority: weight
+  const candidateFields = entity.fields.map(signatureFieldToEntityField);
+  const fieldCandidates = {};
+  const fieldDescriptions = {};
+  const candidateNames = [];
+  for (let i = 0; i < entity.fields.length; i++) {
+    const sig = entity.fields[i];
+    const ef = candidateFields[i];
+    const name = sig.name;
+    candidateNames.push(name);
+    fieldCandidates[name] = ef;
+    if (sig.description) {
+      fieldDescriptions[name] = sig.description;
     }
-  ];
+  }
+  const weight = tierWeight("domain");
+  const q = {
+    id: `${call.orbital}.__entityFields`,
+    orbitalName: call.orbital,
+    question: `Which fields should a ${entityName} have?`,
+    reason: `Defines the data model for ${entityName}. Pick the fields that matter for your use case.`,
+    inputType: "multiselect",
+    mutationTemplate: {
+      kind: "set-orbital-entity-fields",
+      orbitalName: call.orbital
+    },
+    suggestedAnswers: candidateNames,
+    defaultValue: candidateNames,
+    fieldCandidates,
+    tier: "domain",
+    weight,
+    priority: weight
+  };
+  if (Object.keys(fieldDescriptions).length > 0) {
+    q.fieldDescriptions = fieldDescriptions;
+  }
+  return [q];
 }
 function signatureFieldToEntityField(f) {
   const base = {
@@ -207,23 +233,26 @@ function capabilityQuestions(call, signature, ruleCapabilities) {
   const seen = /* @__PURE__ */ new Set();
   const out = [];
   for (const trait of signature.traits) {
+    const policyKnobKeys = new Set(
+      trait.overridableConfigKeys.filter((p) => p.tier === "policy").map((p) => p.key)
+    );
     for (const cap of trait.capabilities) {
       if (seen.has(cap)) continue;
       seen.add(cap);
       if (ruleCapabilities.has(cap)) continue;
+      if (policyKnobKeys.has(cap)) continue;
       out.push({
         id: `${call.orbital}.capability.${cap}`,
         orbitalName: call.orbital,
         question: capabilityPrompt(cap, entityName),
-        reason: capabilityReason(cap, trait),
+        helpText: capabilityHelp(cap, trait),
         capability: cap,
-        inputType: "capability",
+        inputType: "boolean",
         mutationTemplate: {
           kind: "set-rule",
           capability: cap,
           appliesTo: [entityName]
         },
-        suggestedAnswers: ["yes", "skip"],
         // Capabilities encode governance/policy decisions — high impact.
         weight: 3,
         priority: 3
@@ -233,10 +262,11 @@ function capabilityQuestions(call, signature, ruleCapabilities) {
   return out;
 }
 function capabilityPrompt(capability, entity) {
-  return `Should "${capability}" apply to ${entity}?`;
+  const label = humanizeKey(capability);
+  return `Enable ${label} for ${entity}?`;
 }
-function capabilityReason(capability, trait) {
-  return `The "${trait.name}" trait advertises capability "${capability}". Answer "yes" to wire a matching rule into the schema.`;
+function capabilityHelp(capability, trait) {
+  return `Turns on the "${capability}" behavior from the ${trait.name} trait. Say yes to wire a governance rule into the schema.`;
 }
 function findSignature(catalog, organism, orbital) {
   return catalog.find((s) => s.organism === organism && s.orbital === orbital);