@lssm/lib.contracts-spec 17.3.2

package/dist/shared-entities/task-validators.d.ts

@@ -0,0 +1,24 @@
+import type { DocBlock } from '../docs/types.js';
+import type { SharedTask } from './task.js';
+/** Validation result — discriminated union. */
+export type TaskValidationResult = {
+    valid: true;
+} | {
+    valid: false;
+    error: string;
+};
+/**
+ * Validate a {@link SharedTask} for workflow DAG context (A9 invariant).
+ * Rejects tasks with `parent` set — tree semantics are incompatible with DAG.
+ */
+export declare function validateWorkflowTask(task: SharedTask): TaskValidationResult;
+/** Validate all tasks in a workflow DAG. Returns first failure or `valid: true`. */
+export declare function validateWorkflowTasks(tasks: SharedTask[]): TaskValidationResult;
+/**
+ * Validate a {@link SharedTask} for agent task-tree context (A9 invariant).
+ * Rejects tasks with `dependsOn` set — DAG semantics are incompatible with tree topology.
+ */
+export declare function validateAgentTask(task: SharedTask): TaskValidationResult;
+/** Validate all tasks in an agent task tree. Returns first failure or `valid: true`. */
+export declare function validateAgentTasks(tasks: SharedTask[]): TaskValidationResult;
+export declare const shared_entities_task_validators_DocBlocks: DocBlock[];

package/dist/shared-entities/task-validators.js

@@ -0,0 +1 @@
+export function validateWorkflowTask(t){if(t.parent!==void 0)return{valid:!1,error:`workflow tasks must not have 'parent' set (A9 invariant): task '${t.id}' has parent='${t.parent}'. Remove 'parent' or use validateAgentTask() instead.`};return{valid:!0}}export function validateWorkflowTasks(t){for(const a of t){const e=validateWorkflowTask(a);if(!e.valid)return e}return{valid:!0}}export function validateAgentTask(t){if(t.dependsOn!==void 0&&t.dependsOn.length>0)return{valid:!1,error:`agent tasks must not have 'dependsOn' set (A9 invariant): task '${t.id}' has dependsOn=[${t.dependsOn.join(", ")}]. Remove 'dependsOn' or use validateWorkflowTask() instead.`};return{valid:!0}}export function validateAgentTasks(t){for(const a of t){const e=validateAgentTask(a);if(!e.valid)return e}return{valid:!0}}export const shared_entities_task_validators_DocBlocks=[{id:"docs.tech.contracts.shared-entities.task-validators",title:"Task Validators \u2014 Dual Workflow/Agent Runtime Validators (A9)",summary:"`validateWorkflowTask` rejects tasks with `parent`; `validateAgentTask` rejects tasks with `dependsOn`. Both enforce the A9 invariant at runtime.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/shared-entities/task-validators",tags:["tech","contracts","shared-entities","task","validators","a9"],body:"# Task Validators (A9)\n\n| Function | Context | Rejects |\n|----------|---------|--------|\n| `validateWorkflowTask` | Workflow DAG | `parent` set |\n| `validateWorkflowTasks` | Workflow DAG (batch) | first task with `parent` |\n| `validateAgentTask` | Agent tree | `dependsOn` set |\n| `validateAgentTasks` | Agent tree (batch) | first task with `dependsOn` |\n"}];

package/dist/shared-entities/task.d.ts

