@synap-core/workspace-templates 0.9.4 → 0.11.0

package/dist/index.d.ts

@@ -138,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;
@@ -352,6 +374,22 @@ interface TemplateAutomation {
     };
     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;
@@ -417,43 +455,37 @@ interface TemplateExtendsRef {
  * PACKAGE_DEPENDENCY_KINDS — the dependency-kind vocabulary, declared ONCE.
  *
  * This tuple exists so consumers can IMPORT the vocabulary instead of
- * hand-copying it. `TemplateDependency` is currently mirrored by hand in six
- * other places, four of which carry a comment promising they match "VERBATIM so
- * the wire shape never drifts" — a comment doing a type's job. A comment cannot
- * fail a build; an import can. Those mirrors live in repos this package does not
- * own, so this tuple does not fix them by existing — it makes the fix possible:
+ * hand-copying it. `TemplateDependency` is mirrored by hand in several other
+ * places — a comment cannot fail a build, an import can, but these mirrors live
+ * in repos this package does not own, so they must match this list EXACTLY:
  *
- *   - marketplace            `types.ts:102`
- *   - onboarding             `workspace-templates.ts:27`
- *   - synap-backend          `package-definition.ts:204` (exports its own
- *                            `PackageDependencyKind` — the closest peer)
- *   - hub-protocol REST      `rest/packages.ts:140` (zod enum)
- *   - browser                `InstallPackageDialog.tsx:262`
- *   - control-plane-api      `routes/packages.ts:436` (zod enum)
+ *   - marketplace            `features/marketplace/src/types.ts`
+ *   - onboarding             `features/onboarding/src/{templates/workspace-templates,components/WorkspacePreview}.ts(x)`
+ *   - browser                `InstallPackageDialog.tsx`
+ *   - synap-backend          `package-definition.ts` (`PackageDependencyKind`)
+ *   - hub-protocol REST      `rest/packages.ts` (zod enum)
+ *   - control-plane-api      `db/schema/packages.ts` (`TemplateDependency` type)
+ *                            + `routes/packages.ts` (`DEPENDENCY_KINDS` zod enum)
  *
- * ⚠️ `'automation'` IS RETIRED VOCABULARY, deliberately still listed here.
- * CP migration `0049_package_vocabulary` retired the `automation` package
- * category in favour of `workflow` ("workflow — a triggered/sequenced run
- * (absorbs 'automation' + 'playbook')", `PACKAGE_TYPES` in CP
- * `db/schema/packages.ts`). A dependency's `kind` names the TYPE of package it
- * points at, so this vocabulary should track `PACKAGE_TYPES` — meaning the live
- * spelling is `workflow`, not `automation`.
+ * These are the 7 literals the wire accepts, in lockstep with the CP publish
+ * enum (`DEPENDENCY_KINDS = [...PACKAGE_TYPES, "automation"]`, CP
+ * `routes/packages.ts`), the hub install enum (`rest/packages.ts`), and the
+ * backend resolver's `PackageDependencyKind` (`@synap/database`).
  *
- * It is NOT renamed here, on purpose. This is latent, not live: 0/21 templates
- * declare any `kind` other than the default `'workspace'`. And all four wire
- * enums (CP + hub zod, above) still accept `'automation'` and do NOT accept
- * `'workflow'` — so emitting `'workflow'` today would be rejected with a 400 at
- * both doors, and dropping `'automation'` from this tuple would make any
- * consumer that derives a zod enum from it start rejecting a value the wire
- * still legally accepts (a published third-party package may carry it; CP's own
- * schema permits it). Narrowing must therefore follow the wire, not lead it.
+ * Resolver behaviour (backend `package-dependency-resolver.ts`):
+ *   - `workspace`         → resolve+install; the ONLY kind that may `compose`.
+ *   - `capability` / `cell` → resolve+install, always `require`d (presence).
+ *   - `skill` / `workflow` / `view` / `automation` → ACCEPTED and `require`d
+ *     present, surfaced as `required-absent` (non-fatal) — no standalone by-slug
+ *     applier on the pod yet; when one grows, give the kind its own branch.
  *
- * ORDERED FIX (each step deployable alone, no flag day):
- *   1. Widen the CP + hub zod enums to accept BOTH `'automation'` and `'workflow'`.
- *   2. Add `'workflow'` here; mark `'automation'` deprecated; migrate any authored use.
- *   3. Once no payload carries `'automation'`, drop it from the wire enums and this tuple.
+ * `'automation'` is legacy vocabulary: CP migration `0049_package_vocabulary`
+ * renamed the `automation` package category → `workflow` (which absorbs
+ * automation + playbook, `PACKAGE_TYPES` in CP `db/schema/packages.ts`). It
+ * stays accepted on the wire — and therefore in this tuple — for back-compat
+ * with dependencies published before the rename.
  */
-declare const PACKAGE_DEPENDENCY_KINDS: readonly ["workspace", "capability", "automation"];
+declare const PACKAGE_DEPENDENCY_KINDS: readonly ["workspace", "capability", "skill", "workflow", "view", "cell", "automation"];
 /** What a `TemplateDependency` points at. Derived — never re-declare the list. */
 type PackageDependencyKind = (typeof PACKAGE_DEPENDENCY_KINDS)[number];
 interface TemplateDependency {
@@ -461,8 +493,8 @@ interface TemplateDependency {
     slug: string;
     /**
      * What the dependency is. Default `'workspace'`. Only `'workspace'`
-     * dependencies can be `compose`d; `'capability'`/`'automation'` are always
-     * `require`d present without merging.
+     * dependencies can be `compose`d; every other kind is always `require`d
+     * present without merging.
      */
     kind?: PackageDependencyKind;
     /**
@@ -537,6 +569,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 */
@@ -630,6 +675,19 @@ declare function listPublicTemplates(): WorkspaceYaml[];
  *   in the consumers; this door only merges arrays they already fetched.
  */
 
+/**
+ * A lightweight, QUERY-TIME summary of one sub-object a package carries (a cell
+ * today; the shape generalizes to views/automations without change). Rides the
+ * catalog LIST projection so a surface can match/surface a sub-item WITHOUT the
+ * full `definition` — it carries `key + name` only, never the sub-object's code.
+ * `kind` is DERIVED (in the CP SELECT, from which sub-array the row came from),
+ * never a stored taxonomy.
+ */
+interface PackageItemSummary {
+    kind: string;
+    key: string;
+    name: string;
+}
 /**
  * A bundled template — the canonical `WorkspaceYaml` this package ships. Callers
  * pass `listPublicTemplates()` (18) or `listWorkspaceTemplates()` (21); the door
@@ -665,6 +723,13 @@ interface RemoteEntry {
      * never "unknown-so-hide".
      */
     isPrivate?: boolean;
+    /**
+     * Lightweight computed summary of the row's sub-objects (cells), carried on the
+     * LIST projection so a surface can surface a matching sub-item without the full
+     * `definition`. `undefined` on sources that don't compute it (bundled) — treated
+     * as "no known sub-items". See `PackageItemSummary`.
+     */
+    items?: PackageItemSummary[];
     /**
      * The CP `definition` jsonb — opaque install payload. The door reads only
      * `definition.sourcePackage.version` (the winner signal). Absent on browse rows
@@ -724,6 +789,11 @@ interface CpPackageRow {
     icon?: string | null;
     /** Present only on `/mine` rows. `false` ⇒ private. Browse rows omit it. */
     isPublic?: boolean;
+    /**
+     * Computed sub-object summary from `GET /api/packages` / `/mine` (query-time,
+     * not a stored column). Carries `key + name` per cell; never the cell code.
+     */
+    items?: PackageItemSummary[];
 }
 /**
  * Map a CP list row into the merge door's `RemoteEntry`. THE canonical mapping —
@@ -749,6 +819,12 @@ interface CatalogEntryBase {
     icon?: string | null;
     /** `true` ⇒ not publicly listed (internal bundled template, or private CP row). */
     isPrivate: boolean;
+    /**
+     * The entry's sub-object summary (cells). Always present (defaults to `[]`) so a
+     * consumer can match sub-items uniformly. Bundled workspace templates carry no
+     * cells → `[]` (honest); a remote row carries its CP-computed `items`.
+     */
+    items: PackageItemSummary[];
 }
 /** A catalog entry backed by a bundled template. Install via `toWorkspaceDefinition()` / `toPackageDefinition()` on `template`. */
 interface BundledCatalogEntry extends CatalogEntryBase {
@@ -977,9 +1053,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`.
@@ -1017,6 +1095,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>;
 /**
@@ -1029,7 +1114,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;
 
 /**
@@ -1262,18 +1354,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 {
@@ -1390,6 +1482,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;
     /**
@@ -1494,6 +1599,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[];
     /**