@lssm/lib.contracts-spec 17.3.2

package/dist/feature-hubs/social-scheduling.d.ts

@@ -0,0 +1,133 @@
+import { z } from 'zod';
+export declare const SocialScheduleScopeSchema: z.ZodObject<{
+    tenantId: z.ZodString;
+    workspaceId: z.ZodString;
+    brandId: z.ZodString;
+}, z.core.$strict>;
+export declare const SocialScheduleTargetSchema: z.ZodObject<{
+    platform: z.ZodEnum<{
+        linkedin: "linkedin";
+        x: "x";
+    }>;
+    accountId: z.ZodString;
+}, z.core.$strict>;
+export declare const SocialScheduleInputSchema: z.ZodObject<{
+    id: z.ZodString;
+    scope: z.ZodObject<{
+        tenantId: z.ZodString;
+        workspaceId: z.ZodString;
+        brandId: z.ZodString;
+    }, z.core.$strict>;
+    contentRevisionId: z.ZodString;
+    contentDigest: z.ZodString;
+    grantRef: z.ZodString;
+    targets: z.ZodArray<z.ZodObject<{
+        platform: z.ZodEnum<{
+            linkedin: "linkedin";
+            x: "x";
+        }>;
+        accountId: z.ZodString;
+    }, z.core.$strict>>;
+    publishAt: z.ZodISODateTime;
+    expiresAt: z.ZodISODateTime;
+    timeZone: z.ZodString;
+}, z.core.$strict>;
+export declare const SocialScheduledOutcomeSchema: z.ZodObject<{
+    platform: z.ZodEnum<{
+        linkedin: "linkedin";
+        x: "x";
+    }>;
+    accountId: z.ZodString;
+    state: z.ZodEnum<{
+        confirmed: "confirmed";
+        dispatching: "dispatching";
+        failed: "failed";
+        pending: "pending";
+        reconciliation_required: "reconciliation_required";
+    }>;
+    idempotencyKey: z.ZodString;
+    replayRef: z.ZodString;
+    providerRequestId: z.ZodOptional<z.ZodString>;
+    reasonCode: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare const SocialScheduleRecordSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    input: z.ZodObject<{
+        id: z.ZodString;
+        scope: z.ZodObject<{
+            tenantId: z.ZodString;
+            workspaceId: z.ZodString;
+            brandId: z.ZodString;
+        }, z.core.$strict>;
+        contentRevisionId: z.ZodString;
+        contentDigest: z.ZodString;
+        grantRef: z.ZodString;
+        targets: z.ZodArray<z.ZodObject<{
+            platform: z.ZodEnum<{
+                linkedin: "linkedin";
+                x: "x";
+            }>;
+            accountId: z.ZodString;
+        }, z.core.$strict>>;
+        publishAt: z.ZodISODateTime;
+        expiresAt: z.ZodISODateTime;
+        timeZone: z.ZodString;
+    }, z.core.$strict>;
+    version: z.ZodNumber;
+    state: z.ZodEnum<{
+        cancelled: "cancelled";
+        confirmed: "confirmed";
+        dispatching: "dispatching";
+        expired: "expired";
+        failed: "failed";
+        partial: "partial";
+        reconciliation_required: "reconciliation_required";
+        scheduled: "scheduled";
+    }>;
+    outcomes: z.ZodArray<z.ZodObject<{
+        platform: z.ZodEnum<{
+            linkedin: "linkedin";
+            x: "x";
+        }>;
+        accountId: z.ZodString;
+        state: z.ZodEnum<{
+            confirmed: "confirmed";
+            dispatching: "dispatching";
+            failed: "failed";
+            pending: "pending";
+            reconciliation_required: "reconciliation_required";
+        }>;
+        idempotencyKey: z.ZodString;
+        replayRef: z.ZodString;
+        providerRequestId: z.ZodOptional<z.ZodString>;
+        reasonCode: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    createdAt: z.ZodISODateTime;
+    updatedAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export type SocialScheduleInput = z.infer<typeof SocialScheduleInputSchema>;
+export type SocialScheduleRecord = z.infer<typeof SocialScheduleRecordSchema>;
+export type SocialScheduleScope = z.infer<typeof SocialScheduleScopeSchema>;
+export declare const SocialScheduleBatchResultSchema: z.ZodArray<z.ZodObject<{
+    id: z.ZodString;
+    state: z.ZodEnum<{
+        blocked: "blocked";
+        cancelled: "cancelled";
+        confirmed: "confirmed";
+        dispatching: "dispatching";
+        expired: "expired";
+        failed: "failed";
+        partial: "partial";
+        reconciliation_required: "reconciliation_required";
+        scheduled: "scheduled";
+    }>;
+    reasonCode: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>>;
+export type SocialScheduleBatchResult = z.infer<typeof SocialScheduleBatchResultSchema>;
+export interface SocialScheduleStore {
+    recoverable(scope: SocialScheduleScope, before: string, limit: number): Promise<SocialScheduleRecord[]>;
+    create(record: SocialScheduleRecord): Promise<SocialScheduleRecord>;
+    get(scope: SocialScheduleScope, id: string): Promise<SocialScheduleRecord | undefined>;
+    save(record: SocialScheduleRecord, expectedVersion: number): Promise<boolean>;
+    due(scope: SocialScheduleScope, before: string, limit: number): Promise<SocialScheduleRecord[]>;
+}

package/dist/feature-hubs/social-scheduling.js

@@ -0,0 +1 @@
+import{z as t}from"zod";const o=t.string().trim().min(1).max(200);export const SocialScheduleScopeSchema=t.strictObject({tenantId:o,workspaceId:o,brandId:o});export const SocialScheduleTargetSchema=t.strictObject({platform:t.enum(["linkedin","x"]),accountId:o});export const SocialScheduleInputSchema=t.strictObject({id:o,scope:SocialScheduleScopeSchema,contentRevisionId:o.describe("One canonical publication per revision/account; a repost requires a new reviewed revision."),contentDigest:t.string().regex(/^sha256:[a-f0-9]{64}$/),grantRef:o,targets:t.array(SocialScheduleTargetSchema).min(1).max(20),publishAt:t.iso.datetime(),expiresAt:t.iso.datetime(),timeZone:t.string().min(1).refine((e)=>{try{new Intl.DateTimeFormat("en",{timeZone:e});return!0}catch{return!1}})}).superRefine((e,i)=>{if(Date.parse(e.expiresAt)<=Date.parse(e.publishAt))i.addIssue({code:"custom",message:"Publication window is empty."});if(new Set(e.targets.map((a)=>JSON.stringify(a))).size!==e.targets.length)i.addIssue({code:"custom",message:"Publication targets are duplicated."})});export const SocialScheduledOutcomeSchema=SocialScheduleTargetSchema.extend({state:t.enum(["pending","dispatching","confirmed","failed","reconciliation_required"]),idempotencyKey:o,replayRef:o,providerRequestId:o.optional(),reasonCode:o.optional()});export const SocialScheduleRecordSchema=t.strictObject({schemaVersion:t.literal(1),input:SocialScheduleInputSchema,version:t.number().int().positive(),state:t.enum(["scheduled","dispatching","confirmed","failed","partial","reconciliation_required","cancelled","expired"]),outcomes:t.array(SocialScheduledOutcomeSchema).max(20),createdAt:t.iso.datetime(),updatedAt:t.iso.datetime()}).superRefine((e,i)=>{const a=e.outcomes.length===e.input.targets.length,n=e.outcomes.filter((c)=>c.state==="confirmed").length,s=e.outcomes.filter((c)=>c.state==="failed").length;if(["scheduled","cancelled","expired"].includes(e.state)&&e.outcomes.length!==0||e.state==="failed"&&(!a||s!==e.outcomes.length)||e.state==="partial"&&(!a||!n||!s||n+s!==e.outcomes.length))i.addIssue({code:"custom",message:"Schedule state does not match its per-target outcomes."});const l=e.outcomes.map((c)=>`${c.platform}:${c.accountId}`);if(new Set(l).size!==l.length||e.outcomes.some((c)=>!e.input.targets.some((r)=>r.platform===c.platform&&r.accountId===c.accountId)))i.addIssue({code:"custom",message:"Outcome target binding is invalid."});if(e.state==="confirmed"&&(e.outcomes.length!==e.input.targets.length||e.outcomes.some((c)=>c.state!=="confirmed")))i.addIssue({code:"custom",message:"All targets must confirm before a schedule is confirmed."})});export const SocialScheduleBatchResultSchema=t.array(t.strictObject({id:o,state:t.enum([...SocialScheduleRecordSchema.shape.state.options,"blocked"]),reasonCode:o.optional()})).max(100);

package/dist/feature-hubs/types.d.ts

@@ -0,0 +1,89 @@
+export declare const FEATURE_HUB_PROTOCOL_VERSION: '1.0.0';
+export type FeatureHubKind = 'integration' | 'agent-system' | 'agent-network' | 'workflow' | 'auth-user' | 'auth-admin' | 'communication-os' | 'company-os' | 'founder-intelligence' | 'executive-intelligence' | 'talent' | 'social-media';
+export type FeatureHubStability = 'experimental' | 'preview' | 'stable';
+export type HubCapabilityState = 'available' | 'conditional' | 'unsupported' | 'degraded' | 'blocked';
+export type HubReadinessState = 'ready' | 'degraded' | 'blocked';
+export type HubLifecyclePhase = 'defined' | 'installing' | 'installed' | 'starting' | 'running' | 'stopping' | 'disposed' | 'failed';
+export interface HubVersionedRef {
+    readonly key: string;
+    readonly version: string;
+}
+export interface HubCapabilityDeclaration {
+    readonly id: string;
+    readonly capabilityRef: HubVersionedRef;
+    readonly operationRefs: readonly HubVersionedRef[];
+    readonly workflowRefs: readonly HubVersionedRef[];
+    readonly requiredPortIds: readonly string[];
+    readonly optionalPortIds: readonly string[];
+    readonly dependencyCapabilityIds: readonly string[];
+    readonly readinessCheckIds: readonly string[];
+    readonly scheduleIds: readonly string[];
+}
+export interface HubDependencyDeclaration {
+    readonly hubKey: string;
+    readonly versionRange: string;
+    readonly optional?: boolean;
+    readonly capabilityIds?: readonly string[];
+}
+export interface HubSemanticRoute {
+    readonly id: string;
+    readonly capabilityId: string;
+    readonly navigationRef: HubVersionedRef;
+    readonly presentationRouteId: string;
+    readonly defaultPath: string;
+    readonly aliases?: readonly string[];
+    readonly security: 'public' | 'authenticated' | 'fresh-session' | 'admin';
+}
+export interface HubPortDeclaration {
+    readonly id: string;
+    readonly version: string;
+    readonly capabilityIds: readonly string[];
+    readonly secretRefOnly?: boolean;
+}
+export interface HubPolicyDeclaration {
+    readonly id: string;
+    readonly policyRef: HubVersionedRef;
+    readonly operationRefs: readonly HubVersionedRef[];
+}
+export interface HubReadinessCheckDeclaration {
+    readonly id: string;
+    readonly capabilityIds: readonly string[];
+    readonly portIds: readonly string[];
+    readonly blocking: boolean;
+}
+export interface HubScheduleDeclaration {
+    readonly id: string;
+    readonly capabilityId: string;
+    readonly schedulerPortId: string;
+    readonly readinessCheckIds: readonly string[];
+}
+export interface FeatureHubManifest {
+    readonly protocolVersion: typeof FEATURE_HUB_PROTOCOL_VERSION;
+    readonly hubKey: string;
+    readonly hubVersion: string;
+    readonly kind: FeatureHubKind;
+    readonly stability: FeatureHubStability;
+    readonly featureModuleRef: HubVersionedRef;
+    readonly presentationRef: HubVersionedRef;
+    readonly capabilities: readonly HubCapabilityDeclaration[];
+    readonly dependencies: readonly HubDependencyDeclaration[];
+    readonly routes: readonly HubSemanticRoute[];
+    readonly navigationRefs: readonly HubVersionedRef[];
+    readonly requiredPorts: readonly HubPortDeclaration[];
+    readonly optionalPorts: readonly HubPortDeclaration[];
+    readonly policies: readonly HubPolicyDeclaration[];
+    readonly readinessChecks: readonly HubReadinessCheckDeclaration[];
+    readonly schedules: readonly HubScheduleDeclaration[];
+}
+export interface HubCapabilityReadiness {
+    readonly capabilityId: string;
+    readonly state: HubCapabilityState;
+    readonly reasonCode?: string;
+    readonly evidenceRefs: readonly string[];
+}
+export interface HubReadinessReport {
+    readonly hubKey: string;
+    readonly state: HubReadinessState;
+    readonly checkedAt: string;
+    readonly capabilities: readonly HubCapabilityReadiness[];
+}

package/dist/feature-hubs/types.js

@@ -0,0 +1 @@
+export const FEATURE_HUB_PROTOCOL_VERSION="1.0.0";

package/dist/features/index.d.js

@@ -0,0 +1 @@
+export{installFeature}from"./install.js";export{FeatureRegistry}from"./registry.js";export{defineFeature}from"./types.js";export{validateBundleRequires}from"./validate-bundle-requires.js";export{assertFeatureSpecValid,FeatureValidationError,validateFeatureSpec,validateFeatureTargetsV2}from"./validation.js";

package/dist/features/index.d.ts

@@ -0,0 +1,6 @@
+export { type InstallFeatureDeps, installFeature } from './install.js';
+export { FeatureRegistry } from './registry.js';
+export type { DataViewRef, DocRef, EventRef, FeatureModuleMeta, FeatureModuleSpec, FeatureRef, FormRef, IntegrationRef, JobRef, KnowledgeRef, OpRef, PolicyRef, PresentationRef, TelemetryRef, TranslationRef, VisualizationRef, VisualScenarioRef, WorkflowRef, } from './types.js';
+export { defineFeature } from './types.js';
+export { type BundleRequiresEntry, type ValidateBundleRequiresResult, validateBundleRequires, } from './validate-bundle-requires.js';
+export { assertFeatureSpecValid, FeatureValidationError, type FeatureValidationIssue, type FeatureValidationLevel, type FeatureValidationResult, validateFeatureSpec, validateFeatureTargetsV2, } from './validation.js';

package/dist/features/index.js

@@ -0,0 +1 @@
+export{installFeature}from"./install.js";export{FeatureRegistry}from"./registry.js";export{defineFeature}from"./types.js";export{validateBundleRequires}from"./validate-bundle-requires.js";export{assertFeatureSpecValid,FeatureValidationError,validateFeatureSpec,validateFeatureTargetsV2}from"./validation.js";

package/dist/features/install.d.ts

@@ -0,0 +1,38 @@
+import type { CapabilityRegistry } from '../capabilities/index.js';
+import type { DataViewRegistry } from '../data-views/registry.js';
+import type { FormRegistry } from '../forms/forms.js';
+import type { JobSpecRegistry } from '../jobs/spec.js';
+import type { KnowledgeSpaceRegistry } from '../knowledge/spec.js';
+import type { PolicyRegistry } from '../policy/registry.js';
+import type { PresentationSpec } from '../presentations/presentations.js';
+import type { TelemetryRegistry } from '../telemetry/spec.js';
+import type { TranslationRegistry } from '../translations/registry.js';
+import type { VisualScenarioRegistry } from '../visual-scenarios/registry.js';
+import type { VisualizationRegistry } from '../visualizations/registry.js';
+import type { WorkflowRegistry } from '../workflow/spec.js';
+import type { FeatureRegistry } from './registry.js';
+import type { FeatureModuleSpec } from './types.js';
+export interface FeatureIntegrationLookup {
+    get(key: string, version?: string): unknown;
+}
+/** Dependencies for installing a feature. */
+export interface InstallFeatureDeps {
+    features: FeatureRegistry;
+    ops?: import('../operations/registry').OperationSpecRegistry;
+    presentations?: import('../presentations').PresentationRegistry;
+    descriptors?: PresentationSpec[];
+    capabilities?: CapabilityRegistry;
+    workflows?: WorkflowRegistry;
+    knowledge?: KnowledgeSpaceRegistry;
+    telemetry?: TelemetryRegistry;
+    policies?: PolicyRegistry;
+    integrations?: FeatureIntegrationLookup;
+    jobs?: JobSpecRegistry;
+    translations?: TranslationRegistry;
+    dataViews?: DataViewRegistry;
+    visualizations?: VisualizationRegistry;
+    visualScenarios?: VisualScenarioRegistry;
+    forms?: FormRegistry;
+}
+/** Validate and register a feature against optional registries/descriptors. */
+export declare function installFeature(feature: FeatureModuleSpec, deps: InstallFeatureDeps): FeatureRegistry;

package/dist/features/install.js

@@ -0,0 +1 @@
+export function installFeature(e,i){if(i.ops&&e.operations){for(const o of e.operations)if(!i.ops.get(o.key,o.version))throw Error(`installFeature: operation not found ${o.key}.v${o.version}`)}if(i.presentations&&e.presentations){for(const o of e.presentations)if(!i.presentations.get(o.key,o.version))throw Error(`installFeature: presentation not found ${o.key}.v${o.version}`)}if(e.presentationsTargets&&i.descriptors)for(const o of e.presentationsTargets){const t=i.descriptors.find((r)=>r.meta.key===o.key&&r.meta.version===o.version);if(!t)throw Error(`installFeature: V2 descriptor not found ${o.key}.v${o.version}`);for(const r of o.targets)if(!t.targets.includes(r))throw Error(`installFeature: descriptor ${o.key}.v${o.version} missing target ${r}`)}if(e.opToPresentation&&e.opToPresentation.length>0)for(const o of e.opToPresentation){if(i.ops){if(!i.ops.get(o.op.key,o.op.version))throw Error(`installFeature: linked op not found ${o.op.key}.v${o.op.version}`)}if(i.presentations){if(!i.presentations.get(o.pres.key,o.pres.version))throw Error(`installFeature: linked presentation not found ${o.pres.key}.v${o.pres.version}`)}}if(i.capabilities&&e.capabilities?.provides){for(const o of e.capabilities.provides)if(!i.capabilities.get(o.key,o.version))throw Error(`installFeature: capability not registered ${o.key}.v${o.version}`)}if(e.capabilities?.requires?.length){if(!i.capabilities)throw Error(`installFeature: capability registry required to validate capability requirements for ${e.meta.key}`);const o=e.capabilities.provides??[];for(const t of e.capabilities.requires)if(!i.capabilities.satisfies(t,o))throw Error(`installFeature: capability requirement not satisfied ${t.key}${t.version?`.v${t.version}`:""}`)}if(i.dataViews&&e.dataViews){for(const o of e.dataViews)if(!i.dataViews.get(o.key,o.version))throw Error(`installFeature: data view not found ${o.key}.v${o.version}`)}if(i.visualizations&&e.visualizations){for(const o of e.visualizations)if(!i.visualizations.get(o.key,o.version))throw Error(`installFeature: visualization not found ${o.key}.v${o.version}`)}if(i.visualScenarios&&e.visualScenarios){for(const o of e.visualScenarios)if(!i.visualScenarios.get(o.key,o.version))throw Error(`installFeature: visual scenario not found ${o.key}.v${o.version}`)}if(i.forms&&e.forms){for(const o of e.forms)if(!i.forms.get(o.key,o.version))throw Error(`installFeature: form not found ${o.key}.v${o.version}`)}if(i.workflows&&e.workflows){for(const o of e.workflows)if(!i.workflows.get(o.key,o.version))throw Error(`installFeature: workflow not found ${o.key}.v${o.version}`)}if(i.knowledge&&e.knowledge){for(const o of e.knowledge)if(!i.knowledge.get(o.key,o.version))throw Error(`installFeature: knowledge space not found ${o.key}.v${o.version}`)}if(i.telemetry&&e.telemetry){for(const o of e.telemetry)if(!i.telemetry.get(o.key,o.version))throw Error(`installFeature: telemetry spec not found ${o.key}.v${o.version}`)}if(i.policies&&e.policies){for(const o of e.policies)if(!i.policies.get(o.key,o.version))throw Error(`installFeature: policy not found ${o.key}.v${o.version}`)}if(i.integrations&&e.integrations){for(const o of e.integrations)if(!i.integrations.get(o.key,o.version))throw Error(`installFeature: integration not found ${o.key}.v${o.version}`)}if(i.jobs&&e.jobs){for(const o of e.jobs)if(!i.jobs.get(o.key,o.version))throw Error(`installFeature: job not found ${o.key}.v${o.version}`)}if(i.translations&&e.translations)for(const o of e.translations){const t=i.translations.listLocales(o.key);if(t.length===0)throw Error(`installFeature: translation not found ${o.key}.v${o.version}`);if(o.locale&&!t.includes(o.locale))throw Error(`installFeature: translation locale ${o.locale} not found for ${o.key}.v${o.version}`)}i.features.register(e);return i.features}

package/dist/features/registry.d.ts

@@ -0,0 +1,21 @@
+import type { FeatureModuleSpec } from './types.js';
+/** In-memory registry for FeatureModuleSpec. */
+export declare class FeatureRegistry {
+    private items;
+    /** Register a feature module. Throws when the key already exists. */
+    register(f: FeatureModuleSpec): this;
+    /** List all registered feature modules. */
+    list(): FeatureModuleSpec[];
+    /** Get a feature by its key (slug). */
+    get(key: string): FeatureModuleSpec | undefined;
+    /** Filter features by criteria. */
+    filter(criteria: import('../registry-utils').RegistryFilter): FeatureModuleSpec[];
+    /** List features with specific tag. */
+    listByTag(tag: string): FeatureModuleSpec[];
+    /** List features by owner. */
+    listByOwner(owner: string): FeatureModuleSpec[];
+    /** Group features by key function. */
+    groupBy(keyFn: import('../registry-utils').GroupKeyFn<FeatureModuleSpec>): Map<string, FeatureModuleSpec[]>;
+    /** Get unique tags from all features. */
+    getUniqueTags(): string[];
+}

package/dist/features/registry.js

@@ -0,0 +1 @@
+export class FeatureRegistry{items=new Map;register(e){const t=u(e);if(this.items.has(t))throw Error(`Duplicate feature ${t}`);this.items.set(t,e);return this}list(){return[...this.items.values()]}get(e){return this.items.get(e)}filter(e){return r(this.list(),e)}listByTag(e){return this.list().filter((t)=>t.meta.tags?.includes(e))}listByOwner(e){return this.list().filter((t)=>t.meta.owners?.includes(e))}groupBy(e){return s(this.list(),e)}getUniqueTags(){return i(this.list())}}import{filterBy as r,getUniqueTags as i,groupBy as s}from"../registry-utils.js";function u(e){return e.meta.key}

package/dist/features/types.d.ts

@@ -0,0 +1,108 @@
+import type { CapabilityRef, CapabilityRequirement } from '../capabilities/index.js';
+/** Minimal metadata to identify and categorize a feature module. */
+import type { DocBlock } from '../docs/types.js';
+import type { ExperimentRef } from '../experiments/spec.js';
+import type { ImplementationRef } from '../operations/index.js';
+import type { OwnerShipMeta } from '../ownership.js';
+import type { PolicyRef } from '../policy/spec.js';
+import type { PresentationTarget } from '../presentations/presentations.js';
+import type { TranslationRef } from '../translations/spec.js';
+import type { SpecKeyRef, VersionedSpecRef } from '../versioning/index.js';
+export type FeatureModuleMeta = OwnerShipMeta;
+/** Reference to an operation spec (key + version). */
+export type OpRef = VersionedSpecRef;
+/** Reference to an event spec (key + version). */
+export type EventRef = VersionedSpecRef;
+/** Reference to a presentation spec (key + version). */
+export type PresentationRef = VersionedSpecRef;
+/** Reference to a data view spec (key + version). */
+export type DataViewRef = VersionedSpecRef;
+/** Reference to a visualization spec (key + version). */
+export type VisualizationRef = VersionedSpecRef;
+/** Reference to a provider-neutral visual scenario spec (key + version). */
+export type VisualScenarioRef = VersionedSpecRef;
+/** Reference to a form spec (key + version). */
+export type FormRef = VersionedSpecRef;
+/** Reference to a workflow spec (key + version). */
+export type WorkflowRef = VersionedSpecRef;
+/** Reference to a knowledge space spec (key + version). */
+export type KnowledgeRef = VersionedSpecRef;
+/** Reference to a telemetry spec (key + version). */
+export type TelemetryRef = VersionedSpecRef;
+/** Reference to an integration spec (key + version). */
+export type IntegrationRef = VersionedSpecRef;
+/** Reference to a job spec (key + version). */
+export type JobRef = VersionedSpecRef;
+/** Reference to a DocBlock by its unique id. */
+export type DocRef = string;
+export type { PolicyRef, TranslationRef };
+/** Group operations/events/presentations into an installable feature. */
+export interface FeatureModuleSpec {
+    meta: FeatureModuleMeta;
+    /** Contract operations included in this feature. */
+    operations?: OpRef[];
+    /** Events declared/emitted by this feature. */
+    events?: EventRef[];
+    /** Presentations associated to this feature. */
+    presentations?: PresentationRef[];
+    /** Experiments related to this feature. */
+    experiments?: ExperimentRef[];
+    /** Capability bindings exposed/required by this feature. */
+    capabilities?: {
+        provides?: CapabilityRef[];
+        requires?: CapabilityRequirement[];
+    };
+    /** Optional: link ops to presentations for traceability (e.g., ui for op) */
+    opToPresentation?: {
+        op: OpRef;
+        pres: PresentationRef;
+    }[];
+    /** Optional: declare per-presentation target requirements (V2 descriptors) */
+    presentationsTargets?: {
+        /** Presentation key. */
+        key: string;
+        /** Presentation version. */
+        version: string;
+        /** Required targets that must be supported by the descriptor. */
+        targets: PresentationTarget[];
+    }[];
+    /**
+     * Explicit implementation file mappings for the entire feature module.
+     * Used for tracking and verifying that this feature is correctly implemented.
+     */
+    implementations?: ImplementationRef[];
+    /** Data views associated with this feature. */
+    dataViews?: DataViewRef[];
+    /** Visualizations associated with this feature. */
+    visualizations?: VisualizationRef[];
+    /** Visual scenarios associated with this feature. */
+    visualScenarios?: VisualScenarioRef[];
+    /** Forms associated with this feature. */
+    forms?: FormRef[];
+    /** Workflows orchestrated by this feature. */
+    workflows?: WorkflowRef[];
+    /** Knowledge spaces consumed/produced by this feature. */
+    knowledge?: KnowledgeRef[];
+    /** Telemetry spec grouping events tracked by this feature. */
+    telemetry?: TelemetryRef[];
+    /** Policies governing this feature. */
+    policies?: PolicyRef[];
+    /** Integration specs required by this feature. */
+    integrations?: IntegrationRef[];
+    /** Background jobs declared by this feature. */
+    jobs?: JobRef[];
+    /** Translation specs providing i18n messages for this feature. */
+    translations?: TranslationRef[];
+    /** DocBlock IDs documenting this feature. */
+    docs?: DocRef[];
+}
+/**
+ * Reference to a feature (unversioned).
+ * Features are identified by key only, without version pinning.
+ */
+export type FeatureRef = SpecKeyRef;
+/**
+ * Helper to define a Feature.
+ */
+export declare const defineFeature: (spec: FeatureModuleSpec) => FeatureModuleSpec;
+export declare const tech_contracts_ops_to_presentation_linking_DocBlocks: DocBlock[];

package/dist/features/types.js

@@ -0,0 +1,62 @@
+export const defineFeature=(e)=>e;export const tech_contracts_ops_to_presentation_linking_DocBlocks=[{id:"docs.tech.contracts.ops-to-presentation-linking",title:"Ops \u2194 Presentation linking (V2)",summary:"This document explains how operations (OperationSpec) are linked to Presentations (PresentationSpec) via Feature modules.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/ops-to-presentation-linking",tags:["tech","contracts","ops-to-presentation-linking"],body:`### Ops to Presentation Linking (V2)
+
+This document explains how operations (\`OperationSpec\`) are linked to presentations (\`PresentationSpec\`) via feature modules.
+
+- Location: \`packages/libs/contracts-spec/src/features/types.ts\`
+- Field: \`FeatureModuleSpec.opToPresentation?: { op: OpRef; pres: PresentationRef }[]\`
+- Validation:
+  - \`validateFeatureSpec()\` checks that linked refs are declared in the feature itself
+  - \`installFeature()\` checks that declared refs exist in the provided registries
+  - \`validateFeatureTargetsV2()\` checks descriptor target support
+
+Example:
+
+\`\`\`ts
+import { defineFeature, FeatureRegistry } from '@lssm/lib.contracts-spec/features';
+
+export const WidgetsFeature = defineFeature({
+  meta: {
+    key: 'myapp.widgets.linkage',
+    version: '1.0.0',
+    title: 'Widgets (linked)',
+    description: 'Links create and update operations to UI presentations.',
+    domain: 'widgets',
+    owners: ['platform.widgets'],
+    tags: ['widgets', 'linkage'],
+    stability: 'beta',
+  },
+  operations: [
+    { key: 'widgets.create', version: '1.0.0' },
+    { key: 'widgets.update', version: '1.0.0' },
+  ],
+  presentations: [
+    { key: 'myapp.widgets.editor.page', version: '1.0.0' },
+  ],
+  opToPresentation: [
+    {
+      op: { key: 'widgets.create', version: '1.0.0' },
+      pres: { key: 'myapp.widgets.editor.page', version: '1.0.0' },
+    },
+    {
+      op: { key: 'widgets.update', version: '1.0.0' },
+      pres: { key: 'myapp.widgets.editor.page', version: '1.0.0' },
+    },
+  ],
+  presentationsTargets: [
+    {
+      key: 'myapp.widgets.editor.page',
+      version: '1.0.0',
+      targets: ['react', 'markdown'],
+    },
+  ],
+});
+
+const features = new FeatureRegistry().register(WidgetsFeature);
+\`\`\`
+
+Notes:
+
+- This enables traceability: the UI flow that realizes an operation is discoverable via the feature catalog.
+- Presentations can target multiple outputs (\`react\`, \`markdown\`, \`application/json\`, \`application/xml\`).
+- Use \`renderFeaturePresentation()\` to render a descriptor to a given target with a component map.
+`}];

package/dist/features/validate-bundle-requires.d.js

@@ -0,0 +1 @@
+export{};

package/dist/features/validate-bundle-requires.d.ts

@@ -0,0 +1,29 @@
+import type { FeatureModuleSpec } from './types.js';
+/** Minimal registry interface for validation. FeatureRegistry satisfies this. */
+interface FeatureRegistryLike {
+    get(key: string): FeatureModuleSpec | undefined;
+}
+/** Bundle requires entry (from ModuleBundleSpec.requires). */
+export interface BundleRequiresEntry {
+    key: string;
+    version: string;
+}
+/** Result of validating bundle requires against a feature registry. */
+export interface ValidateBundleRequiresResult {
+    valid: boolean;
+    errors: string[];
+    missing: {
+        key: string;
+        version: string;
+    }[];
+}
+/**
+ * Validates that each required feature exists in the registry and matches version (if specified).
+ * Use when resolving bundles to ensure declared dependencies are satisfied.
+ *
+ * @param requires - Array of { key, version } from ModuleBundleSpec.requires
+ * @param registry - FeatureRegistry with registered features (e.g. AiChatFeature)
+ * @returns Validation result with any missing or version-mismatched features
+ */
+export declare function validateBundleRequires(requires: BundleRequiresEntry[], registry: FeatureRegistryLike): ValidateBundleRequiresResult;
+export {};

package/dist/features/validate-bundle-requires.js

@@ -0,0 +1 @@
+export function validateBundleRequires(s,o){const r=[],t=[];for(const e of s){const n=o.get(e.key);if(!n){t.push({key:e.key,version:e.version});r.push(`Required feature "${e.key}" not found in registry`);continue}const i=n.meta.version;if(i&&e.version&&i!==e.version)r.push(`Feature "${e.key}" version mismatch: required ${e.version}, registered ${i}`)}return{valid:r.length===0,errors:r,missing:t}}

package/dist/features/validation.d.ts

@@ -0,0 +1,21 @@
+import type { PresentationSpec } from '../presentations/presentations.js';
+import type { FeatureModuleSpec } from './types.js';
+export type FeatureValidationLevel = 'error' | 'warning' | 'info';
+export interface FeatureValidationIssue {
+    level: FeatureValidationLevel;
+    message: string;
+    path?: string;
+    context?: Record<string, unknown>;
+}
+export interface FeatureValidationResult {
+    valid: boolean;
+    issues: FeatureValidationIssue[];
+}
+export declare class FeatureValidationError extends Error {
+    readonly issues: FeatureValidationIssue[];
+    constructor(message: string, issues: FeatureValidationIssue[]);
+}
+/** Ensure declared target requirements exist on the provided descriptors. */
+export declare function validateFeatureTargetsV2(feature: FeatureModuleSpec, descriptors: PresentationSpec[]): boolean;
+export declare function validateFeatureSpec(spec: FeatureModuleSpec): FeatureValidationResult;
+export declare function assertFeatureSpecValid(spec: FeatureModuleSpec): void;

package/dist/features/validation.js

@@ -0,0 +1 @@
+export class FeatureValidationError extends Error{issues;constructor(e,t){super(e);this.issues=t;this.name="FeatureValidationError"}}export function validateFeatureTargetsV2(e,t){if(!e.presentationsTargets||e.presentationsTargets.length===0)return!0;for(const n of e.presentationsTargets){const r=t.find((a)=>a.meta.key===n.key&&a.meta.version===n.version);if(!r)throw Error(`V2 descriptor not found ${n.key}.v${n.version}`);for(const a of n.targets)if(!r.targets.includes(a))throw Error(`Descriptor ${n.key}.v${n.version} missing target ${a}`)}return!0}export function validateFeatureSpec(e){const t=[];d(e,t);g(e,t);v(e,t);p(e,t);h(e,t);return{valid:t.every((n)=>n.level!=="error"),issues:t}}export function assertFeatureSpecValid(e){const t=validateFeatureSpec(e);if(!t.valid)throw new FeatureValidationError(`Feature ${e.meta.key}.v${e.meta.version} is invalid`,t.issues)}function d(e,t){u(e.meta.key,"Feature must have a non-empty key","meta.key",t);u(e.meta.version,"Feature must have a non-empty version","meta.version",t);u(e.meta.description,"Feature must have a non-empty description","meta.description",t);if(!e.meta.stability)t.push({level:"error",message:"Feature must declare a stability level",path:"meta.stability"});if(!e.meta.owners.length)t.push({level:"error",message:"Feature must declare at least one owner",path:"meta.owners"});if(!e.meta.tags.length)t.push({level:"error",message:"Feature must declare at least one tag",path:"meta.tags"})}function v(e,t){if(Boolean(e.operations?.length)||Boolean(e.events?.length)||Boolean(e.presentations?.length)||Boolean(e.experiments?.length)||Boolean(e.capabilities?.provides?.length)||Boolean(e.capabilities?.requires?.length)||Boolean(e.opToPresentation?.length)||Boolean(e.presentationsTargets?.length)||Boolean(e.implementations?.length)||Boolean(e.dataViews?.length)||Boolean(e.visualizations?.length)||Boolean(e.visualScenarios?.length)||Boolean(e.forms?.length)||Boolean(e.workflows?.length)||Boolean(e.knowledge?.length)||Boolean(e.telemetry?.length)||Boolean(e.policies?.length)||Boolean(e.integrations?.length)||Boolean(e.jobs?.length)||Boolean(e.translations?.length)||Boolean(e.docs?.length))return;t.push({level:"warning",message:"Feature declares only metadata; add refs, docs, or implementations to make it actionable",path:"meta"})}function g(e,t){i(e.operations,"operations",t);i(e.events,"events",t);i(e.presentations,"presentations",t);i(e.experiments,"experiments",t);i(e.capabilities?.provides,"capabilities.provides",t);m(e.capabilities?.requires,t);i(e.dataViews,"dataViews",t);i(e.visualizations,"visualizations",t);i(e.visualScenarios,"visualScenarios",t);i(e.forms,"forms",t);i(e.workflows,"workflows",t);i(e.knowledge,"knowledge",t);i(e.telemetry,"telemetry",t);i(e.policies,"policies",t);i(e.integrations,"integrations",t);i(e.jobs,"jobs",t);f(e.translations,t);c(e.docs,"docs",t)}function p(e,t){const n=new Set((e.operations??[]).map((a)=>`${a.key}.v${a.version}`)),r=new Set((e.presentations??[]).map((a)=>`${a.key}.v${a.version}`));e.opToPresentation?.forEach((a,o)=>{const s=`opToPresentation[${o}]`;if(!n.has(`${a.op.key}.v${a.op.version}`))t.push({level:"error",message:`Linked operation ${a.op.key}.v${a.op.version} is not declared in feature.operations`,path:`${s}.op`});if(!r.has(`${a.pres.key}.v${a.pres.version}`))t.push({level:"error",message:`Linked presentation ${a.pres.key}.v${a.pres.version} is not declared in feature.presentations`,path:`${s}.pres`})})}function h(e,t){const n=new Set((e.presentations??[]).map((a)=>`${a.key}.v${a.version}`)),r=new Set;e.presentationsTargets?.forEach((a,o)=>{const s=`presentationsTargets[${o}]`,l=`${a.key}.v${a.version}`;if(r.has(l))t.push({level:"error",message:`Duplicate presentation target requirement for ${l}`,path:s});r.add(l);if(!n.has(l))t.push({level:"error",message:`Presentation target requirement ${l} is not declared in feature.presentations`,path:s});if(!a.targets.length)t.push({level:"error",message:`Presentation target requirement ${l} must declare at least one target`,path:`${s}.targets`})})}function i(e,t,n){if(!e?.length)return;const r=new Set;e.forEach((a,o)=>{const s=`${a.key}.v${a.version??"*"}`;if(r.has(s))n.push({level:"error",message:`Duplicate reference ${s} in ${t}`,path:`${t}[${o}]`});r.add(s)})}function m(e,t){if(!e?.length)return;const n=new Set;e.forEach((r,a)=>{const o=`${r.key}.v${r.version??"*"}`;if(n.has(o))t.push({level:"error",message:`Duplicate capability requirement ${o}`,path:`capabilities.requires[${a}]`});n.add(o)})}function f(e,t){if(!e?.length)return;const n=new Set;e.forEach((r,a)=>{const o=`${r.key}.v${r.version}:${r.locale??"*"}`;if(n.has(o))t.push({level:"error",message:`Duplicate translation reference ${o}`,path:`translations[${a}]`});n.add(o)})}function c(e,t,n){if(!e?.length)return;const r=new Set;e.forEach((a,o)=>{if(r.has(a))n.push({level:"error",message:`Duplicate value "${a}" in ${t}`,path:`${t}[${o}]`});r.add(a)})}function u(e,t,n,r){if(e?.trim())return;r.push({level:"error",message:t,path:n})}

package/dist/forms/entity-bound-forms.d.ts

@@ -0,0 +1,8 @@
+import type { DocBlock } from '../docs/types.js';
+export declare const entityBoundFormsMigrationNotes: {
+    readonly packageSubpath: '@lssm/lib.contracts-spec/forms';
+    readonly compatibility: 'breaking-allowed';
+    readonly publicExport: '@lssm/lib.contracts-spec/forms/entity-bound';
+    readonly principles: readonly ['Entities own canonical identity; forms are renderable projections.', 'Permissive capture records completion debt instead of blocking intake.', 'Strict readiness is a separate check from capture acceptance.', 'Entity relations use EdgeSpec; form parts use form-specific bindings.', 'Communication intake maps messages to form intake payloads without UI or AI extraction.'];
+};
+export declare const tech_contracts_forms_entity_bound_DocBlocks: DocBlock[];

package/dist/forms/entity-bound-forms.js

@@ -0,0 +1,30 @@
+export const entityBoundFormsMigrationNotes={packageSubpath:"@lssm/lib.contracts-spec/forms",compatibility:"breaking-allowed",publicExport:"@lssm/lib.contracts-spec/forms/entity-bound",principles:["Entities own canonical identity; forms are renderable projections.","Permissive capture records completion debt instead of blocking intake.","Strict readiness is a separate check from capture acceptance.","Entity relations use EdgeSpec; form parts use form-specific bindings.","Communication intake maps messages to form intake payloads without UI or AI extraction."]};export const tech_contracts_forms_entity_bound_DocBlocks=[{id:"docs.tech.contracts.forms.entityBound",title:"Contracts: Entity-bound Form Projections",summary:"How to model entity-first form projections, completion debt, and message intake without overloading entity edges.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/forms/entity-bound",tags:["tech","contracts","forms","entities","intake"],body:`# Entity-bound form projections
+
+Entity-bound forms treat the business entity as the stable semantic anchor and the form as a renderable projection. A customer, appointment, or other entity can expose quick, full, edit, intake, or part projections without turning each projection into a new entity type.
+
+## Authoring model
+
+- Keep canonical entity identity and true entity-to-entity cardinality on entity contracts.
+- Keep renderable fields, layout, policy, and actions on \`FormSpec\`.
+- Bind a form projection to an entity with metadata such as entity key, projection kind, version, and field/path mappings.
+- Use form-part bindings for identity, address, contact, and other sub-capture surfaces when they are parts of one entity.
+- Use \`EdgeSpec\` only for real entity relations, such as customer-to-appointment, not for field-group containment.
+
+## Capture versus readiness
+
+Capture acceptance and completion readiness are intentionally separate:
+
+1. **Capture accepted** means the user or message provided enough information to preserve a draft/intake payload.
+2. **Completion debt** records skipped or missing fields with path/profile metadata.
+3. **Strict readiness** can later require a full profile without invalidating the original capture.
+
+This keeps quick creation and message intake permissive while still giving downstream workflows explicit quality gates.
+
+## Communication intake boundary
+
+Communication runtime may map a normalized message/request into an entity-bound intake payload, but it should stay deterministic and adapter-free. The first-pass hook should carry source references such as message id, thread id, and channel, then return accepted values plus completion debt. Full AI extraction, persistence, and CommunicationOS UI remain downstream concerns.
+
+## Package exports
+
+Consumers should import the form projection documentation surface from \`@lssm/lib.contracts-spec/forms/entity-bound\` and implementation primitives from \`@lssm/lib.contracts-spec/forms\` unless a narrower subpath is introduced with matching package exports and tests.
+`}];

package/dist/forms/entity-bound.d.ts

@@ -0,0 +1 @@
+export * from './entity-bound-forms.js';

package/dist/forms/entity-bound.js

@@ -0,0 +1 @@
+export*from"./entity-bound-forms.js";

package/dist/forms/forms.d.js

@@ -0,0 +1 @@
+export{};