@moretea-labs/forge 1.8.0 → 1.8.2

package/src/runtime/control-plane/workspace/project-onboarding.ts

@@ -0,0 +1,80 @@
+import { ensureForgeInstanceIdentity } from '../../../../packages/kernel/identity/api/index';
+import type { RepositoryRecord } from '../../../cli/repositories/types';
+import {
+  normalizeRemoteUrl,
+  portableProjectSourceFingerprint,
+  stablePortableProjectId,
+} from '../../../cli/repositories/identity';
+import { loadProjectEngineeringContract } from '../../context/project-engineering-contract';
+import {
+  ensureProjectWorkspaceBinding,
+  type EnsureProjectWorkspaceBindingResult,
+} from './workspace-store';
+
+export type RepositoryProjectOnboardingResult =
+  | {
+      status: 'bound';
+      projectId: string;
+      workspaceId: string;
+      forgeInstanceId: string;
+      identitySource: 'project_contract' | 'canonical_remote';
+      createdWorkspace: boolean;
+      createdProject: boolean;
+      createdPlacement: boolean;
+    }
+  | {
+      status: 'unbound';
+      reason: 'portable_project_identity_unavailable';
+    };
+
+/**
+ * Bind a repository to portable Project/Workspace semantics only when Work
+ * admission actually treats it as a project. Repository registration remains a
+ * node-local placement concern and never creates semantic identity by itself.
+ */
+export function ensureRepositoryProjectOnboarding(input: {
+  controllerHome: string;
+  repository: RepositoryRecord;
+  sourceRevision?: string;
+}): RepositoryProjectOnboardingResult {
+  const contract = loadProjectEngineeringContract({
+    repoRoot: input.repository.canonicalRoot,
+    sourceRevision: input.sourceRevision?.trim() || 'working-tree',
+  });
+  const declaredProjectId = contract.status === 'ready' ? contract.contract.projectId : undefined;
+  const canonicalRemote = input.repository.canonicalRemote ?? normalizeRemoteUrl(input.repository.remoteUrl);
+  if (!declaredProjectId && !canonicalRemote) {
+    return { status: 'unbound', reason: 'portable_project_identity_unavailable' };
+  }
+
+  const sourceFingerprint = canonicalRemote
+    ? portableProjectSourceFingerprint(canonicalRemote)
+    : undefined;
+  const fallbackProjectId = canonicalRemote
+    ? stablePortableProjectId(canonicalRemote)
+    : undefined;
+  const instance = ensureForgeInstanceIdentity({
+    controllerHome: input.controllerHome,
+    label: 'Forge Runtime',
+  });
+  const binding: EnsureProjectWorkspaceBindingResult = ensureProjectWorkspaceBinding({
+    controllerHome: input.controllerHome,
+    preferredProjectId: declaredProjectId,
+    fallbackProjectId,
+    sourceFingerprint,
+    displayName: input.repository.displayName,
+    forgeInstanceId: instance.instanceId,
+    repositoryId: input.repository.repoId,
+  });
+
+  return {
+    status: 'bound',
+    projectId: binding.project.projectId,
+    workspaceId: binding.project.workspaceId,
+    forgeInstanceId: binding.placement.forgeInstanceId,
+    identitySource: declaredProjectId ? 'project_contract' : 'canonical_remote',
+    createdWorkspace: binding.createdWorkspace,
+    createdProject: binding.createdProject,
+    createdPlacement: binding.createdPlacement,
+  };
+}

package/src/runtime/control-plane/workspace/semantic-sync-service.ts

@@ -18,6 +18,7 @@ import { readForgeInstanceIdentity } from '../../../../packages/kernel/identity/
 import type { WorkContract } from '../../../../packages/kernel/work/api/index';
 import { semanticScopeRefForWork } from '../../../../packages/kernel/work/api/index';
 import type { PlanContract } from '../facade/types';