@@ -0,0 +1,128 @@
+import type { CapabilityRef } from '../capabilities/index.js';
+import type { DocBlock } from '../docs/types.js';
+import type { OpRef } from '../features/index.js';
+/** Lifecycle status for a shared Task (workflow DAG or agent tree context). */
+export type SharedTaskStatus = 'pending' | 'in_progress' | 'completed' | 'failed' | 'skipped' | 'cancelled';
+export declare const SharedTaskStatusEnum: {
+    readonly Pending: 'pending';
+    readonly InProgress: 'in_progress';
+    readonly Completed: 'completed';
+    readonly Failed: 'failed';
+    readonly Skipped: 'skipped';
+    readonly Cancelled: 'cancelled';
+};
+/**
+ * Cross-context Task used by both workflow DAG and agent task-tree runtimes.
+ *
+ * ## A9 Invariant
+ *
+ * Both `dependsOn?` and `parent?` are OPTIONAL on the shared type.
+ * Context-specific validators (`validateWorkflowTask` / `validateAgentTask`)
+ * enforce mutual exclusion at runtime:
+ * - Workflow validator rejects tasks with `parent` set.
+ * - Agent validator rejects tasks with `dependsOn` set.
+ *
+ * Both `undefined` = root task (valid in either context).
+ */
+export interface SharedTask {
+    /** Stable task identifier within its container. */
+    id: string;
+    /** Human-readable label. */
+    label: string;
+    /** Optional description. */
+    description?: string;
+    /** Current lifecycle status. */
+    status?: SharedTaskStatus;
+    /**
+     * Workflow DAG: task IDs this task depends on.
+     * **Workflow context only.** Workflow validator rejects tasks where `parent` is also set.
+     */
+    dependsOn?: string[];
+    /**
+     * Agent tree: parent task ID.
+     * **Agent context only.** Agent validator rejects tasks where `dependsOn` is also set.
+     */
+    parent?: string;
+    /** Conditional expression evaluated before executing (workflow runIf gate). */
+    runIf?: string;
+    /** Optional domain-specific metadata (JSON-serializable). */
+    meta?: Record<string, unknown>;
+    /**
+     * Task execution category. Drives V2 runner dispatch:
+     * - `automation` — executes `operation` via OperationExecutor.
+     * - `human`      — suspends workflow until external input via `executeStep(id, input)`.
+     * - `decision`   — executes `operation`; result drives downstream edge conditions.
+     */
+    type?: 'human' | 'automation' | 'decision';
+    /** Operation reference executed for automation/decision tasks. */
+    operation?: OpRef;
+    /**
+     * Guard evaluated before executing this task.
+     * `expression` guards use `evaluateExpression()`; `policy` guards use the
+     * configured `guardEvaluator`.
+     * Task is skipped when the guard returns false.
+     */
+    guard?: {
+        type: 'policy' | 'expression';
+        value: string;
+    };
+    /**
+     * Retry policy applied on transient operation failures.
+     * `fixed` holds a constant `delayMs`; `exponential` doubles the delay each
+     * attempt up to `maxDelayMs`.
+     */
+    retry?: {
+        maxAttempts: number;
+        backoff?: 'fixed' | 'exponential';
+        delayMs?: number;
+        maxDelayMs?: number;
+    };
+    /** Per-task execution timeout in milliseconds. Throws `timeout` error on breach. */
+    timeoutMs?: number;
+    /**
+     * Integration slot IDs that must be bound before this task can execute.
+     * Checked during pre-flight; any unbound slot blocks workflow start.
+     */
+    requiredIntegrations?: string[];
+    /**
+     * Capability refs that must be enabled in the resolved app config.
+     * Checked during pre-flight; any missing capability blocks workflow start.
+     */
+    requiredCapabilities?: CapabilityRef[];
+}
+/**
+ * Canonical cross-domain Task entity (Layer 1: slug + edges, M2).
+ * See {@link SharedTask} for the A9-compliant cross-context task type.
+ */
+export declare const TaskEntity: {
+    readonly meta: {
+        readonly key: "task";
+        readonly version: "1.0.0";
+        readonly description: "A unit of work in a workflow DAG or agent task tree. Supports both dependsOn (DAG) and parent (tree) as optional fields per A9 invariant.";
+        readonly title: "Task";
+        readonly domain: "shared";
+        readonly stability: 'stable';
+        readonly owners: ["platform.core"];
+        readonly tags: ["task", "shared", "cross-domain", "workflow", "agent"];
+    };
+    readonly edges: [{
+        readonly id: "task-to-project";
+        readonly from: "task";
+        readonly to: "project";
+        readonly relation: "belongs-to";
+        readonly cardinality: 'many-to-one';
+        readonly directed: true;
+        readonly label: "Project";
+        readonly inverse: "project-to-task";
+    }, {
+        readonly id: "task-to-person";
+        readonly from: "task";
+        readonly to: "person";
+        readonly relation: "assigned-to";
+        readonly cardinality: 'many-to-one';
+        readonly directed: true;
+        readonly label: "Assignee";
+        readonly inverse: "person-to-task";
+    }];
+};
+export declare const shared_entities_task_DocBlocks: DocBlock[];

package/dist/shared-entities/task.js

