@formicoidea/labre-core 0.31.0 → 0.33.0

package/dist/extensions/store.js

@@ -30,43 +30,46 @@ import { LatexStoreExtension as InlineLatexStoreExtension } from '../_pkgs/affin
 import { LinkStoreExtension } from '../_pkgs/affine-inline-link/store.js';
 import { InlinePresetStoreExtension } from '../_pkgs/affine-inline-preset/store.js';
 import { ReferenceStoreExtension } from '../_pkgs/affine-inline-reference/store.js';
-import { isBlockEnabled, } from '../flags.js';
 /**
- * Store extensions, honoring block flags.
- * Omitted flags default to enabled. See {@link BlockFlags}.
+ * Store extensions.
+ *
+ * Registered UNCONDITIONALLY: the store side (models, adapters, transformers)
+ * is what makes a document readable and round-trippable, and a flag must never
+ * gate that (see {@link LabreFlags} and `docs/adr/0009`). The `flags` parameter
+ * is kept for source compatibility with callers written against the previous
+ * contract, and is deliberately ignored.
  */
-export function getInternalStoreExtensions(flags) {
-    const on = (block) => isBlockEnabled(flags, block);
+export function getInternalStoreExtensions(_flags) {
     return [
         FoundationStoreExtension,
-        ...(on('attachment') ? [AttachmentStoreExtension] : []),
-        ...(on('bookmark') ? [BookmarkStoreExtension] : []),
-        ...(on('callout') ? [CalloutStoreExtension] : []),
-        ...(on('code') ? [CodeStoreExtension] : []),
-        ...(on('data-view') ? [DataViewStoreExtension] : []),
-        ...(on('database') ? [DatabaseStoreExtension] : []),
-        ...(on('divider') ? [DividerStoreExtension] : []),
-        ...(on('edgeless-text') ? [EdgelessTextStoreExtension] : []),
-        ...(on('embed') ? [EmbedStoreExtension] : []),
-        ...(on('embed-doc') ? [EmbedDocStoreExtension] : []),
-        ...(on('frame') ? [FrameStoreExtension] : []),
-        ...(on('image') ? [ImageStoreExtension] : []),
-        ...(on('latex') ? [LatexStoreExtension] : []),
-        ...(on('list') ? [ListStoreExtension] : []),
+        AttachmentStoreExtension,
+        BookmarkStoreExtension,
+        CalloutStoreExtension,
+        CodeStoreExtension,
+        DataViewStoreExtension,
+        DatabaseStoreExtension,
+        DividerStoreExtension,
+        EdgelessTextStoreExtension,
+        EmbedStoreExtension,
+        EmbedDocStoreExtension,
+        FrameStoreExtension,
+        ImageStoreExtension,
+        LatexStoreExtension,
+        ListStoreExtension,
         NoteStoreExtension,
         ParagraphStoreExtension,
-        ...(on('surface-ref') ? [SurfaceRefStoreExtension] : []),
-        ...(on('table') ? [TableStoreExtension] : []),
+        SurfaceRefStoreExtension,
+        TableStoreExtension,
         SurfaceStoreExtension,
         RootStoreExtension,
         FootnoteStoreExtension,
         LinkStoreExtension,
         ReferenceStoreExtension,
-        ...(on('latex') ? [InlineLatexStoreExtension] : []),
+        InlineLatexStoreExtension,
         InlinePresetStoreExtension,
-        ...(on('brush') ? [BrushStoreExtension] : []),
+        BrushStoreExtension,
         ShapeStoreExtension,
-        ...(on('mindmap') ? [MindmapStoreExtension] : []),
+        MindmapStoreExtension,
         ConnectorStoreExtension,
         GroupStoreExtension,
         TextStoreExtension,

package/dist/extensions/view.d.ts

@@ -1,7 +1,12 @@
 import { AdapterPanelViewExtension } from '../_pkgs/affine-fragment-adapter-panel/view.js';
-import { type BlockFlags } from '../flags.js';
+import { type LabreFlags } from '../flags.js';
 /**
- * View extensions, honoring block flags.
- * Omitted flags default to enabled. See {@link BlockFlags}.
+ * View extensions.
+ *
+ * Rendering is registered UNCONDITIONALLY; a flag removes only the matching
+ * TOOLING extension (senior button, its submenus and its creation shortcuts),
+ * so a framework switched off disappears from the toolbar without any element
+ * already drawn disappearing from the canvas. Omitted flags default to
+ * enabled. See {@link BlockFlags} and `docs/adr/0009`.
  */
-export declare function getInternalViewExtensions(flags?: BlockFlags): (typeof AdapterPanelViewExtension)[];
+export declare function getInternalViewExtensions(flags?: LabreFlags): (typeof AdapterPanelViewExtension)[];

package/dist/extensions/view.js

@@ -15,7 +15,7 @@ import { ListViewExtension } from '../_pkgs/affine-block-list/view.js';
 import { NoteViewExtension } from '../_pkgs/affine-block-note/view.js';
 import { ParagraphViewExtension } from '../_pkgs/affine-block-paragraph/view.js';
 import { RootViewExtension } from '../_pkgs/affine-block-root/view.js';
-import { SurfaceViewExtension } from '../_pkgs/affine-block-surface/view.js';
+import { AuditViewExtension, SurfaceViewExtension, } from '../_pkgs/affine-block-surface/view.js';
 import { SurfaceRefViewExtension } from '../_pkgs/affine-block-surface-ref/view.js';
 import { TableViewExtension } from '../_pkgs/affine-block-table/view.js';
 import { FoundationViewExtension } from '../_pkgs/affine-foundation/view.js';
@@ -23,7 +23,7 @@ import { AdapterPanelViewExtension } from '../_pkgs/affine-fragment-adapter-pane
 import { DocTitleViewExtension } from '../_pkgs/affine-fragment-doc-title/view.js';
 import { FramePanelViewExtension } from '../_pkgs/affine-fragment-frame-panel/view.js';
 import { OutlineViewExtension } from '../_pkgs/affine-fragment-outline/view.js';
-import { BrushViewExtension } from '../_pkgs/affine-gfx-brush/view.js';
+import { BrushRenderViewExtension, BrushViewExtension, } from '../_pkgs/affine-gfx-brush/view.js';
 import { ConnectorViewExtension } from '../_pkgs/affine-gfx-connector/view.js';
 import { GroupViewExtension } from '../_pkgs/affine-gfx-group/view.js';
 import { LinkViewExtension as GfxLinkViewExtension } from '../_pkgs/affine-gfx-link/view.js';
@@ -56,25 +56,48 @@ import { ScrollAnchoringViewExtension } from '../_pkgs/affine-widget-scroll-anch
 import { SlashMenuViewExtension } from '../_pkgs/affine-widget-slash-menu/view.js';
 import { ToolbarViewExtension } from '../_pkgs/affine-widget-toolbar/view.js';
 import { ViewportOverlayViewExtension } from '../_pkgs/affine-widget-viewport-overlay/view.js';
-import { isBlockEnabled, } from '../flags.js';
+import { isBlockEnabled, isCapabilityEnabled, } from '../flags.js';
+import { CommandTelemetryViewExtension } from './command-telemetry.js';
+import { CommandUsageViewExtension } from './command-usage.js';
 /**
- * View extensions, honoring block flags.
- * Omitted flags default to enabled. See {@link BlockFlags}.
+ * View extensions.
+ *
+ * Rendering is registered UNCONDITIONALLY; a flag removes only the matching
+ * TOOLING extension (senior button, its submenus and its creation shortcuts),
+ * so a framework switched off disappears from the toolbar without any element
+ * already drawn disappearing from the canvas. Omitted flags default to
+ * enabled. See {@link BlockFlags} and `docs/adr/0009`.
  */
 export function getInternalViewExtensions(flags) {
     const on = (block) => isBlockEnabled(flags, block);
     return [
         FoundationViewExtension,
-        // Gfx
+        // The single command-telemetry emitter. Unconditional: a disabled
+        // framework simply never invokes a command (docs/adr/0008).
+        CommandTelemetryViewExtension,
+        // The default (browser-local) recency/frequency measure. Unconditional for
+        // the same reason, and independent of telemetry: it feeds an in-editor
+        // ranking, not a dashboard (docs/adr/0008).
+        CommandUsageViewExtension,
+        // Gfx — each framework contributes an always-on `…Render…` extension
+        // (element view + renderer + interaction + contextual toolbar) and a
+        // flag-gated tooling extension (senior button + creation shortcuts).
+        //
+        // The eight business frameworks are registered as PAIRS, in the order their
+        // senior buttons must read left to right: no framework declares a
+        // `SeniorTool.order`, so they all share the default group and the row is
+        // sorted stably — i.e. left in registration order. The single source of that
+        // order is `FRAMEWORK_DESCRIPTORS`, and `senior-row-order.unit.spec.ts` pins
+        // the two lists together.
         PointerViewExtension,
         GfxNoteViewExtension,
+        BrushRenderViewExtension,
         ...(on('brush') ? [BrushViewExtension] : []),
         // Standalone text / add-file senior buttons, placed right after pen/eraser
         // (registration order = senior-row order for the default order group).
         ...(on('edgeless-text') ? [TextToolViewExtension] : []),
         ...(on('edgeless-media') ? [MediaToolViewExtension] : []),
         ShapeViewExtension,
-        // Mindmap rendering is always on; the flags gate only the senior buttons.
         MindmapRenderViewExtension,
         ...(on('mindmap') ? [MindmapToolViewExtension] : []),
         ConnectorViewExtension,
@@ -82,7 +105,6 @@ export function getInternalViewExtensions(flags) {
         TextViewExtension,
         ...(on('template') ? [TemplateViewExtension] : []),
         ...(on('link') ? [GfxLinkViewExtension] : []),
-        // Core Domain rendering is always on; the flag gates only the senior button.
         // Block
         ...(on('attachment') ? [AttachmentViewExtension] : []),
         ...(on('bookmark') ? [BookmarkViewExtension] : []),
@@ -103,6 +125,11 @@ export function getInternalViewExtensions(flags) {
         ...(on('surface-ref') ? [SurfaceRefViewExtension] : []),
         ...(on('table') ? [TableViewExtension] : []),
         SurfaceViewExtension,
+        // The AI audit seam (PF14.1). A CAPABILITY, not a block: `ai-audit` gates
+        // the `map.audit` command and nothing else, and nothing it touches is
+        // persisted, so switching it off cannot lose anything. See
+        // `OPTIONAL_CAPABILITIES` for why it is not an `OPTIONAL_BLOCKS` entry.
+        ...(isCapabilityEnabled(flags, 'ai-audit') ? [AuditViewExtension] : []),
         RootViewExtension,
         // Inline
         InlineCommentViewExtension,

package/dist/flags.d.ts

@@ -1,30 +1,107 @@
 /**
- * Feature flags for block registration.
+ * Feature flags for editor TOOLING.
  *
- * Each key matches a block (or gfx module) that can be turned off at editor
- * assembly time, through `getAffineSchemas`, `getInternalStoreExtensions` and
- * `getInternalViewExtensions`. Blocks absent from this list form the
- * structural core of the editor (root, surface, note, paragraph, base gfx
- * tools, inline presets, widgets) and are always registered.
+ * ## Contract (reversed in PF4 — see `docs/adr/0009`)
  *
- * Flags default to enabled: `{ database: false }` disables the database
- * block, an empty object (or no flags at all) enables everything. This lets
- * an application ship a block "dark" (registered code, disabled flag), enable
- * it progressively and turn it off again without redeploying.
+ * A flag NEVER decides whether a document can be read. Block schemas
+ * (`getAffineSchemas`) and store extensions (`getInternalStoreExtensions`) are
+ * registered unconditionally, so **every document opens, round-trips and saves
+ * identically whatever the flags say**. Turning a flag off never deletes,
+ * strips or downgrades stored content, and never fails schema validation on
+ * load; turning it back on restores the tooling with the content untouched.
+ *
+ * What a flag gates is the **tooling** that lets a user CREATE and reach that
+ * content:
+ * - the senior toolbar button (edgeless) and its submenus,
+ * - the keyboard shortcuts it owns (see `getShortcutManifest`, which filters on
+ *   {@link ShortcutDescriptor.owner}),
+ * - future side-panel / command-palette entries and validation rules.
+ *
+ * Business framework modules (wardley, edgy, bpmn, cynefin-estuarine, brush,
+ * mindmap, ddd-*) therefore ship their view layer as TWO extensions: an
+ * always-registered `…RenderViewExtension` (element view, renderer,
+ * interaction, contextual toolbar of an already-placed element) and a
+ * flag-gated `…ViewExtension` (senior button + creation shortcuts). Elements
+ * already drawn on a canvas keep painting, stay selectable and stay editable
+ * when their framework is switched off — only the way to add new ones goes
+ * away. The consequence is accepted: the bundle always carries every
+ * framework's renderer, so a framework can no longer ship fully "dark".
+ *
+ * Flags default to enabled: `{ mindmap: false }` hides the Mind Map tooling, an
+ * empty object (or no flags at all) enables everything.
+ *
+ * Note for hosts consuming the PUBLISHED bundles: `scripts/build-bundles.mjs`
+ * strips the four business-framework flags (`wardley`, `edgy`, `bpmn`,
+ * `cynefin-estuarine`) from `@formicoidea/labre-core`'s copy of this file —
+ * they exist only when the matching `@formicoidea/labre-framework-*` bundle is
+ * installed, and the host applies them through that bundle's descriptor. The
+ * examples here therefore use a flag that always ships with core.
  *
  * Caveats:
- * - Disabling a block does not migrate existing documents: a stored document
- *   containing a disabled block will fail schema validation on load. Only
- *   disable blocks that never reached users' documents, or re-enable the flag
- *   to restore access.
- * - The `embed` store extension also registers the linked/synced doc schemas
- *   for backward compatibility; to fully disable doc embeds, disable both
- *   `embed` and `embed-doc`.
- * - `latex` controls both the latex block and inline latex.
- * - `frame` also controls the frame panel fragment.
+ * - The reversal covers **surface elements** (everything living in the surface
+ *   `elements` map: brush, mindmap, wardley, edgy, cynefin, estuarine, bpmn,
+ *   coreDomain). BLOCKS (database, code, image, latex, frame, edgeless-text, …)
+ *   still have their whole view extension gated, because their renderer and
+ *   their tooling live in the same extension. Their data is safe — schema and
+ *   store side are unconditional, so the document loads, round-trips and
+ *   re-renders untouched once the flag is back on — but a disabled block
+ *   currently renders as nothing until its view extension is split the way the
+ *   frameworks' were. See the "Consequences" section of `docs/adr/0009`.
+ * - `latex` covers both the latex block and inline latex.
+ * - `frame` also covers the frame panel fragment.
+ * - `ddd-templates` covers all four DDD Templates-panel categories, so the
+ *   catalogue survives disabling individual DDD senior buttons.
  */
-export declare const OPTIONAL_BLOCKS: readonly ["attachment", "bookmark", "callout", "code", "data-view", "database", "divider", "edgeless-text", "embed", "embed-doc", "frame", "image", "latex", "list", "surface-ref", "table", "brush", "mindmap", "edgeless-text", "edgeless-media", "template", "link"];
+export declare const OPTIONAL_BLOCKS: readonly ["attachment", "bookmark", "callout", "code", "data-view", "database", "divider", "edgeless-text", "embed", "embed-doc", "frame", "image", "latex", "list", "surface-ref", "table", "brush", "mindmap", "edgeless-media", "template", "link"];
 export type OptionalBlock = (typeof OPTIONAL_BLOCKS)[number];
-/** Map of optional block -> enabled. Missing keys default to enabled. */
+/** Map of optional block -> tooling enabled. Missing keys default to enabled. */
 export type BlockFlags = Partial<Record<OptionalBlock, boolean>>;
+/**
+ * Whether the tooling of `block` is enabled. Never consult this to decide
+ * whether content can be read or rendered — see the contract above.
+ */
 export declare function isBlockEnabled(flags: BlockFlags | undefined, block: OptionalBlock): boolean;
+/**
+ * Editor CAPABILITIES — a second switch axis, deliberately not a member of
+ * {@link OPTIONAL_BLOCKS}.
+ *
+ * ## Why a separate list (PF14.1 decision)
+ *
+ * `OPTIONAL_BLOCKS` answers one question: "does this BLOCK or FRAMEWORK exist
+ * for this user". Every entry names a thing a document can contain, which is
+ * what makes the contract above meaningful — "the schema is registered
+ * unconditionally, so the content is safe" is a sentence about content.
+ *
+ * `ai-audit` names no block, no element and no schema. It is a capability of
+ * the editor: whether this build can ask an assistant for an opinion. Filing it
+ * under `OPTIONAL_BLOCKS` would have cost nothing at the keyboard and a lot
+ * afterwards — `FrameworkId` is asserted `satisfies readonly OptionalBlock[]`,
+ * `scripts/build-bundles.mjs` reads the list as the set of things a bundle can
+ * carry, and the flags README would have had to explain why one of its entries
+ * has no schema to protect. A list whose members do not answer the same
+ * question is a list that has to be filtered at every use.
+ *
+ * ## Same contract, in full
+ *
+ * Everything the flag contract promises holds here, and holds trivially:
+ * missing key = enabled; switching it off removes TOOLING only; and there is no
+ * data to lose, because the audit seam persists nothing at all — criteria are
+ * code, findings are session state in `ValidationManager.auditFindings$`, and
+ * neither ever reaches a `Y.Doc`. Off, the command is not registered: it
+ * disappears from the registry, both manifests and the keymap together. Back
+ * on, it is there again, with the document untouched in between.
+ *
+ * Hosts pass ONE object ({@link LabreFlags}): the two key spaces are disjoint,
+ * so nothing about the wiring changes.
+ */
+export declare const OPTIONAL_CAPABILITIES: readonly ["ai-audit"];
+export type OptionalCapability = (typeof OPTIONAL_CAPABILITIES)[number];
+/** Map of capability -> enabled. Missing keys default to enabled. */
+export type CapabilityFlags = Partial<Record<OptionalCapability, boolean>>;
+/**
+ * The one object a host passes. Two disjoint key spaces, one bag — a host that
+ * only ever spoke `BlockFlags` keeps compiling and keeps behaving identically.
+ */
+export type LabreFlags = BlockFlags & CapabilityFlags;
+/** Whether `capability` is enabled. Same defaulting rule as a block flag. */
+export declare function isCapabilityEnabled(flags: CapabilityFlags | undefined, capability: OptionalCapability): boolean;

package/dist/flags.js

@@ -1,27 +1,56 @@
 /**
- * Feature flags for block registration.
+ * Feature flags for editor TOOLING.
  *
- * Each key matches a block (or gfx module) that can be turned off at editor
- * assembly time, through `getAffineSchemas`, `getInternalStoreExtensions` and
- * `getInternalViewExtensions`. Blocks absent from this list form the
- * structural core of the editor (root, surface, note, paragraph, base gfx
- * tools, inline presets, widgets) and are always registered.
+ * ## Contract (reversed in PF4 — see `docs/adr/0009`)
  *
- * Flags default to enabled: `{ database: false }` disables the database
- * block, an empty object (or no flags at all) enables everything. This lets
- * an application ship a block "dark" (registered code, disabled flag), enable
- * it progressively and turn it off again without redeploying.
+ * A flag NEVER decides whether a document can be read. Block schemas
+ * (`getAffineSchemas`) and store extensions (`getInternalStoreExtensions`) are
+ * registered unconditionally, so **every document opens, round-trips and saves
+ * identically whatever the flags say**. Turning a flag off never deletes,
+ * strips or downgrades stored content, and never fails schema validation on
+ * load; turning it back on restores the tooling with the content untouched.
+ *
+ * What a flag gates is the **tooling** that lets a user CREATE and reach that
+ * content:
+ * - the senior toolbar button (edgeless) and its submenus,
+ * - the keyboard shortcuts it owns (see `getShortcutManifest`, which filters on
+ *   {@link ShortcutDescriptor.owner}),
+ * - future side-panel / command-palette entries and validation rules.
+ *
+ * Business framework modules (wardley, edgy, bpmn, cynefin-estuarine, brush,
+ * mindmap, ddd-*) therefore ship their view layer as TWO extensions: an
+ * always-registered `…RenderViewExtension` (element view, renderer,
+ * interaction, contextual toolbar of an already-placed element) and a
+ * flag-gated `…ViewExtension` (senior button + creation shortcuts). Elements
+ * already drawn on a canvas keep painting, stay selectable and stay editable
+ * when their framework is switched off — only the way to add new ones goes
+ * away. The consequence is accepted: the bundle always carries every
+ * framework's renderer, so a framework can no longer ship fully "dark".
+ *
+ * Flags default to enabled: `{ mindmap: false }` hides the Mind Map tooling, an
+ * empty object (or no flags at all) enables everything.
+ *
+ * Note for hosts consuming the PUBLISHED bundles: `scripts/build-bundles.mjs`
+ * strips the four business-framework flags (`wardley`, `edgy`, `bpmn`,
+ * `cynefin-estuarine`) from `@formicoidea/labre-core`'s copy of this file —
+ * they exist only when the matching `@formicoidea/labre-framework-*` bundle is
+ * installed, and the host applies them through that bundle's descriptor. The
+ * examples here therefore use a flag that always ships with core.
  *
  * Caveats:
- * - Disabling a block does not migrate existing documents: a stored document
- *   containing a disabled block will fail schema validation on load. Only
- *   disable blocks that never reached users' documents, or re-enable the flag
- *   to restore access.
- * - The `embed` store extension also registers the linked/synced doc schemas
- *   for backward compatibility; to fully disable doc embeds, disable both
- *   `embed` and `embed-doc`.
- * - `latex` controls both the latex block and inline latex.
- * - `frame` also controls the frame panel fragment.
+ * - The reversal covers **surface elements** (everything living in the surface
+ *   `elements` map: brush, mindmap, wardley, edgy, cynefin, estuarine, bpmn,
+ *   coreDomain). BLOCKS (database, code, image, latex, frame, edgeless-text, …)
+ *   still have their whole view extension gated, because their renderer and
+ *   their tooling live in the same extension. Their data is safe — schema and
+ *   store side are unconditional, so the document loads, round-trips and
+ *   re-renders untouched once the flag is back on — but a disabled block
+ *   currently renders as nothing until its view extension is split the way the
+ *   frameworks' were. See the "Consequences" section of `docs/adr/0009`.
+ * - `latex` covers both the latex block and inline latex.
+ * - `frame` also covers the frame panel fragment.
+ * - `ddd-templates` covers all four DDD Templates-panel categories, so the
+ *   catalogue survives disabling individual DDD senior buttons.
  */
 export const OPTIONAL_BLOCKS = [
     'attachment',
@@ -43,13 +72,65 @@ export const OPTIONAL_BLOCKS = [
     // gfx modules
     'brush',
     'mindmap',
-    // Standalone text / add-file tools, promoted out of the former "Others"
-    // senior submenu (each individually toggleable).
-    'edgeless-text',
+    // Media / template / link tools, promoted out of the former "Others"
+    // senior submenu (each individually toggleable). The edgeless-text tool is
+    // gated by the 'edgeless-text' block flag above.
     'edgeless-media',
     'template',
     'link',
 ];
+/**
+ * Whether the tooling of `block` is enabled. Never consult this to decide
+ * whether content can be read or rendered — see the contract above.
+ */
 export function isBlockEnabled(flags, block) {
     return flags?.[block] !== false;
 }
+/**
+ * Editor CAPABILITIES — a second switch axis, deliberately not a member of
+ * {@link OPTIONAL_BLOCKS}.
+ *
+ * ## Why a separate list (PF14.1 decision)
+ *
+ * `OPTIONAL_BLOCKS` answers one question: "does this BLOCK or FRAMEWORK exist
+ * for this user". Every entry names a thing a document can contain, which is
+ * what makes the contract above meaningful — "the schema is registered
+ * unconditionally, so the content is safe" is a sentence about content.
+ *
+ * `ai-audit` names no block, no element and no schema. It is a capability of
+ * the editor: whether this build can ask an assistant for an opinion. Filing it
+ * under `OPTIONAL_BLOCKS` would have cost nothing at the keyboard and a lot
+ * afterwards — `FrameworkId` is asserted `satisfies readonly OptionalBlock[]`,
+ * `scripts/build-bundles.mjs` reads the list as the set of things a bundle can
+ * carry, and the flags README would have had to explain why one of its entries
+ * has no schema to protect. A list whose members do not answer the same
+ * question is a list that has to be filtered at every use.
+ *
+ * ## Same contract, in full
+ *
+ * Everything the flag contract promises holds here, and holds trivially:
+ * missing key = enabled; switching it off removes TOOLING only; and there is no
+ * data to lose, because the audit seam persists nothing at all — criteria are
+ * code, findings are session state in `ValidationManager.auditFindings$`, and
+ * neither ever reaches a `Y.Doc`. Off, the command is not registered: it
+ * disappears from the registry, both manifests and the keymap together. Back
+ * on, it is there again, with the document untouched in between.
+ *
+ * Hosts pass ONE object ({@link LabreFlags}): the two key spaces are disjoint,
+ * so nothing about the wiring changes.
+ */
+export const OPTIONAL_CAPABILITIES = [
+    /**
+     * The AI audit seam (PF14.1): the `map.audit` command on the `'agent'`
+     * surface. Independent of whether an `AuditProvider` is actually registered —
+     * this says whether the editor OFFERS the capability, the provider says
+     * whether anything can answer. Both are needed for an audit to run, and the
+     * degraded paths differ: switched off, the command does not exist; wired off,
+     * it exists and refuses cleanly.
+     */
+    'ai-audit',
+];
+/** Whether `capability` is enabled. Same defaulting rule as a block flag. */
+export function isCapabilityEnabled(flags, capability) {
+    return flags?.[capability] !== false;
+}

package/dist/frameworks.d.ts

@@ -0,0 +1,45 @@
+import type { FrameworkDescriptor, FrameworkId } from './_pkgs/std/index.js';
+import type { OptionalBlock } from './flags.js';
+/**
+ * THE per-framework identity — the thing that was spelled five times across
+ * the repo (flag key, senior-tool id, `ShortcutDescriptor.owner`, telemetry
+ * union member, `scripts/build-bundles.mjs`) and had already drifted.
+ *
+ * This module is DATA ONLY: plain object literals and type-only imports, no
+ * lit, no runtime dependency. That is what lets `scripts/build-bundles.mjs`
+ * read it (through a type-strip transform) instead of hand-maintaining its own
+ * `FRAMEWORKS` array. Keep it that way. See `docs/adr/0008` § Packaging.
+ *
+ * `telemetryKey` and `telemetrySegment` hold the HISTORICAL PostHog values.
+ * They are the reason the identity unification is code-side only and existing
+ * dashboards keep working untouched — never "tidy" them.
+ */
+/**
+ * Every `FrameworkId` is a real tooling flag key — the ADR's
+ * `satisfies readonly OptionalBlock[]`, expressed at the type level so this
+ * module keeps NO runtime import (`FRAMEWORK_IDS` lives in `@labre/std`, where
+ * `CommandDescriptor.owner` needs it and `OptionalBlock` cannot reach).
+ */
+type AssertFlagKey<_T extends OptionalBlock> = true;
+export type FrameworkIdsAreFlags = AssertFlagKey<FrameworkId>;
+export declare const FRAMEWORK_DESCRIPTORS: FrameworkDescriptor[];
+/**
+ * Bundles that are NOT frameworks: no senior button, no commands, no identity
+ * to unify — just packaging. `ddd-aggregate` ships the four DDD Templates-panel
+ * categories, which is why its flag (`ddd-templates`) is not a `FrameworkId`.
+ * Kept separate on purpose: folding it into {@link FRAMEWORK_DESCRIPTORS} would
+ * mean inventing a framework identity for something that has none.
+ */
+export declare const AUXILIARY_BUNDLES: {
+    bundle: string;
+    label: string;
+    info: string;
+    pkg: string;
+    dir: string;
+    extensions: {
+        flag: string;
+        viewExtension: string;
+    }[];
+}[];
+export declare const frameworkDescriptor: (id: FrameworkId) => FrameworkDescriptor | undefined;
+export {};