+import { SEMANTIC_SCOPE_KEY } from '../../../cli/repositories/controller-home';
 import type { Requirement } from '../persistence/requirement-store';
 import {
   ControlPlaneConflictError,
@@ -90,13 +91,15 @@ export interface WorkSemanticView {
   semanticScope: ReturnType<typeof semanticScopeRefForWork>;
   objective: string;
   acceptanceCriteria: string[];
-  status: WorkContract['status'];
+  state: WorkContract['semanticState'];
   phase: WorkContract['phase'];
   workKind: WorkContract['workKind'];
   lifecycleRole?: WorkContract['lifecycleRole'];
   requirementId?: string;
   planId?: string;
   planStepId?: string;
+  semanticParentWorkId?: string;
+  dependsOnWorkIds?: string[];
   predecessorWorkId?: string;
   supersedes?: string[];
   supersededBy?: string;
@@ -199,13 +202,15 @@ export function projectWorkSemantic(work: WorkContract): WorkSemanticView {
     semanticScope: semanticScopeRefForWork(work),
     objective: work.objective,
     acceptanceCriteria: [...work.acceptanceCriteria],
-    status: work.status,
+    state: work.semanticState,
     phase: work.phase,
     workKind: work.workKind,
     ...(work.lifecycleRole ? { lifecycleRole: work.lifecycleRole } : {}),
     ...(work.requirementId ? { requirementId: work.requirementId } : {}),
     ...(work.planId ? { planId: work.planId } : {}),
     ...(work.planStepId ? { planStepId: work.planStepId } : {}),
+    ...(work.semanticParentWorkId ? { semanticParentWorkId: work.semanticParentWorkId } : {}),
+    ...(work.dependsOnWorkIds?.length ? { dependsOnWorkIds: [...work.dependsOnWorkIds] } : {}),
     ...(work.predecessorWorkId ? { predecessorWorkId: work.predecessorWorkId } : {}),
     ...(work.supersedes ? { supersedes: [...work.supersedes] } : {}),
     ...(work.supersededBy ? { supersededBy: work.supersededBy } : {}),
@@ -311,9 +316,18 @@ function localRecordWithinTransaction(database: SqliteDatabase, input: { kind: S
   if (input.kind === 'workspace') return readControlPlaneRecordWithinTransaction(database, WORKSPACE_SEMANTIC_NAMESPACE, CONTROLLER_SCOPE, input.id);
   if (input.kind === 'project') return readControlPlaneRecordWithinTransaction(database, PROJECT_SEMANTIC_NAMESPACE, input.workspaceId, input.id);
   if (input.kind === 'requirement') return readControlPlaneRecordWithinTransaction(database, 'requirement', CONTROLLER_SCOPE, input.id);
-  if (!input.repositoryId) return undefined;
-  if (input.kind === 'plan') return readControlPlaneRecordWithinTransaction(database, 'plan_contract', input.repositoryId, input.id);
-  if (input.kind === 'work') return readControlPlaneRecordWithinTransaction(database, 'work_contract', input.repositoryId, input.id);
+  if (input.kind === 'plan') {
+    const semantic = readControlPlaneRecordWithinTransaction(database, 'plan_contract', SEMANTIC_SCOPE_KEY, input.id);
+    return semantic ?? (input.repositoryId
+      ? readControlPlaneRecordWithinTransaction(database, 'plan_contract', input.repositoryId, input.id)
+      : undefined);
+  }
+  if (input.kind === 'work') {
+    const semantic = readControlPlaneRecordWithinTransaction(database, 'work_contract', SEMANTIC_SCOPE_KEY, input.id);
+    return semantic ?? (input.repositoryId
+      ? readControlPlaneRecordWithinTransaction(database, 'work_contract', input.repositoryId, input.id)
+      : undefined);
+  }
   return undefined;
 }
 

package/src/runtime/control-plane/workspace/workspace-store.ts

@@ -2,8 +2,12 @@ import type { ProjectIdentity, ProjectPlacement, WorkspaceIdentity } from '../..
 import { projectIdentity, projectPlacement, workspaceIdentity } from '../../../../packages/kernel/identity/api/index';
 import {
   listControlPlaneRecords,
+  listControlPlaneRecordsWithinTransaction,
   readControlPlaneRecord,
+  readControlPlaneRecordWithinTransaction,
+  withControlPlaneTransaction,
   writeControlPlaneRecord,
+  writeControlPlaneRecordWithinTransaction,
   type ControlPlaneRecord,
 } from '../persistence/sqlite-store';
 
@@ -12,6 +16,30 @@ export const PROJECT_SEMANTIC_NAMESPACE = 'project_semantic';
 export const PROJECT_PLACEMENT_NAMESPACE = 'project_placement';
 const CONTROLLER_SCOPE = 'controller';
 
+export const DEFAULT_PERSONAL_WORKSPACE_ID = 'workspace-personal';
+export const DEFAULT_PERSONAL_WORKSPACE_TITLE = 'Personal workspace';
+
+export interface EnsureProjectWorkspaceBindingInput {
+  controllerHome: string;
+  preferredProjectId?: string;
+  fallbackProjectId?: string;
+  sourceFingerprint?: string;
+  displayName: string;
+  forgeInstanceId: string;
+  repositoryId: string;
+  defaultWorkspaceId?: string;
+  defaultWorkspaceTitle?: string;
+}
+
+export interface EnsureProjectWorkspaceBindingResult {
+  workspace: WorkspaceIdentity;
+  project: ProjectIdentity;
+  placement: ProjectPlacement;
+  createdWorkspace: boolean;
+  createdProject: boolean;
+  createdPlacement: boolean;
+}
+
 export function writeWorkspaceIdentity(input: { controllerHome: string; value: Omit<WorkspaceIdentity, 'schemaVersion'> | WorkspaceIdentity; expectedRevision?: number | null }): ControlPlaneRecord<WorkspaceIdentity> {
   const value = workspaceIdentity(input.value);
   return writeControlPlaneRecord(input.controllerHome, {
@@ -58,6 +86,147 @@ export function readProjectPlacement(controllerHome: string, forgeInstanceId: st
   return readControlPlaneRecord(controllerHome, PROJECT_PLACEMENT_NAMESPACE, forgeInstanceId.trim(), projectId.trim());
 }
 
+export function ensureProjectWorkspaceBinding(input: EnsureProjectWorkspaceBindingInput): EnsureProjectWorkspaceBindingResult {
+  const preferredProjectId = input.preferredProjectId?.trim();
+  const fallbackProjectId = input.fallbackProjectId?.trim();
+  const candidateProjectId = preferredProjectId || fallbackProjectId;
+  if (!candidateProjectId) throw new Error('PROJECT_PORTABLE_IDENTITY_REQUIRED');
+  const sourceFingerprint = input.sourceFingerprint?.trim().toLowerCase();
+  const displayName = input.displayName.trim();
+  if (!displayName) throw new Error('PROJECT_DISPLAY_NAME_INVALID');
+  const defaultWorkspaceId = input.defaultWorkspaceId?.trim() || DEFAULT_PERSONAL_WORKSPACE_ID;
+  const defaultWorkspaceTitle = input.defaultWorkspaceTitle?.trim() || DEFAULT_PERSONAL_WORKSPACE_TITLE;
+
+  return withControlPlaneTransaction(input.controllerHome, (database) => {
+    const projects = listControlPlaneRecordsWithinTransaction<ProjectIdentity>(database, {
+      namespace: PROJECT_SEMANTIC_NAMESPACE,
+      limit: 1000,
+    });
+    if (projects.length >= 1000) throw new Error('PROJECT_IDENTITY_LOOKUP_LIMIT');
+
+    const exactMatches = projects.filter(({ value }) => value.projectId === candidateProjectId);
+    if (exactMatches.length > 1) throw new Error(`PROJECT_IDENTITY_AMBIGUOUS: ${candidateProjectId}`);
+    const sourceMatches = sourceFingerprint
+      ? projects.filter(({ value }) => value.sourceFingerprint === sourceFingerprint)
+      : [];
+    if (sourceMatches.length > 1) throw new Error('PROJECT_SOURCE_IDENTITY_AMBIGUOUS');
+
+    const exact = exactMatches[0]?.value;
+    const sameSource = sourceMatches[0]?.value;
+    if (exact && sameSource && exact.projectId !== sameSource.projectId) {
+      throw new Error(`PROJECT_IDENTITY_SOURCE_ALIAS_CONFLICT: project=${exact.projectId} source_project=${sameSource.projectId}`);
+    }
+    if (preferredProjectId && sameSource && sameSource.projectId !== preferredProjectId) {
+      throw new Error(`PROJECT_IDENTITY_SOURCE_ALIAS_CONFLICT: declared=${preferredProjectId} existing=${sameSource.projectId}`);
+    }
+
+    const existingProject = exact ?? sameSource;
+    if (existingProject?.sourceFingerprint && sourceFingerprint && existingProject.sourceFingerprint !== sourceFingerprint) {
+      throw new Error(`PROJECT_IDENTITY_SOURCE_MISMATCH: ${existingProject.projectId}`);
+    }
+    if (preferredProjectId && existingProject && existingProject.projectId !== preferredProjectId) {
+      throw new Error(`PROJECT_IDENTITY_DECLARATION_MISMATCH: declared=${preferredProjectId} existing=${existingProject.projectId}`);
+    }
+
+    const projectId = existingProject?.projectId ?? candidateProjectId;
+    const workspaceId = existingProject?.workspaceId ?? defaultWorkspaceId;
+    let workspace = readControlPlaneRecordWithinTransaction<WorkspaceIdentity>(
+      database,
+      WORKSPACE_SEMANTIC_NAMESPACE,
+      CONTROLLER_SCOPE,
+      workspaceId,
+    );
+    let createdWorkspace = false;
+    if (!workspace) {
+      if (existingProject) throw new Error(`PROJECT_WORKSPACE_IDENTITY_UNRESOLVED: ${workspaceId}`);
+      const value = workspaceIdentity({ workspaceId, title: defaultWorkspaceTitle });
+      workspace = writeControlPlaneRecordWithinTransaction(database, {
+        namespace: WORKSPACE_SEMANTIC_NAMESPACE,
+        scope: CONTROLLER_SCOPE,
+        key: value.workspaceId,
+        schemaVersion: 1,
+        value,
+        action: 'workspace_semantic_onboard',
+        expectedRevision: null,
+      });
+      createdWorkspace = true;
+    }
+
+    let projectRecord = existingProject
+      ? projects.find((entry) => entry.value.workspaceId === existingProject.workspaceId && entry.value.projectId === existingProject.projectId)
+      : undefined;
+    let createdProject = false;
+    if (!projectRecord) {
+      const value = projectIdentity({
+        projectId,
+        workspaceId,
+        displayName,
+        ...(sourceFingerprint ? { sourceFingerprint } : {}),
+      });
+      projectRecord = writeControlPlaneRecordWithinTransaction(database, {
+        namespace: PROJECT_SEMANTIC_NAMESPACE,
+        scope: workspaceId,
+        key: value.projectId,
+        schemaVersion: 1,
+        value,
+        action: 'project_semantic_onboard',
+        expectedRevision: null,
+      });
+      createdProject = true;
+    }
+
+    const placements = listControlPlaneRecordsWithinTransaction<ProjectPlacement>(database, {
+      namespace: PROJECT_PLACEMENT_NAMESPACE,
+      scope: input.forgeInstanceId,
+      limit: 1000,
+    });
+    if (placements.length >= 1000) throw new Error('PROJECT_PLACEMENT_LOOKUP_LIMIT');
+    const repositoryPlacements = placements.filter(({ value }) => value.repositoryId === input.repositoryId);
+    if (repositoryPlacements.length > 1) throw new Error('PROJECT_REPOSITORY_PLACEMENT_AMBIGUOUS');
+    const repositoryPlacement = repositoryPlacements[0]?.value;
+    if (repositoryPlacement && repositoryPlacement.projectId !== projectId) {
+      throw new Error(`PROJECT_REPOSITORY_ALREADY_BOUND: repository=${input.repositoryId} existing=${repositoryPlacement.projectId} requested=${projectId}`);
+    }
+
+    let placementRecord = readControlPlaneRecordWithinTransaction<ProjectPlacement>(
+      database,
+      PROJECT_PLACEMENT_NAMESPACE,
+      input.forgeInstanceId,
+      projectId,
+    );
+    if (placementRecord && placementRecord.value.repositoryId !== input.repositoryId) {
+      throw new Error(`PROJECT_PLACEMENT_REPOSITORY_CONFLICT: project=${projectId} existing=${placementRecord.value.repositoryId} requested=${input.repositoryId}`);
+    }
+    let createdPlacement = false;
+    if (!placementRecord) {
+      const value = projectPlacement({
+        projectId,
+        forgeInstanceId: input.forgeInstanceId,
+        repositoryId: input.repositoryId,
+      });
+      placementRecord = writeControlPlaneRecordWithinTransaction(database, {
+        namespace: PROJECT_PLACEMENT_NAMESPACE,
+        scope: input.forgeInstanceId,
+        key: projectId,
+        schemaVersion: 1,
+        value,
+        action: 'project_placement_onboard',
+        expectedRevision: null,
+      });
+      createdPlacement = true;
+    }
+
+    return {
+      workspace: workspace.value,
+      project: projectRecord.value,
+      placement: placementRecord.value,
+      createdWorkspace,
+      createdProject,
+      createdPlacement,
+    };
+  });
+}
+
 /** Resolve semantic project through current placement; never derive identity from a path. */
 export function resolveProjectForRepositoryPlacement(input: {
   controllerHome: string; forgeInstanceId: string; repositoryId: string; checkoutId?: string; projectId?: string;