@wildo-ai/platform-core-shared 1.1.0 → 1.1.2

package/dist/esm/workbench/workbench-resources.custom.shared.schemas.js

@@ -2,110 +2,498 @@ import { z } from 'zod';
 import { initZodDecorators } from '@wildo-ai/zod-decorators';
 initZodDecorators(z);
 /**
- * An application's shared MODULE and the resources it owns — derived, never stored.
+ * One relationship, as it rides on BOTH resources it joins.
  *
- * The first resource backed by `PersistenceAdapter.INTROSPECTION`. Rows come from the companion's
- * `resource-specifications` behavior, whose `moduleOwnership` is exactly this shape
- * (`{ moduleId, resourceTypes }`), so nothing is reshaped on the way through: the binding names the
- * behavior and the path, and the schema describes what that behavior already answers.
+ * ## Why an edge appears on two rows rather than on one
  *
- * ## Why `moduleId` is the primary key
+ * A relationship genuinely IS a property of both resources — "what is `deals` related to?" is a
+ * question about `deals` and about everything `deals` touches — so carrying it on both is a
+ * statement of what it means, not an encoding chosen to fit a row shape. Hanging every edge off one
+ * arbitrarily-chosen endpoint would be the encoding, and the choice would have to be re-derived by
+ * every reader.
  *
- * There is no store to mint a surrogate in. A derived row must be identified by something the SOURCE
- * already guarantees unique, and a module id is that by construction — two modules with one id would
- * be a defect in the application, not in this projection.
+ * The consumer draws each edge once, keyed by {@link relationshipId}. The duplication costs one extra
+ * copy of a small object per edge and buys a row that is complete on its own.
+ *
+ * ## Why the vocabularies are plain strings
+ *
+ * These values cross a subprocess boundary from the OBSERVED application's registry, which may be
+ * built against a different engine revision than the workbench. Binding `nature` or the cardinalities to the engine enums would make a
+ * row the observed application can legitimately produce unparseable here — the workbench refusing to
+ * show exactly the drift it exists to reveal.
+ */
+export const Workbench_DomainResourceRelationship_Schema = z.object({
+    /**
+     * Stable identity for ONE edge within this projection, composed from every field carried about it.
+     *
+     * NOT the `resourceType1__resourceType2__foreignKeyField` triple the retired
+     * `workbenchResourceRelationships` resource addressed a row by: that triple is not total here,
+     * because a MANY-to-MANY edge carries
+     * `jointResourceType` and no `foreignKeyField`. Two edges agreeing on every field below are
+     * indistinguishable to a graph, so merging them loses nothing a reader could have seen.
+     */
+    relationshipId: z.string().min(1),
+    resourceType1: z.string().min(1),
+    resourceType2: z.string().min(1),
+    cardinality1: z.string().min(1),
+    cardinality2: z.string().min(1),
+    /**
+     * `composition`, `reference` or `association` — every member `RelationshipNature` declares — kept as
+     * a plain string for the drift-tolerance reason above, not because a fourth one exists today.
+     */
+    nature: z.string().min(1),
+    /** The field carrying the join. Absent on a junction-backed MANY-to-MANY, which has no FK column. */
+    foreignKeyField: z.string().min(1).nullable(),
+    /**
+     * Which side's rows CARRY the foreign key — the direction an arrow must point.
+     *
+     * Resolved by the framework's own `resolveForeignKeyHolderResourceType`, from CARDINALITY, never
+     * from declaration order: `(TODOS, USERS, MANY, ONE, { foreignKeyField })` is a valid child-first
+     * declaration that puts the referenced resource in `resourceType2`, so a consumer reading position
+     * draws half its arrows backwards.
+     */
+    foreignKeyHolderResourceType: z.string().min(1),
+    /** The junction resource of a MANY-to-MANY, which the framework requires such an edge to name. */
+    jointResourceType: z.string().min(1).nullable(),
+    /** Whether this edge is the structural ownership anchor giving `resourceType2` its scope. */
+    isPrimaryScope: z.boolean(),
+    /**
+     * Whether the edge is DECLARED BUT INACTIVE.
+     *
+     * The one field here whose absence made the graph WRONG rather than thinner: a disabled edge
+     * constrains nothing at runtime, so drawing it like a live one tells a reader the application has
+     * a relationship it does not have. Carried even though the dogfood application disables none
+     * (measured 2026-08-31: 0 of 16) — a field that is uniformly `false` today is exactly the one that
+     * silently misleads the first time it is not.
+     */
+    isDisabled: z.boolean(),
+    /**
+     * How a caller reaches rows on the far side — `requires_context`, `standalone`, and whatever else
+     * the observed application's engine revision declares.
+     *
+     * A plain string for the same drift-tolerance reason `nature` is one.
+     */
+    accessScopeStrategy: z.string().min(1).nullable(),
+    /** Whether the parent endpoint is `mandatory` or `optional` for the child's addressing. */
+    parentResourceRequirement: z.string().min(1).nullable(),
+    /**
+     * WHICH resource this edge anchors scope to, when it anchors one.
+     *
+     * Not derivable from {@link isPrimaryScope}, which says only THAT it anchors. On an edge whose
+     * endpoints are both scoped, the two answer different questions.
+     */
+    primaryScope: z.string().min(1).nullable(),
+    /** Whether a cycle through this edge is permitted — a graph-shape fact a graph should be able to show. */
+    allowCycle: z.boolean(),
+});
+/**
+ * ONE resource of the observed application's domain model — node, module membership, specification
+ * and edges in a single row.
+ *
+ * ## Why every field is a summary field
+ *
+ * A LIST renders the SUMMARY projection, and this resource's list IS its whole purpose: the graph
+ * consumes the collection. A field left out of the summary is a field the graph cannot draw, and the
+ * omission is silent — the row arrives, the field is simply absent. So the summary here is the full
+ * row by design rather than by neglect.
+ *
+ * ## Why this is one row per RESOURCE rather than one row per module or one row for the graph
+ *
+ * Edges are resource-to-resource. A module-per-node projection would have to AGGREGATE them, which
+ * destroys precisely the meanings the framework refuses to merge — nature, cardinality, foreign-key
+ * direction — and a graph that draws every edge as one grey line has lost information the flat table
+ * at least preserved.
  */
