sdd-agent-platform 0.3.0 → 0.4.1

package/node_modules/@sdd-agent-platform/core/src/router/runtime-validation.ts

@@ -0,0 +1,277 @@
+import {
+  AGENT_REGISTRY_CONTRACT_VERSION,
+  AGENT_SKILL_TEAM_RUNTIME_CONTRACT_VERSION,
+  WORKFLOW_GATE_CONTRACT_VERSION
+} from '../contracts.js';
+import { contractIssue, type ContractValidationIssue } from '../contracts/issues.js';
+import { listAgentRegistry, type AgentRegistryEntry } from '../registries/agent-registry.js';
+import { listWorkflowGates, type WorkflowGateContract } from '../registries/workflow-gates.js';
+import { BUILT_IN_MODEL_POLICIES, buildAgentSkillRuntimeRegistry } from './runtime-registry.js';
+import { inspectAgentSkillTeamRuntime } from './runtime-inspection.js';
+import type {
+  AgentProfileId,
+  AgentSkillTeamRuntimeInspection,
+  CapabilitySourceCatalogEntry,
+  RuntimeRegistryEntrySource
+} from './agent-runtime.js';
+
+export interface WorkflowGateValidation {
+  version: typeof WORKFLOW_GATE_CONTRACT_VERSION;
+  valid: boolean;
+  workflows: WorkflowGateContract[];
+  issues: ContractValidationIssue[];
+}
+
+export interface AgentRegistryValidation {
+  version: typeof AGENT_REGISTRY_CONTRACT_VERSION;
+  valid: boolean;
+  agents: AgentRegistryEntry[];
+  issues: ContractValidationIssue[];
+}
+
+export interface AgentSkillTeamRuntimeValidation {
+  version: typeof AGENT_SKILL_TEAM_RUNTIME_CONTRACT_VERSION;
+  valid: boolean;
+  inspection: AgentSkillTeamRuntimeInspection;
+  issues: ContractValidationIssue[];
+}
+
+export async function validateWorkflowGates(projectRoot: string): Promise<WorkflowGateValidation> {
+  const registry = await listWorkflowGates(projectRoot);
+  const agentRegistry = await listAgentRegistry(projectRoot);
+  const agentIds = new Set(agentRegistry.agents.map((agent) => agent.id));
+  const issues = registry.workflows.flatMap((workflow) => validateWorkflowGate(workflow, agentIds));
+  return {
+    version: WORKFLOW_GATE_CONTRACT_VERSION,
+    valid: issues.length === 0,
+    workflows: registry.workflows,
+    issues
+  };
+}
+
+export async function validateAgentRegistry(projectRoot: string): Promise<AgentRegistryValidation> {
+  const registry = await listAgentRegistry(projectRoot);
+  const issues = registry.agents.flatMap(validateAgentRegistryEntry);
+  return {
+    version: AGENT_REGISTRY_CONTRACT_VERSION,
+    valid: issues.length === 0,
+    agents: registry.agents,
+    issues
+  };
+}
+
+export async function validateAgentSkillTeamRuntime(projectRoot: string): Promise<AgentSkillTeamRuntimeValidation> {
+  const inspection = await inspectAgentSkillTeamRuntime(projectRoot);
+  const registry = await buildAgentSkillRuntimeRegistry(projectRoot);
+  const issues = [...registry.issues, ...validateAgentSkillTeamRuntimeInspection(inspection)];
+  return {
+    version: AGENT_SKILL_TEAM_RUNTIME_CONTRACT_VERSION,
+    valid: issues.length === 0,
+    inspection,
+    issues
+  };
+}
+
+function validateWorkflowGate(workflow: WorkflowGateContract, agentIds: Set<string>): ContractValidationIssue[] {
+  const issues: ContractValidationIssue[] = [];
+  if (workflow.requiredInputs.length === 0) {
+    issues.push(contractIssue(`${workflow.id}.requiredInputs`, 'Workflow gate has no required inputs.', 'Declare required inputs before this workflow can run.'));
+  }
+  if (workflow.requiredArtifacts.length === 0) {
+    issues.push(contractIssue(`${workflow.id}.requiredArtifacts`, 'Workflow gate has no required artifacts.', 'Declare required artifacts for workflow evidence.'));
+  }
+  for (const agentId of workflow.allowedAgents) {
+    if (!agentIds.has(agentId)) {
+      issues.push(contractIssue(`${workflow.id}.allowedAgents`, `Workflow references unknown agent ${agentId}.`, 'Add the agent to AgentRegistryContract or remove it from the workflow.'));
+    }
+  }
+  return issues;
+}
+
+function validateAgentRegistryEntry(agent: AgentRegistryEntry): ContractValidationIssue[] {
+  const issues: ContractValidationIssue[] = [];
+  if (agent.allowedStages.length === 0) {
+    issues.push(contractIssue(`${agent.id}.allowedStages`, 'Agent has no allowed stages.', 'Declare where the agent may participate.'));
+  }
+  if (agent.readBoundary.length === 0 || agent.writeBoundary.length === 0) {
+    issues.push(contractIssue(`${agent.id}.boundary`, 'Agent read/write boundary is incomplete.', 'Declare read and write boundaries.'));
+  }
+  if (agent.toolAllowlist.length === 0) {
+    issues.push(contractIssue(`${agent.id}.toolAllowlist`, 'Agent has no tool allowlist.', 'Declare permitted tool categories.'));
+  }
+  return issues;
+}
+
+function validateAgentSkillTeamRuntimeInspection(inspection: AgentSkillTeamRuntimeInspection): ContractValidationIssue[] {
+  const issues: ContractValidationIssue[] = [];
+  const profileIds = new Set(inspection.profiles.map((profile) => profile.id));
+  const capabilityIds = new Set(inspection.skillCapabilities.map((capability) => capability.id));
+  const sourceIds = new Set(inspection.capabilitySources.map((source) => source.id));
+  const modelPolicyIds = new Set(BUILT_IN_MODEL_POLICIES.map((policy) => policy.id));
+  for (const requiredProfile of ['planner', 'architect', 'implementer', 'reviewer', 'validator', 'researcher', 'orchestrator', 'security', 'domain_expert'] as AgentProfileId[]) {
+    if (!profileIds.has(requiredProfile)) {
+      issues.push(contractIssue(`profiles.${requiredProfile}`, 'Required Phase 6 profile is missing.', 'Add the profile to AgentProfileContract.'));
+    }
+  }
+  for (const source of inspection.capabilitySources) {
+    if (!source.id.trim()) {
+      issues.push(contractIssue('capabilitySources.id', 'Capability source has no id.', 'Declare a stable capability source id.'));
+    }
+    if (!source.sourceRef.trim()) {
+      issues.push(contractIssue(`${source.id}.sourceRef`, 'Capability source has no source reference.', 'Declare the source_ref before runtime inspection can cite it.'));
+    }
+    if (!source.attribution.trim()) {
+      issues.push(contractIssue(`${source.id}.attribution`, 'Capability source has no attribution.', 'Declare attribution before external material can enter the runtime registry.'));
+    }
+    if (source.permissionModel.length === 0) {
+      issues.push(contractIssue(`${source.id}.permissionModel`, 'Capability source has no permission model.', 'Declare how host/tool permissions are bounded before routing this source.'));
+    }
+    if (source.provenanceRequirements.length === 0) {
+      issues.push(contractIssue(`${source.id}.provenanceRequirements`, 'Capability source has no provenance requirements.', 'Declare source, session, artifact, or tool provenance before external output can be cited.'));
+    }
+    if (source.hostCompatibility.length === 0) {
+      issues.push(contractIssue(`${source.id}.hostCompatibility`, 'Capability source has no host compatibility declaration.', 'Declare supported, future_adapter, or unsupported host compatibility.'));
+    }
+    if (source.allowedEvidenceTypes.length === 0) {
+      issues.push(contractIssue(`${source.id}.allowedEvidenceTypes`, 'Capability source has no allowed evidence type.', 'Declare whether output is none, candidate evidence, command output, browser snapshot, design context, execution record, or external reference.'));
+    }
+    if (source.forbiddenAuthority.length === 0 || !sourceForbidsRuntimeAuthority(source)) {
+      issues.push(contractIssue(`${source.id}.forbiddenAuthority`, 'Capability source does not forbid runtime authority.', 'External sources must forbid lifecycle, completion, sync-back, ship, and permission authority.'));
+    }
+    if (!source.quarantineRequired && source.quarantineStatus !== 'not_required') {
+      issues.push(contractIssue(`${source.id}.quarantineStatus`, 'Non-quarantined source has a quarantine status.', 'Use not_required unless quarantine is required.'));
+    }
+    if (source.quarantineRequired && source.quarantineStatus === 'not_required') {
+      issues.push(contractIssue(`${source.id}.quarantineStatus`, 'Quarantined source is missing active quarantine status.', 'Use required, quarantined, or denied for external sources that require quarantine.'));
+    }
+    if ((source.quarantineRequired || source.quarantineStatus === 'quarantined' || source.quarantineStatus === 'denied') && source.reuseDecision === 'reuse_direct') {
+      issues.push(contractIssue(`${source.id}.reuseDecision`, 'Quarantined source cannot be reused directly.', 'Use adapt_via_host_adapter, borrow_mechanism, or avoid until quarantine evidence promotes the source.'));
+    }
+    if ((source.quarantineRequired || source.quarantineStatus === 'quarantined') && sourceDeclaresUnsafeAuthority(source)) {
+      issues.push(contractIssue(`${source.id}.allowedUse`, 'Quarantined source requests prompt import, direct execution, or lifecycle authority.', 'Keep external material declarative and route only through validated profiles, capabilities, and adapter mappings.'));
+    }
+    if (source.quarantineStatus === 'denied' && source.reuseDecision !== 'avoid') {
+      issues.push(contractIssue(`${source.id}.reuseDecision`, 'Denied capability source is still routable.', 'Set reuse_decision to avoid for denied or unsupported sources.'));
+    }
+  }
+  for (const capability of inspection.skillCapabilities) {
+    const registrySource = inspectionRegistrySource(inspection, 'skill_capability', capability.id);
+    if (!capability.id.trim()) {
+      issues.push(contractIssue('skillCapabilities.id', 'Capability has no id.', 'Declare a stable capability id.'));
+    }
+    if (capability.allowedStages.length === 0) {
+      issues.push(contractIssue(`${capability.id}.allowedStages`, 'Capability has no allowed stages.', 'Declare the SDD stages where this capability may be used.'));
+    }
+    if (!capability.sourceRef.trim()) {
+      issues.push(contractIssue(`${capability.id}.sourceRef`, 'Capability has no source attribution.', 'Add source_ref before routing can cite this capability.'));
+    }
+    if (registrySource?.origin === 'project_config' && capability.evidenceType === 'none') {
+      issues.push(contractIssue(`${capability.id}.evidenceType`, 'Project-declared capability has no evidence type.', 'Declare evidence_type so runtime results can be verified.'));
+    }
+    if (registrySource?.sourceId && !sourceIds.has(registrySource.sourceId)) {
+      issues.push(contractIssue(`${capability.id}.sourceRef`, `Capability references missing source ${registrySource.sourceId}.`, 'Add the capability source or update the capability source_ref.'));
+    }
+  }
+  for (const profile of inspection.profiles) {
+    if (!profile.id.trim()) {
+      issues.push(contractIssue('profiles.id', 'Profile has no id.', 'Declare a stable profile id.'));
+    }
+    if (profile.stageScope.length === 0 || profile.boundaries.length === 0) {
+      issues.push(contractIssue(`${profile.id}.boundary`, 'Profile stage scope or boundary is incomplete.', 'Declare stage scope and execution boundaries.'));
+    }
+    if (profile.toolScope.length === 0) {
+      issues.push(contractIssue(`${profile.id}.toolScope`, 'Profile has no tool scope.', 'Declare allowed tool groups before routing can project permissions.'));
+    }
+    if (profile.requiredArtifacts.length === 0) {
+      issues.push(contractIssue(`${profile.id}.requiredArtifacts`, 'Profile has no required artifacts.', 'Declare the evidence artifacts expected from this profile.'));
+    }
+    if (!modelPolicyIds.has(profile.modelPolicyId)) {
+      issues.push(contractIssue(`${profile.id}.modelPolicyId`, `Profile references unknown model policy ${profile.modelPolicyId}.`, 'Use a registered model policy id.'));
+    }
+    for (const capabilityId of profile.hostCapabilityRequirements) {
+      if (!capabilityIds.has(capabilityId) && capabilityId !== 'claude_code.host_adapter') {
+        issues.push(contractIssue(`${profile.id}.hostCapabilityRequirements`, `Profile references unknown capability ${capabilityId}.`, 'Add the capability or remove the requirement.'));
+      }
+    }
+  }
+  for (const [alias, target] of Object.entries(inspection.aliases ?? {})) {
+    if (!alias.trim() || !target.trim()) {
+      issues.push(contractIssue('agent_runtime.aliases', 'Alias declaration is incomplete.', 'Declare alias and target profile id.'));
+      continue;
+    }
+    if (!inspectionProfileTokenResolves(target, profileIds)) {
+      issues.push(contractIssue(`agent_runtime.aliases.${alias}`, `Alias points to unknown profile ${target}.`, 'Point aliases at a registered built-in or project-config profile.'));
+    }
+  }
+  for (const rule of inspection.routingRules ?? []) {
+    if (!rule.id.trim()) {
+      issues.push(contractIssue('agent_runtime.routing_rules.id', 'Routing rule has no id.', 'Declare a stable routing rule id.'));
+    }
+    if (rule.when.keywords.length === 0 && rule.when.affectedFileGlobs.length === 0) {
+      issues.push(contractIssue(`${rule.id}.when`, 'Routing rule has no match condition.', 'Declare keywords or affected_file_globs before the rule can influence routing.'));
+    }
+    if (!inspectionProfileTokenResolves(rule.preferProfile, profileIds)) {
+      issues.push(contractIssue(`${rule.id}.preferProfile`, `Routing rule prefers unknown profile ${rule.preferProfile}.`, 'Add the profile or update prefer_profile.'));
+    }
+    for (const capabilityId of rule.requireCapabilities) {
+      if (!capabilityIds.has(capabilityId)) {
+        issues.push(contractIssue(`${rule.id}.requireCapabilities`, `Routing rule requires unknown capability ${capabilityId}.`, 'Add the capability or remove it from require_capabilities.'));
+      }
+    }
+  }
+  for (const mapping of inspection.adapterMappings ?? []) {
+    if (!inspectionProfileTokenResolves(mapping.profile, profileIds)) {
+      issues.push(contractIssue(`agent_runtime.adapter_mappings.${mapping.profile}`, `Adapter mapping references unknown profile ${mapping.profile}.`, 'Map adapters only to registered profiles.'));
+    }
+    if (!mapping.hostAdapter.trim() || !mapping.projection.trim() || !mapping.permissionPolicy.trim()) {
+      issues.push(contractIssue(`agent_runtime.adapter_mappings.${mapping.profile}`, 'Adapter mapping is incomplete.', 'Declare host_adapter, projection, and permission_policy.'));
+    }
+  }
+  if (inspection.teamMode.enabled) {
+    issues.push(contractIssue('teamMode.enabled', 'Runtime inspection without task context must keep team-mode disabled.', 'Use task routing to select adaptive team-mode for a concrete task.'));
+  }
+  return issues;
+}
+
+function inspectionRegistrySource(inspection: AgentSkillTeamRuntimeInspection, kind: RuntimeRegistryEntrySource['kind'], id: string): RuntimeRegistryEntrySource | null {
+  return inspection.registrySources?.find((source) => source.kind === kind && source.id === id) ?? null;
+}
+
+function inspectionProfileTokenResolves(value: string, profileIds: Set<AgentProfileId>): boolean {
+  const normalized = normalizeAgentToken(value);
+  if ([...profileIds].some((profileId) => normalizeAgentToken(profileId) === normalized)) {
+    return true;
+  }
+  const aliasTarget = builtInProfileAliasTarget(value);
+  return aliasTarget ? profileIds.has(aliasTarget) : false;
+}
+
+function sourceDeclaresUnsafeAuthority(source: CapabilitySourceCatalogEntry): boolean {
+  return /prompt\s*(body|import)|direct\s+execution|execute\s+(third[- ]party|external)|run\s+(agent\s+)?pack|lifecycle\s+authority|completion\s+authority|unscoped\s+write|permission\s+escalation/i.test([source.allowedUse, source.rationale].join('\n'));
+}
+
+function sourceForbidsRuntimeAuthority(source: CapabilitySourceCatalogEntry): boolean {
+  const forbidden = source.forbiddenAuthority.join('\n').toLowerCase();
+  return ['lifecycle', 'stage completion', 'sync-back', 'ship', 'permission'].every((term) => forbidden.includes(term));
+}
+
+function builtInProfileAliasTarget(value: string): AgentProfileId | null {
+  const normalized = normalizeAgentToken(value);
+  if (normalized === 'scout') {
+    return 'researcher';
+  }
+  if (normalized === 'debugger') {
+    return 'implementer';
+  }
+  if (normalized === 'spec_reviewer') {
+    return 'reviewer';
+  }
+  if (normalized === 'domain') {
+    return 'domain_expert';
+  }
+  return null;
+}
+
+function normalizeAgentToken(value: string): string {
+  return value.trim().toLowerCase().replace(/[\s_-]+/g, '_');
+}