@@ -0,0 +1 @@
+import{defineContractEntity as e}from"../entities/defineContractEntity.js";export const SharedTaskStatusEnum={Pending:"pending",InProgress:"in_progress",Completed:"completed",Failed:"failed",Skipped:"skipped",Cancelled:"cancelled"};export const TaskEntity=e({meta:{key:"task",version:"1.0.0",description:"A unit of work in a workflow DAG or agent task tree. Supports both dependsOn (DAG) and parent (tree) as optional fields per A9 invariant.",title:"Task",domain:"shared",stability:"stable",owners:["platform.core"],tags:["task","shared","cross-domain","workflow","agent"]},edges:[{id:"task-to-project",from:"task",to:"project",relation:"belongs-to",cardinality:"many-to-one",directed:!0,label:"Project",inverse:"project-to-task"},{id:"task-to-person",from:"task",to:"person",relation:"assigned-to",cardinality:"many-to-one",directed:!0,label:"Assignee",inverse:"person-to-task"}]});export const shared_entities_task_DocBlocks=[{id:"docs.tech.contracts.shared-entities.task",title:"SharedTask + TaskEntity \u2014 Cross-Context Task (A9 Invariant)",summary:"`SharedTask` carries both `dependsOn?` (workflow DAG) and `parent?` (agent tree) as optional. Validators enforce mutual exclusion per A9. `TaskEntity` is the Layer-1 contract registration.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/shared-entities/task",tags:["tech","contracts","shared-entities","task","a9","workflow","agent"],body:"# SharedTask + TaskEntity\n\n## A9 Invariant\n\n| Field | Context | Validator rejects |\n|-------|---------|------------------|\n| `dependsOn?` | Workflow DAG | Agent validator |\n| `parent?` | Agent tree | Workflow validator |\n\nBoth `undefined` \u2192 root task (valid in either context).\n\n## V2 Execution Fields (Path B parity)\n\n- `type`: `automation` (default) | `human` | `decision`\n- `operation?: OpRef` \u2014 dispatched by the V2 runner's OperationExecutor\n- `guard?` \u2014 expression or policy guard evaluated before execution; task skipped on false\n- `retry?` \u2014 fixed/exponential backoff with configurable attempts, delay, and cap\n- `timeoutMs?` \u2014 per-task timeout; raises `WorkflowExecutionError('timeout')`\n- `requiredIntegrations?` \u2014 slot IDs checked during pre-flight\n- `requiredCapabilities?` \u2014 CapabilityRefs checked during pre-flight\n"}];

package/dist/shared-entities/team.d.ts

@@ -0,0 +1,44 @@
+import type { DocBlock } from '../docs/types.js';
+/**
+ * Canonical cross-domain Team entity (Layer 1: slug + edges, M2).
+ */
+export declare const TeamEntity: {
+    readonly meta: {
+        readonly key: "team";
+        readonly version: "1.0.0";
+        readonly description: "A group of persons organized around a shared purpose.";
+        readonly title: "Team";
+        readonly domain: "shared";
+        readonly stability: 'stable';
+        readonly owners: ["platform.core"];
+        readonly tags: ["team", "shared", "cross-domain"];
+    };
+    readonly edges: [{
+        readonly id: "team-to-person";
+        readonly from: "team";
+        readonly to: "person";
+        readonly relation: "has-member";
+        readonly cardinality: 'many-to-many';
+        readonly directed: true;
+        readonly label: "Members";
+        readonly inverse: "person-to-team";
+    }, {
+        readonly id: "team-to-project";
+        readonly from: "team";
+        readonly to: "project";
+        readonly relation: "owns";
+        readonly cardinality: 'one-to-many';
+        readonly directed: true;
+        readonly label: "Projects";
+        readonly inverse: "project-to-team";
+    }, {
+        readonly id: "team-to-resource";
+        readonly from: "team";
+        readonly to: "resource";
+        readonly relation: "manages";
+        readonly cardinality: 'one-to-many';
+        readonly directed: true;
+        readonly label: "Resources";
+    }];
+};
+export declare const shared_entities_team_DocBlocks: DocBlock[];

package/dist/shared-entities/team.js

@@ -0,0 +1,12 @@
+import{defineContractEntity as e}from"../entities/defineContractEntity.js";export const TeamEntity=e({meta:{key:"team",version:"1.0.0",description:"A group of persons organized around a shared purpose.",title:"Team",domain:"shared",stability:"stable",owners:["platform.core"],tags:["team","shared","cross-domain"]},edges:[{id:"team-to-person",from:"team",to:"person",relation:"has-member",cardinality:"many-to-many",directed:!0,label:"Members",inverse:"person-to-team"},{id:"team-to-project",from:"team",to:"project",relation:"owns",cardinality:"one-to-many",directed:!0,label:"Projects",inverse:"project-to-team"},{id:"team-to-resource",from:"team",to:"resource",relation:"manages",cardinality:"one-to-many",directed:!0,label:"Resources"}]});export const shared_entities_team_DocBlocks=[{id:"docs.tech.contracts.shared-entities.team",title:"TeamEntity \u2014 Cross-Domain Team Contract Entity",summary:"`TeamEntity` is the canonical cross-domain entity for a group of persons. Layer 1: `team` slug with edges to person, project, resource.",kind:"reference",visibility:"public",route:"/docs/tech/contracts/shared-entities/team",tags:["tech","contracts","shared-entities","team"],body:`# TeamEntity
+
+Layer 1 (M2): slug + edges. Entity key: \`'team'\`.
+
+## Edges
+
+| ID | From | To | Relation | Cardinality |
+|----|----|----|----|----|  
+| \`team-to-person\` | team | person | has-member | many-to-many |
+| \`team-to-project\` | team | project | owns | one-to-many |
+| \`team-to-resource\` | team | resource | manages | one-to-many |
+`}];