-export const Workbench_ApplicationModule_Schema = z.object({
-    moduleId: z.string().min(1).isPrimaryKey().isSummaryField(),
+export const Workbench_DomainResource_Schema = z.object({
+    /**
+     * Composed by the introspection source from the binding's `identityFields` (`['resourceType']`).
+     *
+     * `.isSummaryField()` on the IDENTITY field is load-bearing rather than cosmetic: the projection a
+     * list renders is the summary, and a row with no id is a row nothing can address — the failure that
+     * made every relationship row unclickable before its id was marked.
+     */
+    workbenchDomainResourceId: z.string().min(1).isPrimaryKey().isSummaryField(),
+    resourceType: z.string().min(1).isSummaryField(),
+    /**
+     * The module that registers this resource, or `null`.
+     *
+     * `null` is a FACT, not a gap: no module of the observed application owns this resource, which is
+     * true of every ENGINE resource — and an application merges all of them, since `initializeResources`
+     * applies the engine's core factory map unconditionally and both registries merge it. They are
+     * carried rather than dropped because they are part of the running application, and because an edge
+     * to the resource that gives a row its tenant scope is the most load-bearing edge in the graph.
+     *
+     * No `origin` field restates this. The absence of a module IS the distinction, and a second field
+     * saying the same thing is a second thing that can disagree with the first.
+     */
+    moduleId: z.string().min(1).isSummaryField().nullable(),
+    /** `domain` or `engine` — the kind the owning module declares, when there is one. */
+    moduleKind: z.string().min(1).isSummaryField().nullable(),
+    /**
+     * Which part of its owner this resource belongs to — a SECOND grouping axis, under the module.
+     *
+     * Sourced from `ResourceSpecificationConfig.subDomain`. For engine resources that is the closed
+     * `EngineResourceSubDomain` vocabulary (`auth`, `billing`, `users`, …), which exists because the
+     * engine's 85 resources otherwise arrive as one flat set and every surface that has to present them
+     * invents a grouping of its own.
+     *
+     * A plain `string` here rather than that enum, and deliberately: this schema is shared by a
+     * workbench that observes an application whose own sub-domains it cannot enumerate. Pinning the
+     * engine's vocabulary here would make an application's value invalid at the wire.
+     *
+     * `null` means the resource specification declares none — an application resource today, or an engine
+     * resource with no spec at all. A consumer grouping by this must carry an "unclassified" bucket and
+     * say so, rather than folding those rows into a real group.
+     */
+    subDomain: z.string().min(1).isSummaryField().nullable(),
     /**
-     * The resource types this module registers.
+     * Every field of the materialized `mainSchema`, with everything the framework knows about it.
      *
-     * A plain string array rather than foreign keys: these name resources in the OBSERVED
-     * application's registry, not rows in any store this workbench can reach. Modelling them as
-     * relationships would promise a join that cannot exist.
+     * This replaced a bare `fieldNames: string[]`, whose JSDoc argued that "a domain-model panel
+     * answers what a resource HOLDS" and that per-field extraction "belongs to `resource-specifications`".
+     * The premise was right and the conclusion aged badly: a NAME answers "does this field exist",
+     * which the node already implies by counting them, and a reader who opens a resource wants what
+     * the field IS. The cost was then MEASURED rather than assumed — 715 fields across the 82 engine
+     * resources extract to 264 KB, a fraction of what the relationship edges already cost — so the
+     * reason to withhold it was gone.
+     *
+     * `params`, `derived` and `origin` are OPAQUE records on purpose. They are the extractor's own
+     * output — authored spec prose, framework-derived structure, base-vs-variant provenance — and each
+     * is an open shape that grows with the decorators. Restating them field by field here would make
+     * this schema a second, always-lagging copy of a contract `@wildo-ai/saas-specifications` owns;
+     * a consumer that needs one reads it through that package's type.
      */
-    resourceTypes: z.array(z.string()).isSummaryField(),
+    fields: z.array(z.object({
+        fieldName: z.string().min(1),
+        /** Which `{primitive}Spec()` decorator carried the authored prose, when one did. */
+        specDecorator: z.string().min(1).nullable(),
+        params: z.record(z.string(), z.unknown()).nullable(),
+        derived: z.record(z.string(), z.unknown()).nullable(),
+        origin: z.record(z.string(), z.unknown()).nullable(),
+        /**
+         * The field's DECORATOR record, as the schema declares it — beside `derived`, which is the
+         * extractor's interpretation of it.
+         *
+         * It carries what the interpretation drops: `isSummaryField`, `isHidden`, `excludeFromCreate` /
+         * `excludeFromUpdate`, `dataCategories`, and the index / unique / primary-key trio.
+         *
+         * It does NOT carry `*.ui-behavior.tsx` configuration, and that is a reachability limit rather
+         * than an omission: those decorators are applied by a FRONTEND module the companion never loads,
+         * because the subprocess resolves `library`, `specifications` and `service` targets and there is
+         * no frontend one. Measured on the engine's resources — zero UI keys present.
+         */
+        metadata: z.record(z.string(), z.unknown()).nullable(),
+    })).isSummaryField(),
     /**
-     * `domain` or `engine` — or absent, which an application is free to leave unset.
+     * Every operation the resource declares, projected to what a READER needs.
      *
-     * Carried because it is the ONE field that distinguishes a business-domain module from an engine
-     * contribution, and the projection used to discard it. Without it a module carrying roles,
-     * features, milestones and a product catalog is indistinguishable from a broken empty one.
+     * Never the DTOs. A materialized operation carries six Zod schemas — request, response, summary,
+     * context, internal, repository — each serializing to tens of kilobytes, so carrying the operation
+     * objects would put megabytes on the wire to say which verbs exist. What is here is the identity,
+     * the variant, the authorization and the flags that change what the operation DOES.
      *
-     * A plain nullable string rather than the `ApplicationModuleKind` union: this is a projection of
-     * the OBSERVED application's declaration, which may be built against a different engine revision
-     * than the workbench. Binding the union here would make the workbench refuse to display a kind the
-     * observed app can legitimately declare — refusing to show exactly the drift it exists to reveal.
+     * An EMPTY `roles` array is a real answer — no role gate on that variant — and not a gap.
      */
-    kind: z.string().min(1).nullable(),
+    operations: z.array(z.object({
+        operationIdentifier: z.string().min(1),
+        /** The TRANSPORT kind: `api_call`, `internal_call`, `repository_only`, … */
+        variantType: z.string().min(1).nullable(),
+        /**
+         * WHICH variant of that transport — `admin`, `summary`, `context` — or `null` for the default.
+         *
+         * The missing half of an operation's IDENTITY, and its absence was a defect rather than missing
+         * detail: `organizations` declares four operations that are all `read` × `api_call`, separated
+         * only by this key, and across the engine's core map 133 of 794 operations collided on the pair
+         * without it.
+         */
+        variantKey: z.string().min(1).nullable(),
+        /** For a CUSTOM operation, the core verb it behaves like. `null` for a core operation. */
+        resourceOperationLike: z.string().min(1).nullable(),
+        isDefault: z.boolean(),
+        roles: z.array(z.string()),
+        riskLevel: z.string().min(1).nullable(),
+        isUnimplemented: z.boolean(),
+        isDisabled: z.boolean(),
+        requiresStepUpAuthentication: z.boolean(),
+        admitsCrossTenantPlatformAdministration: z.boolean(),
+        auditableEventType: z.string().min(1).nullable(),
+        isMcpExposed: z.boolean(),
+        requiredFeatures: z.array(z.string()),
+        /**
+         * Everything else the operation declares — HTTP verb, runtime mode, bulk and API-key posture,
+         * notification fan-out, custom-implementation modes, authoritative fields.
+         *
+         * A DENY LIST over the operation's own keys on the producing side, for the same reason `advanced`
+         * is, and this is the one that proved the argument: a hand-picked set of twelve fields shipped
+         * without `variantKey`, `httpVerb`, `isBulkOperation` or `serviceRuntimeMode`. The six DTO
+         * schemas are excluded by name — each serializes to tens of kilobytes.
+         */
+        attributes: z.record(z.string(), z.unknown()),
+        /**
+         * The authored specification for this operation, keyed by `operationIdentifier` — so every
+         * VARIANT of one verb carries the same entry, which is what the specification describes.
+         *
+         * `null` means the specification does not mention the operation: a gap a reader can act on.
+         */
+        specification: z.record(z.string(), z.unknown()).nullable(),
+        /** The authored `frontend.views` overlay for this operation, when there is one. */
+        view: z.record(z.string(), z.unknown()).nullable(),
+    })).isSummaryField(),
     /**
-     * What the module contributes, and how much of each.
+     * The operations for which the resource specification declares a FRONTEND view overlay (`frontend.views`).
      *
-     * DERIVED from the module's own declared keys rather than from a fixed list, so a contribution
-     * kind added to `SharedSaaSModule` appears here without a schema or projection change. Counts
-     * rather than content: an inventory answers whether and how much, and the content belongs to
-     * whichever behavior projects that contribution specifically.
+     * Refs only. The entries are authoring prose about how an operation surfaces, which belongs to a
+     * specification reader; what a domain-model panel can act on is which operations have an authored
+     * view and — by difference with `operations` — which do not.
      */
-    contributions: z.array(z.object({
-        contribution: z.string().min(1),
-        count: z.number().int().nonnegative(),
-    })),
+    viewRefs: z.array(z.string()).isSummaryField(),
+    /**
+     * The configuration facts that are neither prose nor structure — persistence, policy, bindings.
+     *
+     * Everything on the resource's `ResourceConfiguration` that decides how it BEHAVES rather than what
+     * it holds: which database it lives in, whether it is a system resource, its retention,
+     * transposition, portability and data-subject policies, its HTTP and introspection bindings.
+     *
+     * An OPAQUE record, and deliberately so. The producer builds it by DENY list over the
+     * configuration's own keys rather than by enumerating the ones that exist today, because
+     * `ResourceConfiguration` has grown several of these fields in as many months and an enumeration
+     * reports the subset its author knew about. Typing it here would put that enumeration back.
+     */
+    advanced: z.record(z.string(), z.unknown()).isSummaryField(),
+    /**
+     * The authored specification's PROSE, or `null` when this resource has none.
+     *
+     * It rides in the row rather than being fetched on selection because a per-selection fetch is not
+     * cheaper: `deriveRows` has no per-row path, so an addressed READ derives the WHOLE set and filters
+     * it afterwards. "Fetch the specification when a node is clicked" would therefore be a second full
+     * derivation of the entire application.
+     */
+    specification: z.object({
+        /** Why this resource exists in the domain. */
+        purpose: z.string(),
+        /** The functional role it plays inside the business architecture. */
+        businessRole: z.string(),
+        /** How it evolves over time. Optional in the specification contract, so nullable here. */
+        lifecycleRole: z.string().nullable(),
+        /** Domain caveats not encoded structurally elsewhere. */
+        businessConstraints: z.array(z.string()),
+    }).isSummaryField().nullable(),
+    /** Every relationship this resource participates in, on either side. */
+    relationships: z.array(Workbench_DomainResourceRelationship_Schema).isSummaryField(),
 });
 /**
- * One relationship edge between two of the observed application's resources.
+ * The QUESTION a specification family answers — the axis the workbench groups them by.
  *
- * ## Where the shape comes from
+ * ## Why the families are grouped at all
  *
- * MEASURED against a live `resources-registry` derivation rather than transcribed from the engine's
- * `ResourceRelationship` type: 16 edges, 12 keys present on all of them and `primaryScope` on 8. The
- * engine type carries more than the behavior emits, and a schema written from the type would refuse
- * every row for fields the projection never sends.
+ * Fifteen rows in one undifferentiated list is a directory, not a review surface. A creator opening
+ * the workbench is not looking for "the `document-release-policy` family"; they are looking for what
+ * was decided about who this product is for, or about what it must promise. Grouping by the question
+ * answered is what makes the list navigable without inventing twelve destinations.
  *
- * ## Why the vocabularies are plain strings here
+ * ## Why this is a display vocabulary and not a property of the family
  *
- * `nature`, `cardinality*` and `accessScopeStrategy` ARE closed engine enums, and this is one of the
- * documented exceptions rather than an oversight: these rows cross a subprocess boundary as JSON
- * from the OBSERVED application's registry, which may be built against a different engine revision
- * than the workbench. Binding to the enum would make a row the observed app can legitimately produce
- * unparseable here — the workbench would refuse to show exactly the drift it exists to reveal. This
- * is a projection of someone else's runtime, not an authored value the framework controls.
+ * `ApplicationSpecificationFamilySemanticSchemaRef` names what a family MEANS and what validates it.
+ * Nothing in the runtime branches on the concern below — it exists so a reader can find a row. Adding
+ * it to the semantic authority would put a workbench presentation choice inside the contract the
+ * journey lands artifacts against.
  *
- * `resolvedSemantics` is deliberately ABSENT. It is a deep nested object (handling modes, foreign-key
- * persistence) that no current view reads, and copying it into the schema would freeze a shape whose
- * consumer does not exist yet.
+ * The family → concern mapping deliberately lives with the projection that derives it (the
+ * companion's `specification-artifacts` behavior), beside the semantic authority it must stay
+ * exhaustive over, rather than here where the authority is not reachable.
  */
-export const Workbench_ResourceRelationship_Schema = z.object({
+export var WorkbenchSpecificationArtifactConcern;
+(function (WorkbenchSpecificationArtifactConcern) {
+    /** Why the product exists and who it is for — `vision-brief`, `market-snapshot`. */
+    WorkbenchSpecificationArtifactConcern["INTENT"] = "intent";
+    /** What it must do and what it costs — `requirements`, `feature-drafts`, `business-model`. */
+    WorkbenchSpecificationArtifactConcern["SCOPE"] = "scope";
+    /** How and when it gets built — `domain-plan`, `build-plan`, `roadmap`, `placement-plan`. */
+    WorkbenchSpecificationArtifactConcern["DELIVERY"] = "delivery";
+    /** How it presents itself — `brand-brief`. */
+    WorkbenchSpecificationArtifactConcern["IDENTITY"] = "identity";
+    /** What it must promise and publish — the assurance and governed-document families. */
+    WorkbenchSpecificationArtifactConcern["OBLIGATIONS"] = "obligations";
     /**
-     * Composed by the introspection source from the binding's `identityFields`, because a relationship
-     * row carries no identifier of its own — see `IntrospectionResourceBinding.identityFields`.
+     * A family the workbench has not been taught to group.
      *
-     * ## Why this is named for the resource rather than `relationshipId`
+     * A named member rather than a throw, and rather than silence. The population is derived from the
+     * semantic authority, so a family added there arrives here with no classification — and the two
+     * alternatives are both worse than a visible bucket: refusing the derivation would blank the whole
+     * page over one unmapped row, and defaulting into a real concern would file the new family
+     * somewhere plausible and wrong, which nobody would notice.
      *
-     * A COMPOSED identity is written to the resource's own `resourceFieldIdentifier`. That is the one
-     * name the source can resolve from the registry without introspecting decorators — the schema's
-     * `.isPrimaryKey()` marker is not readable as a field NAME from the built configuration, and
-     * duplicating the name onto the binding would create a second declaration that can disagree.
+     * A companion test asserts this member is currently UNUSED, so it stays a signal rather than
+     * becoming a habit.
+     */
+    WorkbenchSpecificationArtifactConcern["UNCLASSIFIED"] = "unclassified";
+})(WorkbenchSpecificationArtifactConcern || (WorkbenchSpecificationArtifactConcern = {}));
+/**
+ * Whether a family has landed, and whether what landed still validates.
+ *
+ * THREE states, not two, because "not landed" and "landed but invalid" are the opposite instructions
+ * to a reviewer: the first is work the journey has not done, the second is work it did that no longer
+ * holds. A boolean `isValid` would report both as `false`.
+ */
+export var WorkbenchSpecificationArtifactState;
+(function (WorkbenchSpecificationArtifactState) {
+    /** The family is exported by the application and its `_core` validator reports no error. */
+    WorkbenchSpecificationArtifactState["LANDED_VALID"] = "landed_valid";
+    /** The family is exported and its `_core` validator reports at least one ERROR-severity issue. */
+    WorkbenchSpecificationArtifactState["LANDED_INVALID"] = "landed_invalid";
+    /**
+     * The application exports nothing for this family.
      *
-     * Its sibling `workbenchApplicationModules` names its key `moduleId` instead, and the difference
-     * is real rather than inconsistent: that behavior's rows arrive carrying `moduleId`, so nothing is
-     * composed and the schema is free to keep the source's own name.
+     * Reported as a ROW rather than omitted — the same call `definition-specifications.behavior.ts`
+     * makes for the same reason: *"an omitted row and a family that does not exist would look the same
+     * to the reader."* On a fresh application an empty list would say nothing; fifteen NOT_LANDED rows
+     * say what the journey has left to produce.
      */
-    workbenchResourceRelationshipId: z.string().min(1).isPrimaryKey(),
-    resourceType1: z.string().min(1).isSummaryField(),
-    resourceType2: z.string().min(1).isSummaryField(),
-    /** `one` / `many`, as the observed application's registry reports them. */
-    cardinality1: z.string().min(1),
-    cardinality2: z.string().min(1),
-    /** `composition`, `aggregation`, `reference`, … — the observed app's vocabulary, not ours. */
-    nature: z.string().min(1).isSummaryField(),
-    /** The field carrying the join. Present on every measured edge. */
-    foreignKeyField: z.string().min(1),
-    accessScopeStrategy: z.string().min(1),
-    parentResourceRequirement: z.string().min(1),
-    isPrimaryScope: z.boolean(),
-    allowCycle: z.boolean(),
-    isDisabled: z.boolean(),
-    /** Present on 8 of 16 measured edges — optional because the projection genuinely omits it. */
-    primaryScope: z.string().min(1).optional(),
+    WorkbenchSpecificationArtifactState["NOT_LANDED"] = "not_landed";
+})(WorkbenchSpecificationArtifactState || (WorkbenchSpecificationArtifactState = {}));
+/**
+ * ONE application-specification family, projected for a human reviewer.
+ *
+ * ## Why the prose fields are markdown strings
+ *
+ * `StringDisplayMode.MARKDOWN` renders GFM through the framework's own display chrome, which is what
+ * lets headings, lists and paragraphs survive into the page. The alternative — modelling each
+ * family's shape as nested schema fields — would have to be done fifteen times, would freeze twelve
+ * `_core` contracts into this projection, and would still render as a form rather than as a document.
+ *
+ * The rendering is an OUTLINE, never a table. That is the acceptance criterion this resource exists
+ * to satisfy: these artifacts are prose-heavy and their value is in the rationale, so a projection
+ * that put them in columns would destroy exactly what makes them worth reviewing.
+ *
+ * ## Why the heavy fields are NOT summary fields
+ *
+ * `document`, `issues`, `decisionRecord` and `diagram` are excluded from the summary by omission, so
+ * a list carries the INDEX while a detail page carries the documents. One derivation still computes
+ * all of them either way — this bounds the RESPONSE, not the work.
+ *
+ * Which variant a caller gets matters, and is easy to state wrongly: the LIST operation's DEFAULT
+ * variant answers the full row, and it is the operation's `summary` variant that applies this
+ * projection. Measured against the live wonder-crm companion, 2026-08-31:
+ * `GET /api/v1/workbench-specification-artifacts` → **149,089 B**, and
+ * `…/workbench-specification-artifacts/summary` → **3,654 B** carrying the eight fields marked
+ * below. A list layout renders the summary variant — which is also why the addressing field must be
+ * marked, or every row in that list is unclickable.
+ */
+export const Workbench_SpecificationArtifact_Schema = z.object({
+    /**
+     * The family id — `vision-brief`, `market-snapshot`, `compliance-program`.
+     *
+     * The source's own key, marked `.isSummaryField()` because a list row with no id is a row nothing
+     * can address: the summary projection is what a click reads the target from.
+     */
+    family: z.string().min(1).isPrimaryKey().isSummaryField(),
+    /** The family's name in a creator's words — `Vision`, `Market`, `Assurance programme`. */
+    title: z.string().min(1).isSummaryField(),
+    /**
+     * What this family IS, in one sentence a creator recognizes — static per family, present whether
+     * or not anything landed. This is the summary card's subtitle: a card reading only
+     * "Governed-document drafts · Not landed" tells a reader nothing they can act on; "The drafts of
+     * the public documents this product must publish" does.
+     */
+    description: z.string().min(1).isSummaryField(),
+    /**
+     * A one-line PULSE of the landed content — `"3 ICPs · 5 personas · 2 positionings"`, the vision's
+     * own one-liner — or `null` when the family has not landed.
+     *
+     * Derived server-side from the RAW value so the list answers "how much is in there" without any
+     * client downloading fifteen full documents. It is a COUNT-and-headline summary, never a
+     * truncation of prose: a clipped sentence reads as an accident, a count reads as an answer.
+     */
+    contentSummary: z.string().nullable().isSummaryField(),
+    /** The question this family answers, which is the axis the list groups by. */
+    concern: z.enum(WorkbenchSpecificationArtifactConcern).isSummaryField(),
+    /** Landed and valid, landed and invalid, or not landed at all. */
+    state: z.enum(WorkbenchSpecificationArtifactState).isSummaryField(),
+    /** The `_core` contract the family's content must satisfy, verbatim from the semantic authority. */
+    schemaRef: z.string().min(1),
+    /**
+     * Where the family's file lives, relative to the application root — the file a reader opens when
+     * the rendering is not enough.
+     *
+     * `null` when this runtime places no file for the family. A placement and a RENDER PROFILE are
+     * different things (`playbook-output-landing-target`), and only the placement is asked for here.
+     */
+    sourcePath: z.string().min(1).nullable().isSummaryField(),
+    /** ERROR-severity issues the family's own validator reports on the landed content, right now. */
+    errorCount: z.number().int().nonnegative().isSummaryField(),
+    /** WARN-severity issues — authoring drift that does not invalidate the artifact. */
+    warnCount: z.number().int().nonnegative().isSummaryField(),
+    /**
+     * Every playbook whose declared `outputs[].family` is this family.
+     *
+     * This is the durable half of "what produced it": a fact about the compiled catalog, in git, true
+     * whether or not any run's state survives. A link to the RUN that produced this particular value
+     * was deliberately rejected — runs, traces and the write register are a per-run cache under
+     * `one-source-of-truth.md` Rule 5, so a durable artifact pointing into deletable state is dangling
+     * by design. The link runs the other way: a run may name what it wrote.
+     *
+     * Empty for a family no playbook produces — which is a finding, not a gap.
+     */
+    producedByPlaybookRefs: z.array(z.string()).isSummaryField(),
+    /**
+     * The landed family value, RAW — exactly the object the specifications package exports.
+     *
+     * ## Why the raw value rides beside its rendering
+     *
+     * The per-family display templates (workbench `artifact-templates/`) render EDITORIALLY — an ICP
+     * card, a requirement with its acceptance criteria, a placement decision with its rationale — and
+     * an editorial template needs the VALUE, not a markdown projection of it. The markdown `document`
+     * below stays: it is the structural fallback every family keeps behind the template error
+     * boundary, and the whole rendering for a family no template covers yet.
+     *
+     * ## Untyped HERE, typed at the EDGE — a measured decision, not an omission
+     *
+     * The typed `_core` snapshot schemas live in `@wildo-ai/saas-specifications`, which depends on
+     * `saas-frontend-lib` AND `saas-backend-lib` (its package.json) — while this package is the
+     * platform's light contracts-only spine (`platform/CLAUDE.md`). Typing this field would drag the
+     * whole engine into every consumer of this package for a shape only two consumers read. The two
+     * readers type it themselves: the companion behavior validates through the semantic authority
+     * before emitting, and the workbench templates narrow via TYPE-ONLY imports (erased at compile,
+     * zero runtime dependency). Recorded with alternatives in
+     * `.claude/plans/workbench-product-artifacts-ux-analysis.md` (D1).
+     *
+     * Deliberately NOT a summary field: the LIST carries the index, and this is the heaviest thing a
+     * row owns. Emitted from the RAW landed value — never from a validator's parsed output, whose
+     * schema `.default()`s would inject content the author never wrote.
+     */
+    content: z.record(z.string(), z.unknown()).nullable(),
+    /**
+     * The artifact rendered as a document, or `null` when the family has not landed.
+     *
+     * Produced by `renderSpecificationFamilyReviewDocument` — an outline over the landed value, not a
+     * prompt block. The prompt renderers (`market-render-prompt`, `brand-render-prompt`) read the same
+     * content for a language model and must never be reused here.
+     */
+    document: z.string().nullable(),
+    /**
+     * The validator's own findings, rendered for a reader, or `null` when there are none.
+     *
+     * Carried as content rather than as counts alone because a reviewer deciding whether to accept an
+     * artifact needs to see WHICH rule failed and where, and the counts beside them in the list are
+     * only the signal to come and look.
+     */
+    issues: z.string().nullable(),
+    /**
+     * `DECISIONS.md` committed beside the family, verbatim, or `null` when there is none.
+     *
+     * The strongest provenance this surface has: it names the playbook that produced the artifact and,
+     * more importantly, records every question the creator was asked — including the ones they did NOT
+     * answer, where "the derivation chose for itself". A run that asked nothing writes no such file, so
+     * `null` here means "no clarification was recorded", never "no clarification happened".
+     */
+    decisionRecord: z.string().nullable(),
+    /**
+     * `DIAGRAM.md` committed beside the family, verbatim, or `null`.
+     *
+     * Three families have one today (`domain-plan`, `build-plan`, `roadmap`). It is surfaced rather
+     * than re-derived: the diagram is already a committed output of the family, regenerated on every
+     * landing, and rendering a second picture here would be a second thing that can disagree with it.
+     */
+    diagram: z.string().nullable(),
 });
 //# sourceMappingURL=workbench-resources.custom.shared.schemas.js.map