package/node_modules/@sdd-agent-platform/core/src/router/team-mode.ts

@@ -0,0 +1,170 @@
+import { TEAM_MODE_POLICY_VERSION } from '../contracts.js';
+import type { LifecycleAutonomyCeiling } from '../lifecycle/decision-gate.js';
+import type { TeamModeActivation } from './route-cache.js';
+import { BUILT_IN_DELEGATION_WAVES } from './runtime-registry.js';
+import type {
+  AgentProfileId,
+  AgentRouterCategory,
+  DelegationWavePolicy,
+  TeamModeCostClass,
+  TeamModeCostRoute,
+  TeamModeDecisionStatus,
+  TeamModePolicy,
+  TeamModeSelection
+} from './agent-runtime.js';
+import type { SddTask } from '../sdd-docs/task-parser.js';
+import { buildTaskRiskProfile } from '../task-risk-profile.js';
+import { taskAutonomyCeiling } from './risk-policy.js';
+
+export function resolveTeamModeActivation(options: { teamModeEnabled?: boolean; teamModeActivation?: TeamModeActivation }, defaultActivation: TeamModeActivation): TeamModeActivation {
+  if (options.teamModeActivation) {
+    return options.teamModeActivation;
+  }
+  if (options.teamModeEnabled === true) {
+    return 'force';
+  }
+  if (options.teamModeEnabled === false) {
+    return 'off';
+  }
+  return defaultActivation;
+}
+
+function baseTeamModePolicy(input: {
+  activation: TeamModeActivation;
+  mode: TeamModeSelection;
+  enabled: boolean;
+  decision: TeamModeDecisionStatus;
+  costClass: TeamModeCostClass;
+  reason: string;
+  costRoute?: TeamModeCostRoute;
+  downgradeReason?: string | null;
+  trustPolicyEnforced?: boolean;
+  allowedWaves?: DelegationWavePolicy[];
+  memberProfiles?: AgentProfileId[];
+  maxMembers?: number;
+  blockedReason?: string | null;
+}): TeamModePolicy {
+  const allowedWaves = input.allowedWaves ?? [];
+  const memberProfiles = (input.memberProfiles ?? [...new Set(allowedWaves.flatMap((wave) => wave.memberProfiles))]).slice(0, input.maxMembers ?? 0);
+  return {
+    version: TEAM_MODE_POLICY_VERSION,
+    enabled: input.enabled,
+    decision: input.decision,
+    mode: input.mode,
+    activation: input.activation,
+    costClass: input.costClass,
+    reason: input.reason,
+    costRoute: input.costRoute ?? 'not_applicable',
+    downgradeReason: input.downgradeReason ?? null,
+    trustPolicyEnforced: input.trustPolicyEnforced ?? true,
+    chiefProfile: 'orchestrator',
+    memberProfiles,
+    allowedWaves,
+    maxMembers: input.maxMembers ?? memberProfiles.length,
+    requireArtifacts: true,
+    blockedReason: input.blockedReason ?? null,
+    waveRecommendation: allowedWaves.map((wave) => wave.id)
+  };
+}
+
+function selectTeamWaves(ids: Array<DelegationWavePolicy['id']>): DelegationWavePolicy[] {
+  return ids.map((id) => BUILT_IN_DELEGATION_WAVES.find((wave) => wave.id === id)).filter((wave): wave is DelegationWavePolicy => Boolean(wave));
+}
+
+
+export function buildTeamModePolicy(options: { activation: TeamModeActivation; task?: SddTask | null; category?: AgentRouterCategory; risk?: string[]; autonomyCeiling?: LifecycleAutonomyCeiling; blockedReason?: string | null }): TeamModePolicy {
+  const activation = options.activation;
+  if (options.blockedReason) {
+    return baseTeamModePolicy({
+      activation,
+      mode: 'off',
+      enabled: false,
+      decision: 'blocked',
+      costClass: 'none',
+      reason: options.blockedReason,
+      blockedReason: options.blockedReason,
+      costRoute: 'blocked',
+      trustPolicyEnforced: true
+    });
+  }
+  if (activation === 'off') {
+    return baseTeamModePolicy({
+      activation,
+      mode: 'off',
+      enabled: false,
+      decision: 'disabled',
+      costClass: 'none',
+      reason: 'Team-mode automation disabled for this route.',
+      costRoute: 'not_applicable',
+      trustPolicyEnforced: true
+    });
+  }
+
+  const task = options.task ?? null;
+  const profile = buildTaskRiskProfile(task ? { ...task, risk: options.risk ?? task.risk } : null);
+  const category = options.category ?? 'planning';
+  const autonomyCeiling = options.autonomyCeiling ?? (task ? taskAutonomyCeiling(task) : 'direct_execution_allowed');
+  const highRisk = profile.riskLevel === 'high' || autonomyCeiling === 'full_sdd_with_checkpoint' || autonomyCeiling === 'research_before_implementation';
+  const reviewNeeded = category === 'implementation_review' || category === 'validation' || profile.teamRecommendation === 'review-lite';
+
+  if (profile.securitySensitive || category === 'security_research') {
+    return baseTeamModePolicy({
+      activation,
+      mode: 'security-research',
+      enabled: true,
+      decision: 'enabled',
+      costClass: 'high',
+      reason: 'Security-sensitive task automatically requires bounded security-research team evidence.',
+      costRoute: 'no_downgrade',
+      trustPolicyEnforced: true,
+      allowedWaves: selectTeamWaves(['security_research', 'validation']),
+      memberProfiles: ['security', 'reviewer', 'validator'],
+      maxMembers: 3
+    });
+  }
+
+  if (highRisk || category === 'external_research') {
+    return baseTeamModePolicy({
+      activation,
+      mode: 'hyperplan',
+      enabled: true,
+      decision: 'enabled',
+      costClass: highRisk ? 'high' : 'medium',
+      reason: profile.sourceBoundary ? 'Source-boundary or high-risk task requires adversarial planning/review evidence.' : 'High-risk or research-before-implementation task automatically requires adversarial planning/review evidence.',
+      costRoute: 'no_downgrade',
+      trustPolicyEnforced: true,
+      allowedWaves: selectTeamWaves(['hyperplan', 'implementation_review', 'validation']),
+      memberProfiles: ['architect', 'reviewer', 'security', 'validator'],
+      maxMembers: 4
+    });
+  }
+
+  if (reviewNeeded || activation === 'force') {
+    return baseTeamModePolicy({
+      activation,
+      mode: 'review-lite',
+      enabled: true,
+      decision: 'enabled',
+      costClass: 'low',
+      reason: activation === 'force' ? 'Team-mode was forced, so router selects the lowest-cost review-lite team.' : 'Task metadata indicates review or validation evidence is useful, so router selects review-lite.',
+      costRoute: activation === 'force' ? 'no_downgrade' : 'downgraded',
+      downgradeReason: activation === 'force' ? null : 'Low-cost review-lite route keeps reviewer/validator artifacts and policy-backed verify mandatory.',
+      trustPolicyEnforced: true,
+      allowedWaves: selectTeamWaves(['implementation_review', 'validation']),
+      memberProfiles: ['reviewer', 'validator'],
+      maxMembers: 2
+    });
+  }
+
+  return baseTeamModePolicy({
+    activation,
+    mode: 'off',
+    enabled: false,
+    decision: 'disabled',
+    costClass: 'none',
+    reason: 'No shared task risk profile signals require an agent team.',
+    costRoute: 'downgraded',
+    downgradeReason: 'Shared risk profile is low; artifact trust policy and policy-backed verify remain mandatory.',
+    trustPolicyEnforced: true
+  });
+}

