@synap-core/workspace-templates 0.9.3 → 0.10.0

package/dist/index.d.ts

@@ -5,13 +5,13 @@
  * YAML source files validate against these types.
  * Every consumer (browser, backend, CLI, marketplace) imports from here.
  */
-type TemplateAppKind = 'native' | 'stored' | 'url';
+type TemplateAppKind = "native" | "stored" | "url";
 interface TemplateAppRef {
     kind: TemplateAppKind;
     /** For kind='native': the appId registered in the browser manifest */
     appId?: string;
     /** For kind='native': how the platform renders the app */
-    rendererType?: 'native' | 'external' | 'iframe-srcdoc';
+    rendererType?: "native" | "external" | "iframe-srcdoc";
     /** For kind='stored': the cell key registered in the cell registry */
     cellKey?: string;
     /** For kind='stored': default props passed to the cell */
@@ -25,25 +25,34 @@ type WorkspaceJsonValue = string | number | boolean | null | WorkspaceJsonValue[
     [key: string]: WorkspaceJsonValue;
 };
 type WorkspacePrimarySurface = {
-    kind: 'app';
+    kind: "app";
     appId: string;
-    rendererType: 'native';
+    rendererType: "native";
     title?: string;
     props?: Record<string, WorkspaceJsonValue>;
 } | {
-    kind: 'app';
+    kind: "app";
     appId: string;
-    rendererType: 'external';
+    rendererType: "external";
     url: string;
     title?: string;
     props?: Record<string, WorkspaceJsonValue>;
 } | {
-    kind: 'cell';
+    kind: "cell";
     cellKey: string;
     title?: string;
     props?: Record<string, WorkspaceJsonValue>;
 } | {
-    kind: 'view';
+    /**
+     * Ordinary website. Unlike an external `app`, this has no trusted app
+     * identity and is always opened through the Browser's unprivileged URL
+     * surface.
+     */
+    kind: "url";
+    url: string;
+    title?: string;
+} | {
+    kind: "view";
     viewId: string;
     title?: string;
 };
@@ -53,12 +62,12 @@ type WorkspacePrimarySurface = {
  * slug. The pod resolves this to `WorkspacePrimarySurface` before persistence.
  */
 type WorkspacePrimarySurfaceViewReference = {
-    kind: 'view';
+    kind: "view";
     viewName: string;
     viewSlug?: string;
     title?: string;
 } | {
-    kind: 'view';
+    kind: "view";
     viewName?: string;
     viewSlug: string;
     title?: string;
@@ -102,11 +111,11 @@ interface TemplateProfile {
      * `entity_scope` of an existing profile (a divergence is reported as an
      * advisory `scopeConflict` and the live row is left alone).
      */
-    entityScope?: 'pod' | 'workspace';
+    entityScope?: "pod" | "workspace";
     /** Semantic slug for system profiles. */
     semanticSlug?: string;
     /** Kind vs role profile. Omit for default ('kind'). */
-    profileKind?: 'kind' | 'role';
+    profileKind?: "kind" | "role";
     /** For profileKind='role': which base-kind profile slugs this role can attach to. */
     applicableKinds?: string[];
     properties: TemplateProperty[];
@@ -129,6 +138,28 @@ interface TemplateEntityLink {
     type: string;
     label?: string;
 }
+/**
+ * A domain-level relation TYPE definition — a `relation_defs` row, the workspace's
+ * relation vocabulary. Distinct from {@link TemplateEntityLink}, which is a
+ * profile→profile EDGE (and only carries `type` + `label`). A relation def stands
+ * alone: it has no source/target profile pairing and it carries the rich metadata
+ * (`description`, `isDirectional`, `uiHints`) that the entity-link path drops.
+ *
+ * Mirrors `DefaultRelationDef` in synap-backend
+ * `packages/database/src/utils/default-relation-defs.ts` VERBATIM — the door
+ * find-or-creates a `relation_defs` row from each entry (idempotent by
+ * `slug` within the workspace), which is `ensureDefaultRelationDefs`'s body.
+ */
+interface TemplateRelationDef {
+    slug: string;
+    displayName: string;
+    description?: string;
+    isDirectional?: boolean;
+    uiHints?: {
+        category?: "workflow" | "social" | "reference" | "hierarchy";
+        inverseLabel?: string;
+    };
+}
 interface TemplateSeedEntity {
     profileSlug: string;
     title: string;
@@ -159,21 +190,21 @@ interface TemplateDisplayTemplate {
     config: Record<string, unknown>;
 }
 interface TemplateSidebarSurface {
-    kind: 'cell' | 'view' | 'entity' | 'document' | 'channel' | 'app' | 'url';
+    kind: "cell" | "view" | "entity" | "document" | "channel" | "app" | "url";
     cellKey?: string;
     viewId?: string;
     viewName?: string;
     appId?: string;
     url?: string;
-    rendererType?: 'native' | 'external' | 'iframe-srcdoc';
-    placement?: 'main' | 'side' | 'floating' | 'modal' | 'popover' | 'embed';
-    displayMode?: 'compact' | 'medium' | 'full';
+    rendererType?: "native" | "external" | "iframe-srcdoc";
+    placement?: "main" | "side" | "floating" | "modal" | "popover" | "embed";
+    displayMode?: "compact" | "medium" | "full";
     props?: Record<string, unknown>;
     title?: string;
     meta?: Record<string, unknown>;
 }
 interface TemplateSidebarItem {
-    kind: 'app' | 'view' | 'profile' | 'external' | 'cell';
+    kind: "app" | "view" | "profile" | "external" | "cell";
     appId?: string;
     viewName?: string;
     viewId?: string;
@@ -204,7 +235,7 @@ interface TemplateLayoutConfig {
     sidebarItems?: TemplateSidebarItem[];
 }
 interface TemplateBentoBlock {
-    kind: 'view' | 'widget';
+    kind: "view" | "widget";
     viewName?: string;
     widgetType?: string;
     pos: {
@@ -222,7 +253,7 @@ interface TemplateProfileEntityBentoTemplates {
     };
 }
 /** Mirrors `WorkspaceSourceRole` in synap-backend `schema/workspaces.ts`. */
-type TemplateSourceRole = 'provider' | 'consumer' | 'provider-consumer';
+type TemplateSourceRole = "provider" | "consumer" | "provider-consumer";
 /** Mirrors `WorkspaceDefaultSource` in synap-backend `schema/workspaces.ts`. */
 interface TemplateDefaultSource {
     /** The workspace id that supplies this capability domain. */
@@ -240,7 +271,7 @@ interface TemplateOnboardingCollectTarget {
     /** Human description of what to capture for this target. */
     what: string;
     /** Roughly how many to expect — guides interview depth. */
-    cardinality?: 'one' | 'few' | 'several';
+    cardinality?: "one" | "few" | "several";
     /** Key fields the agent should make sure to fill. */
     keyFields?: string[];
 }
@@ -280,7 +311,7 @@ interface TemplateOnboarding {
 }
 interface TemplatePlaybookParam {
     name: string;
-    type: 'text' | 'number' | 'entity' | 'choice' | 'boolean';
+    type: "text" | "number" | "entity" | "choice" | "boolean";
     label?: string;
     required?: boolean;
     defaultValue?: unknown;
@@ -290,12 +321,12 @@ interface TemplatePlaybook {
     description?: string;
     goalTemplate: string;
     params?: TemplatePlaybookParam[];
-    executor?: 'is-agent' | 'external-agent' | 'hybrid';
-    inputStrategy?: 'none' | 'static' | 'rotating' | 'query';
+    executor?: "is-agent" | "external-agent" | "hybrid";
+    inputStrategy?: "none" | "static" | "rotating" | "query";
     channelSpec?: {
-        type: 'GROUP' | 'AGENT_COLLAB' | 'THREAD';
+        type: "GROUP" | "AGENT_COLLAB" | "THREAD";
         members?: string[];
-        aiReactionMode?: 'on_mention' | 'always' | 'never';
+        aiReactionMode?: "on_mention" | "always" | "never";
     };
     /**
      * A cron schedule that maintains ONE backing cron automation (a single
@@ -327,29 +358,45 @@ interface TemplatePlaybook {
         profileSlug: string;
         filter?: Record<string, unknown>;
     };
-    status?: 'draft' | 'active' | 'paused';
+    status?: "draft" | "active" | "paused";
 }
 interface TemplateAutomation {
     /** Stable local key (unused on the wire today — reserved for dedup/refs). */
     key?: string;
     name: string;
     description?: string;
-    triggerType: 'event' | 'cron' | 'webhook' | 'manual';
+    triggerType: "event" | "cron" | "webhook" | "manual";
     triggerConfig?: Record<string, unknown>;
     flow: {
         nodes: unknown[];
         edges: unknown[];
         precondition?: string;
     };
-    status?: 'draft' | 'active' | 'paused';
+    status?: "draft" | "active" | "paused";
+}
+interface TemplateCommandDerivedInput {
+    name: string;
+    label?: string;
+    /** Mirrors `DerivedInput.type` (text | number | entity | view | choice). */
+    type?: string;
+}
+interface TemplateCommand {
+    title: string;
+    promptTemplate: string;
+    derivedInputs?: TemplateCommandDerivedInput[];
+    /** text | proposal | view */
+    outputMode?: string;
+    canCreateViews?: boolean;
+    /** read_only | propose_writes */
+    permissionsProfile?: string;
 }
 interface TemplateActionPlacement {
     /** Entity kind whose detail surface this action appears on. */
     profileSlug: string;
     /** Where the action renders. Only "entity-detail" is consumed today. */
-    surface: 'entity-detail' | string;
+    surface: "entity-detail" | string;
     /** What the action does when clicked. */
-    kind: 'capability' | 'playbook' | 'automation';
+    kind: "capability" | "playbook" | "automation";
     /**
      * Reference to the thing to run: a capability verb key, or a playbook /
      * automation NAME (resolved to a row id at apply time).
@@ -381,7 +428,7 @@ interface TemplateIntegration {
     /** Override default params with {{var}} interpolation. */
     params?: Record<string, string>;
     /** "apply" (create+update) or "install" (create only). */
-    mode?: 'apply' | 'install';
+    mode?: "apply" | "install";
 }
 interface TemplateExtendsRef {
     source: string;
@@ -465,7 +512,7 @@ interface TemplateDependency {
      * - `'require'` (default): the dependency must be present on the pod as its
      *   own artifact, but this template does not merge into it.
      */
-    relation?: 'compose' | 'require';
+    relation?: "compose" | "require";
     /**
      * Short human reason shown in the install-time "this also installs…" prompt.
      */
@@ -502,7 +549,7 @@ interface WorkspaceYaml {
          * Workspace classifier — consumed by createFromDefinition (settings.workspaceType,
          * creator-role + agent-workspace behavior). Mirrors the backend union.
          */
-        workspaceType?: 'personal' | 'agent' | 'project' | 'operational';
+        workspaceType?: "personal" | "agent" | "project" | "operational";
         visibility?: string;
         /** Capabilities this workspace provides (e.g. "brand.library", "content.pipeline") */
         capabilities?: string[];
@@ -528,6 +575,19 @@ interface WorkspaceYaml {
     views?: TemplateView[];
     /** Schema-level links between entity types */
     entityLinks?: TemplateEntityLink[];
+    /**
+     * Domain-level relation TYPE vocabulary seeded into the workspace's
+     * `relation_defs`. Distinct from `entityLinks` (profile→profile edges): a
+     * relation def stands alone and carries `description`/`isDirectional`/`uiHints`.
+     * The `base` template carries the universal defaults. See {@link TemplateRelationDef}.
+     */
+    relationDefs?: TemplateRelationDef[];
+    /**
+     * Workspace-scoped intelligence commands (prompt-template "Default Command
+     * Pack") seeded with the workspace. The `base` template carries the universal
+     * pack. See {@link TemplateCommand}.
+     */
+    commands?: TemplateCommand[];
     /** Initial data to seed on workspace creation */
     seedEntities?: TemplateSeedEntity[];
     /** Relations between seed entities, created on provisioning */
@@ -968,9 +1028,11 @@ declare function layerTemplateGraph(input: LayerTemplateGraphInput): Composition
  * Cross-template CONCEPT guard — catches vocabulary forks between templates.
  *
  * WHY THIS EXISTS (read before weakening or deleting it):
- * `business-developer.yaml` introduced workspace-scoped `crm-lead`/`crm-client`
- * for the same real-world concept that `foundation.yaml`/`crm.yaml` declare as
- * pod-wide shared `lead`/`client`. Nothing failed. Three reasons:
+ * `business-developer.yaml` once introduced workspace-scoped
+ * `crm-lead`/`crm-client` for the same real-world concept that
+ * `foundation.yaml`/`crm.yaml` declare as pod-wide shared `lead`/`client` (that
+ * fork has since been collapsed back onto the shared slugs). Nothing failed at
+ * the time. Three reasons:
  *
  *   1. `build.mjs`'s `validate()` runs PER FILE, inside the read loop, so it
  *      structurally cannot see that another template already owns `lead`.
@@ -1008,6 +1070,13 @@ interface ConceptViolation {
  * list cannot rot into a graveyard.
  *
  * Key = the two colliding profile slugs, sorted, joined by "|".
+ *
+ * Currently EMPTY, and that is the healthy state. The two entries this list was
+ * born for — `crm-lead|lead` and `client|crm-client` — were RESOLVED rather
+ * than kept: business-developer.yaml now re-declares the shared `lead`/`client`
+ * roles and carries its business-development fields as workspace-overlay
+ * PROPERTIES. One concept, one slug, workspace-specific fields. Rule 3 below
+ * would have failed CI had the entries been left behind.
  */
 declare const DECLARED_DIVERGENCES: Record<string, string>;
 /**
@@ -1020,7 +1089,14 @@ declare const DECLARED_DIVERGENCES: Record<string, string>;
  * is honest: no guard can know they mean the same thing.
  */
 declare function conceptTerm(semanticSlug: string): string;
-declare function findConceptViolations(templates?: Record<string, WorkspaceYaml>): ConceptViolation[];
+declare function findConceptViolations(templates?: Record<string, WorkspaceYaml>, 
+/**
+ * The declared-divergence allowlist to enforce against. Defaults to the real
+ * one; injectable so the escape-hatch semantics (rule 1 suppression, rule 3
+ * staleness) stay testable now that the shipped list is empty — previously
+ * those tests could only be written because a live entry happened to exist.
+ */
+declaredDivergences?: Record<string, string>): ConceptViolation[];
 declare function formatConceptViolations(violations: ConceptViolation[]): string;
 
 /**
@@ -1253,18 +1329,18 @@ declare function validateTemplate(tpl: WorkspaceYaml, opts?: ValidateOptions): V
  * Until then: keep the constant arrays below identical to `@synap/database`
  * `schema/automations.ts`.
  */
-/** The 21 node types — `AutomationNodeBase.type` union (schema/automations.ts). */
-declare const FLOW_NODE_TYPES: readonly ["trigger", "command", "condition", "delay", "output", "loop", "transform", "fetch", "query", "entity_read", "related_entities", "guard", "compute", "select", "claim", "messages_query", "switch", "skill", "capability", "sub_automation", "playbook_run"];
+/** The 23 node types — `AutomationNodeBase.type` union (schema/automations.ts). */
+declare const FLOW_NODE_TYPES: readonly ["trigger", "command", "condition", "delay", "output", "loop", "transform", "fetch", "query", "entity_read", "related_entities", "guard", "compute", "select", "claim", "messages_query", "runs_query", "proposals_query", "switch", "skill", "capability", "sub_automation", "playbook_run"];
 /** The 11 output types — `OutputNodeDef.data.outputType` (schema/automations.ts). */
 declare const FLOW_OUTPUT_TYPES: readonly ["notification", "entity_create", "entity_update", "facet_attach", "facet_update", "facet_detach", "relation_create", "webhook", "channel_message", "session_update", "set_state"];
 /**
  * The known `config.channelType` values for a `channel_message` output. Mirrors
  * the executor's channel_message resolution (automation-executor.ts). The output
- * channel is CONTEXT-DERIVED — a channel_message is valid with `channelId`, OR
- * `channelEntityRef` (an entity-id expression → that entity's internal channel),
- * OR a `channelType` from this set, OR NOTHING (the executor defaults a targetless
- * channel_message to the automation's own run channel). A `channelType` that is
- * PRESENT but not one of these is still a typo → still an error.
+ * channel is now CONTEXT-DERIVED — a channel_message is valid with `channelId`,
+ * OR `channelEntityRef` (an entity-id expression → that entity's internal
+ * channel), OR a `channelType` from this set, OR NOTHING (the executor defaults a
+ * targetless channel_message to the automation's own run channel). A `channelType`
+ * that is PRESENT but not one of these is still a typo → still an error.
  */
 declare const CHANNEL_MESSAGE_CHANNEL_TYPES: readonly ["personal_thread", "proactive", "subjectEntity"];
 interface FlowValidationError {
@@ -1381,6 +1457,19 @@ interface WorkspaceDefinitionInput {
     seedEntities: NonNullable<WorkspaceYaml['seedEntities']>;
     suggestedRelations?: WorkspaceYaml['suggestedRelations'];
     displayTemplates?: WorkspaceYaml['displayTemplates'];
+    /**
+     * Domain-level relation TYPE vocabulary — the door find-or-creates a
+     * `relation_defs` row per entry (idempotent by slug within the workspace). NOT
+     * `entityLinks` (those are profile→profile edges and drop the rich metadata).
+     * Carried verbatim; the authored form IS the wire form.
+     */
+    relationDefs?: WorkspaceYaml['relationDefs'];
+    /**
+     * Workspace intelligence commands — the door find-or-creates an
+     * `intelligence_commands` row per entry (idempotent by title). Carried
+     * verbatim; the authored form IS the wire form.
+     */
+    commands?: WorkspaceYaml['commands'];
     layoutConfig: WorkspaceYaml['layout'] | undefined;
     bentoViewName?: string;
     /**
@@ -1485,6 +1574,10 @@ interface PackageDefinitionOutput {
     suggestedRelations?: WorkspaceYaml['suggestedRelations'];
     displayTemplates?: WorkspaceYaml['displayTemplates'];
     entityLinks?: WorkspaceYaml['entityLinks'];
+    /** Relation-type vocabulary — carried verbatim (authored form IS the wire form). */
+    relationDefs?: WorkspaceYaml['relationDefs'];
+    /** Intelligence commands — carried verbatim (authored form IS the wire form). */
+    commands?: WorkspaceYaml['commands'];
     /** WIDGET half of the authored bento union — mapped by the pod via `widgetType`. */
     bentoLayout?: BentoWidgetBlockWire[];
     /**