package/dist/sop/generation-sources.d.ts

@@ -0,0 +1,57 @@
+import type { OpRef } from '../features/index.js';
+export declare const SopGenerationSourcesDocBlock: {
+    id: string;
+    title: string;
+    body: string;
+    tags: string[];
+};
+export type SopGenerationSourceKind = 'capability' | 'integration' | 'operation' | 'policy' | 'health' | 'knowledge' | 'incident' | 'case';
+export interface SopGenerationSourceBase {
+    readonly kind: SopGenerationSourceKind;
+    readonly sourceRef: string;
+    readonly sourceRevisionRef: string;
+    readonly observedAt: string;
+    readonly expiresAt: string;
+    readonly evidenceRefs: readonly string[];
+}
+export interface SopCapabilitySource extends SopGenerationSourceBase {
+    readonly kind: 'capability';
+    readonly capabilityRefs: readonly string[];
+}
+export interface SopIntegrationSource extends SopGenerationSourceBase {
+    readonly kind: 'integration';
+    readonly integrationRefs: readonly string[];
+}
+export interface SopOperationSource extends SopGenerationSourceBase {
+    readonly kind: 'operation';
+    readonly operations: readonly OpRef[];
+}
+export interface SopPolicySource extends SopGenerationSourceBase {
+    readonly kind: 'policy';
+    readonly policyRefs: readonly string[];
+}
+export type SopHealthStatus = 'healthy' | 'degraded' | 'down' | 'unknown';
+export interface SopHealthSource extends SopGenerationSourceBase {
+    readonly kind: 'health';
+    readonly signals: Readonly<Record<string, SopHealthStatus>>;
+}
+export interface SopKnowledgeSource extends SopGenerationSourceBase {
+    readonly kind: 'knowledge';
+    readonly knowledgeRefs: readonly string[];
+}
+export interface SopIncidentSource extends SopGenerationSourceBase {
+    readonly kind: 'incident';
+    readonly incidentRefs: readonly string[];
+}
+export interface SopCaseSource extends SopGenerationSourceBase {
+    readonly kind: 'case';
+    readonly caseRefs: readonly string[];
+}
+export type SopGenerationSourceContribution = SopCapabilitySource | SopIntegrationSource | SopOperationSource | SopPolicySource | SopHealthSource | SopKnowledgeSource | SopIncidentSource | SopCaseSource;
+export interface SopGenerationSourceSnapshot {
+    readonly version: '1';
+    readonly snapshotRef: string;
+    readonly digest: string;
+    readonly createdAt: string;
+    readonly contributions: readonly SopGenerationSourceContribution[];
+}

package/dist/sop/generation-sources.js

@@ -0,0 +1,5 @@
+export const SopGenerationSourcesDocBlock={id:"doc:sop.generation-sources",title:"Living SOP generation source snapshots",body:`Living SOP generation consumes canonical, serializable source contributions rather than provider objects or delivery-matrix state.
+
+Each contribution names an immutable source revision, validity window, and opaque evidence references. Source providers must never place raw answers, message bodies, contact data, prompts, or secrets in identity or evidence references. The runtime copies only the declared semantic fields, applies kind-specific freshness ceilings, canonicalizes ordering, and computes a content-addressed snapshot. Live generation revalidates source expiry against the current clock; historical projection is replay-only. Product adapters derive authority from authenticated server context; generation intent never carries tenant, workspace, actor, policy, or capability authority.
+
+Capability availability comes from the deployed runtime source. Delivery and qualification matrices may be recorded as documentation evidence, but never decide executable availability. Operation contributions resolve aliases to canonical registered key and version before snapshotting. The snapshot executes no effects; Workflow and Connect retain effect authority.`,tags:["sop","generation","provenance","security"]};

package/dist/sop/index.d.ts

@@ -0,0 +1,5 @@
+export * from './generation-sources.js';
+export * from './operations.js';
+export * from './sop.feature.js';
+export * from './types.js';
+export * from './validation.js';

package/dist/sop/index.js

@@ -0,0 +1 @@
+export*from"./generation-sources.js";export*from"./operations.js";export*from"./sop.feature.js";export*from"./types.js";export*from"./validation.js";