package/node_modules/@sdd-agent-platform/core/src/router.ts

@@ -0,0 +1,4 @@
+export * from './router/agent-runtime-config.js';
+export * from './router/agent-runtime.js';
+export * from './router/route-cache.js';
+export * from './router/route-sdd-task.js';

package/node_modules/@sdd-agent-platform/core/src/run-state/artifacts.ts

@@ -0,0 +1,118 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { getEvidenceAttachmentPath, getLegacyArtifactPath, getRunRelativeArtifactPath, normalizeArtifactRootRelativePath } from '../runtime-paths.js';
+import { readRuntimeRunState, recordRuntimeArtifactPayload, recordRuntimeEvidenceAttachment, resolveRuntimeArtifactPayload, runtimeScopedId, withRuntimeStore } from '../storage/runtime-store.js';
+import { appendArtifactHashLedgerEntry } from './invocation-ledger.js';
+
+export async function writeArtifact(projectRoot: string, runId: string, artifactRootRelativePath: string, content: string): Promise<{ absolutePath: string; runRelativePath: string }> {
+  const normalized = normalizeArtifactRootRelativePath(artifactRootRelativePath);
+  const runRelativePath = getRunRelativeArtifactPath(normalized);
+  const runScope = await resolveRunScope(projectRoot, runId);
+  const contentHash = hashDocumentContent(content);
+  const physicalPayloadPath = uniquePhysicalPayloadPath(runRelativePath, runId, contentHash);
+  const absolutePath = getEvidenceAttachmentPath(projectRoot, runScope.branchSlug, physicalPayloadPath);
+  await mkdir(path.dirname(absolutePath), { recursive: true });
+  await writeFile(absolutePath, content, 'utf8');
+  await appendArtifactHashLedgerEntry(projectRoot, {
+    runId,
+    artifactPath: runRelativePath,
+    content,
+    status: 'written'
+  });
+  await recordRuntimeArtifact(projectRoot, { runId, path: runRelativePath, content, status: 'written', taskId: runScope.taskId });
+  await recordRuntimeArtifactPayload(projectRoot, {
+    payloadId: runtimeScopedId(runId, runRelativePath, contentHash),
+    runId,
+    sourceRunId: runId,
+    branchSlug: runScope.branchSlug,
+    taskId: runScope.taskId,
+    logicalRef: runRelativePath,
+    physicalPayloadPath,
+    artifactRole: artifactKind(runRelativePath),
+    digest: contentHash,
+    status: 'active',
+    payload: { logicalRef: runRelativePath, physicalPayloadPath, artifactPath: runRelativePath, status: 'written' }
+  });
+  await recordRuntimeEvidenceAttachment(projectRoot, {
+    branchSlug: runScope.branchSlug,
+    runId,
+    taskId: runScope.taskId,
+    kind: artifactKind(runRelativePath),
+    relativePath: physicalPayloadPath,
+    contentHash,
+    bytes: Buffer.byteLength(content, 'utf8'),
+    payload: { logicalRef: runRelativePath, physicalPayloadPath, status: 'written' }
+  });
+  return { absolutePath, runRelativePath };
+}
+
+export async function readArtifact(projectRoot: string, runId: string, artifactRootRelativePath: string): Promise<string> {
+  const normalized = normalizeArtifactRootRelativePath(artifactRootRelativePath);
+  const runRelativePath = getRunRelativeArtifactPath(normalized);
+  const payload = await resolveRuntimeArtifactPayload(projectRoot, runId, runRelativePath);
+  const runScope = await resolveRunScope(projectRoot, runId);
+  const evidencePath = getEvidenceAttachmentPath(projectRoot, runScope.branchSlug, payload?.physicalPayloadPath ?? runRelativePath);
+  if (payload) {
+    return readFile(evidencePath, 'utf8');
+  }
+  try {
+    return await readFile(evidencePath, 'utf8');
+  } catch {
+    return readFile(getLegacyArtifactPath(projectRoot, runId, normalized), 'utf8');
+  }
+}
+
+function uniquePhysicalPayloadPath(logicalRef: string, runId: string, digest: string): string {
+  const parsed = path.posix.parse(logicalRef.replace(/\\/g, '/'));
+  const suffix = `${runId}-${digest.slice(0, 12)}`;
+  return path.posix.join(parsed.dir, `${parsed.name}-${suffix}${parsed.ext}`);
+}
+
+export function artifactKind(artifactPath: string): string {
+  const fileName = path.posix.basename(artifactPath.replace(/\\/g, '/'));
+  if (fileName.startsWith('implement-')) {
+    return 'implement';
+  }
+  if (fileName.startsWith('review-')) {
+    return 'review';
+  }
+  if (fileName.startsWith('debug-')) {
+    return 'debug';
+  }
+  if (fileName.startsWith('test-validation-')) {
+    return 'test-validation';
+  }
+  if (fileName.startsWith('validation-')) {
+    return 'validation';
+  }
+  if (fileName.startsWith('gap-report-')) {
+    return 'gap-report';
+  }
+  if (fileName === 'sync-back-proposal.md') {
+    return 'sync-back-proposal';
+  }
+  return 'artifact';
+}
+
+async function recordRuntimeArtifact(projectRoot: string, input: { runId: string; path: string; content: string; status: string; taskId?: string | null; agent?: string | null }): Promise<void> {
+  const contentHash = hashDocumentContent(input.content);
+  const now = new Date().toISOString();
+  const payload = JSON.stringify({ path: input.path, status: input.status, taskId: input.taskId ?? null, agent: input.agent ?? null });
+  await withRuntimeStore(projectRoot, ({ db }) => {
+    db.prepare('INSERT OR REPLACE INTO artifacts (artifact_id, run_id, path, kind, task_id, agent, content_hash, bytes, status, created_at, payload_json) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)')
+      .run(runtimeScopedId(input.runId, input.path, contentHash), input.runId, input.path, artifactKind(input.path), input.taskId ?? null, input.agent ?? null, contentHash, Buffer.byteLength(input.content, 'utf8'), input.status, now, payload);
+  });
+}
+
+async function resolveRunScope(projectRoot: string, runId: string): Promise<{ branchSlug: string; taskId: string | null }> {
+  const state = await readRuntimeRunState(projectRoot, runId);
+  return {
+    branchSlug: state?.gitBranch ?? state?.partition ?? 'unscoped',
+    taskId: state?.taskId ?? state?.currentTask ?? null
+  };
+}
+
+function hashDocumentContent(raw: string): string {
+  return createHash('sha256').update(raw.replace(/\r\n/g, '\n'), 'utf8').digest('hex');
+}

package/node_modules/@sdd-agent-platform/core/src/run-state/events.ts

@@ -0,0 +1,27 @@
+
+import path from 'node:path';
+import { EVENT_LOG_CONTRACT } from '../contracts.js';
+import { getLegacyRunDir } from '../runtime-paths.js';
+
+import { importLegacyRunEventsIfNeeded, readRuntimeRunEvents, recordRuntimeEvent } from '../storage/runtime-store.js';
+import type { RuntimeEvent } from './model.js';
+
+export async function appendEvent(projectRoot: string, runId: string, event: Omit<RuntimeEvent, 'contract' | 'time'>): Promise<RuntimeEvent> {
+  const nextEvent: RuntimeEvent = {
+    contract: EVENT_LOG_CONTRACT,
+    time: new Date().toISOString(),
+    ...event
+  };
+  await recordRuntimeEvent(projectRoot, nextEvent);
+  return nextEvent;
+}
+
+export async function readRunEvents(projectRoot: string, runId: string): Promise<RuntimeEvent[]> {
+  const storedEvents = await readRuntimeRunEvents(projectRoot, runId);
+  if (storedEvents.length > 0) {
+    return storedEvents;
+  }
+  const eventPath = path.join(getLegacyRunDir(projectRoot, runId), 'events.jsonl');
+  await importLegacyRunEventsIfNeeded(projectRoot, runId, eventPath);
+  return readRuntimeRunEvents(projectRoot, runId);
+}