phasegate 0.229.0 → 0.254.0

package/scripts/harness/world-model/domain/value-objects/world-node-id.ts

@@ -0,0 +1,222 @@
+// @unit world-model
+// @layer domain
+// @work-item-id WI-287
+import { ArtifactKind } from "./artifact-kind.js";
+import { CorpusRole } from "./corpus-role.js";
+import { DeclaredKey } from "./declared-key.js";
+import { decodeWorldIdComponent, encodeWorldIdComponent, PathKey } from "./path-key.js";
+import { Sha256Digest } from "./sha256-digest.js";
+
+export type WorldNodeType =
+  | "artifact"
+  | "source-file"
+  | "fragment"
+  | "work-item"
+  | "test-reference"
+  | "explicit-claim"
+  | "constraint"
+  | "snapshot";
+
+export type TestReferenceBinding = "ac" | "file";
+export type TestReferenceType = "unit" | "it" | "scenario";
+
+export interface TestReferenceIdInput {
+  readonly storyId: string;
+  readonly acId: string;
+  readonly binding?: TestReferenceBinding;
+  readonly testType: TestReferenceType;
+  readonly filePath: PathKey;
+  readonly testName?: string;
+}
+
+export class InvalidWorldNodeIdError extends Error {
+  constructor(value: string) {
+    super(`Invalid World node ID: "${value}"`);
+    this.name = "InvalidWorldNodeIdError";
+  }
+}
+
+const assertArtifactRole = (kind: ArtifactKind, role: CorpusRole): void => {
+  const valid =
+    (kind.value === "design-document" &&
+      (role.value === "product" || role.value === "inception" || role.value === "adr")) ||
+    (kind.value === "generated-artifact" && role.value === "generated") ||
+    (kind.value === "external-declaration" && role.value === "external");
+  if (!valid) {
+    throw new InvalidWorldNodeIdError(`${kind.toString()}:${role.toString()}`);
+  }
+};
+
+const reconstruct = (candidate: WorldNodeId, source: string): WorldNodeId => {
+  if (candidate.toString() !== source) {
+    throw new InvalidWorldNodeIdError(source);
+  }
+  return candidate;
+};
+
+export class WorldNodeId {
+  readonly value: string;
+  readonly nodeType: WorldNodeType;
+
+  private constructor(value: string, nodeType: WorldNodeType) {
+    this.value = value;
+    this.nodeType = nodeType;
+    Object.freeze(this);
+  }
+
+  static artifact(kind: ArtifactKind, role: CorpusRole, path: PathKey): WorldNodeId {
+    assertArtifactRole(kind, role);
+    return new WorldNodeId(
+      `pgw:v1:artifact:${kind.toString()}:${role.toString()}:${path.toEncodedString()}`,
+      "artifact",
+    );
+  }
+
+  static sourceFile(path: PathKey): WorldNodeId {
+    return new WorldNodeId(`pgw:v1:source-file:${path.toEncodedString()}`, "source-file");
+  }
+
+  static fragment(role: CorpusRole, key: DeclaredKey): WorldNodeId {
+    return new WorldNodeId(`pgw:v1:fragment:${role.toString()}:${key.toString()}`, "fragment");
+  }
+
+  static legacyFragment(kind: ArtifactKind, role: CorpusRole, path: PathKey): WorldNodeId {
+    assertArtifactRole(kind, role);
+    return new WorldNodeId(
+      `pgw:v1:fragment:legacy:${kind.toString()}:${role.toString()}:${path.toEncodedString()}`,
+      "fragment",
+    );
+  }
+
+  static workItem(workItemId: string): WorldNodeId {
+    if (!/^WI-\d+$/.test(workItemId)) {
+      throw new InvalidWorldNodeIdError(workItemId);
+    }
+    return new WorldNodeId(`pgw:v1:work-item:${workItemId}`, "work-item");
+  }
+
+  static testReference(input: TestReferenceIdInput): WorldNodeId {
+    const binding = input.binding ?? "file";
+    if (binding !== "ac" && binding !== "file") {
+      throw new InvalidWorldNodeIdError(binding);
+    }
+    if (input.testType !== "unit" && input.testType !== "it" && input.testType !== "scenario") {
+      throw new InvalidWorldNodeIdError(input.testType);
+    }
+    const storyId = encodeWorldIdComponent(input.storyId);
+    const acId = encodeWorldIdComponent(input.acId);
+    const nameKey = input.testName === undefined ? "none" : `value:${encodeWorldIdComponent(input.testName)}`;
+    return new WorldNodeId(
+      [
+        "pgw:v1:test-reference",
+        storyId,
+        acId,
+        binding,
+        input.testType,
+        input.filePath.toEncodedString(),
+        "name",
+        nameKey,
+      ].join(":"),
+      "test-reference",
+    );
+  }
+
+  static explicitClaim(key: DeclaredKey): WorldNodeId {
+    return new WorldNodeId(`pgw:v1:explicit-claim:${key.toString()}`, "explicit-claim");
+  }
+
+  static constraint(key: DeclaredKey): WorldNodeId {
+    return new WorldNodeId(`pgw:v1:constraint:${key.toString()}`, "constraint");
+  }
+
+  static snapshot(corpusRoot: Sha256Digest): WorldNodeId {
+    return new WorldNodeId(`pgw:v1:snapshot:${corpusRoot.toString()}`, "snapshot");
+  }
+
+  static parse(value: string): WorldNodeId {
+    try {
+      let match = /^pgw:v1:artifact:([^:]+):([^:]+):(.+)$/.exec(value);
+      if (match) {
+        return reconstruct(
+          WorldNodeId.artifact(
+            ArtifactKind.parse(match[1]),
+            CorpusRole.parse(match[2]),
+            PathKey.fromEncodedString(match[3]),
+          ),
+          value,
+        );
+      }
+
+      match = /^pgw:v1:source-file:(.+)$/.exec(value);
+      if (match) {
+        return reconstruct(WorldNodeId.sourceFile(PathKey.fromEncodedString(match[1])), value);
+      }
+
+      match = /^pgw:v1:fragment:legacy:([^:]+):([^:]+):(.+)$/.exec(value);
+      if (match) {
+        return reconstruct(
+          WorldNodeId.legacyFragment(
+            ArtifactKind.parse(match[1]),
+            CorpusRole.parse(match[2]),
+            PathKey.fromEncodedString(match[3]),
+          ),
+          value,
+        );
+      }
+
+      match = /^pgw:v1:fragment:([^:]+):(.+)$/.exec(value);
+      if (match) {
+        return reconstruct(WorldNodeId.fragment(CorpusRole.parse(match[1]), DeclaredKey.create(match[2])), value);
+      }
+
+      match = /^pgw:v1:work-item:(WI-\d+)$/.exec(value);
+      if (match) {
+        return reconstruct(WorldNodeId.workItem(match[1]), value);
+      }
+
+      match = /^pgw:v1:test-reference:([^:]+):([^:]+):(ac|file):(unit|it|scenario):(.+):name:(none|value:(.*))$/.exec(
+        value,
+      );
+      if (match) {
+        const testName = match[6] === "none" ? undefined : decodeWorldIdComponent(match[7]);
+        return reconstruct(
+          WorldNodeId.testReference({
+            storyId: decodeWorldIdComponent(match[1]),
+            acId: decodeWorldIdComponent(match[2]),
+            binding: match[3] as TestReferenceBinding,
+            testType: match[4] as TestReferenceType,
+            filePath: PathKey.fromEncodedString(match[5]),
+            testName,
+          }),
+          value,
+        );
+      }
+
+      match = /^pgw:v1:explicit-claim:(.+)$/.exec(value);
+      if (match) {
+        return reconstruct(WorldNodeId.explicitClaim(DeclaredKey.create(match[1])), value);
+      }
+
+      match = /^pgw:v1:constraint:(.+)$/.exec(value);
+      if (match) {
+        return reconstruct(WorldNodeId.constraint(DeclaredKey.create(match[1])), value);
+      }
+
+      match = /^pgw:v1:snapshot:(sha256:[0-9a-f]{64})$/.exec(value);
+      if (match) {
+        return reconstruct(WorldNodeId.snapshot(Sha256Digest.create(match[1])), value);
+      }
+    } catch {
+      throw new InvalidWorldNodeIdError(value);
+    }
+    throw new InvalidWorldNodeIdError(value);
+  }
+
+  equals(other: WorldNodeId): boolean {
+    return this.value === other.value;
+  }
+
+  toString(): string {
+    return this.value;
+  }
+}

package/scripts/harness/world-model/index.ts

@@ -0,0 +1,22 @@
+// @unit world-model
+// @layer public-api
+// @work-item-id WI-291, WI-296
+
+export type {
+  WorldExtractionDiagnosticDto,
+  WorldInspectionDto,
+  WorldInventoryCountDto,
+  WorldJsonObject,
+  WorldJsonValue,
+} from "./application/dto/world-inspection-dto.js";
+export type {
+  WorldCorpusConfig,
+  WorldResolvedConfigInput,
+} from "./application/dto/world-resolved-config-input.js";
+export type { WorldModelModuleOptions } from "./composition-root.js";
+export { createWorldModelModule } from "./composition-root.js";
+export type { WorldCommandResult } from "./presentation/cli/world-command-support.js";
+export { WorldDeriveCommandHandler } from "./presentation/cli/world-derive-command-handler.js";
+export type { WorldInspectCommandResult } from "./presentation/cli/world-inspect-command-handler.js";
+export { WorldInspectCommandHandler } from "./presentation/cli/world-inspect-command-handler.js";
+export { WorldPinCommandHandler } from "./presentation/cli/world-pin-command-handler.js";

package/scripts/harness/world-model/infrastructure/adapters/adr-fact-extractor.ts

@@ -0,0 +1,27 @@
+// @unit world-model
+// @layer infrastructure
+// @work-item-id WI-289, WI-291
+
+import { CorpusRole } from "../../domain/value-objects/corpus-role.js";
+import type { DesignFactSource } from "./design-fact-extraction.js";
+import { FileSystemDesignFactScope, type MarkdownDesignFactExtractor } from "./markdown-design-fact-extractor.js";
+
+export interface AdrFactExtractorDeps {
+  readonly rootDir: string;
+  readonly markdownExtractor: MarkdownDesignFactExtractor;
+  readonly adrRoot?: string;
+}
+
+export class AdrFactExtractor extends FileSystemDesignFactScope implements DesignFactSource {
+  constructor(deps: AdrFactExtractorDeps) {
+    super({
+      rootDir: deps.rootDir,
+      relativeRoot: deps.adrRoot ?? "docs/ADR",
+      role: CorpusRole.adr(),
+      markdownExtractor: deps.markdownExtractor,
+      include: (relativePath) => relativePath.endsWith(".md"),
+      skip: () => false,
+      metadata: () => ({}),
+    });
+  }
+}

package/scripts/harness/world-model/infrastructure/adapters/assembled-world-fact-source.ts

@@ -0,0 +1,17 @@
+// @unit world-model
+// @layer infrastructure
+// @work-item-id WI-291
+
+import type { WorldFactBatch, WorldFactSourcePort } from "../../application/ports/world-fact-source-port.js";
+
+export interface WorldFactExtractorContract {
+  extract(): Promise<WorldFactBatch>;
+}
+
+export class AssembledWorldFactSource implements WorldFactSourcePort {
+  constructor(private readonly extractors: readonly WorldFactExtractorContract[]) {}
+
+  async extract(): Promise<readonly WorldFactBatch[]> {
+    return Promise.all(this.extractors.map((extractor) => extractor.extract()));
+  }
+}

package/scripts/harness/world-model/infrastructure/adapters/attestation-fact-extractor.ts

@@ -0,0 +1,288 @@
+// @unit world-model
+// @layer infrastructure
+// @work-item-id WI-290
+
+import type {
+  AttestationDocument,
+  VerifyAttestationHandler,
+  VerifyAttestationOutput,
+} from "../../../attestation/index.js";
+import { ExtractionDiagnostic } from "../../domain/entities/extraction-diagnostic.js";
+import { WorldNode } from "../../domain/entities/world-node.js";
+import type { WorldHashingPort } from "../../domain/ports/world-hashing-port.js";
+import { type CanonicalJsonObject, CanonicalJsonSerializer } from "../../domain/services/canonical-json-serializer.js";
+import { ArtifactKind } from "../../domain/value-objects/artifact-kind.js";
+import { CorpusRole } from "../../domain/value-objects/corpus-role.js";
+import {
+  assertExactKeys,
+  OwnerProjectionError,
+  projectionDiagnostic,
+  readOptionalJson,
+  requireArray,
+  requireBoolean,
+  requireObject,
+  requireString,
+} from "./json-fact-extractor-support.js";
+import type { RuntimeFactExtraction } from "./runtime-fact-extraction.js";
+
+const DEFAULT_ATTESTATION_PATH = ".harness/attestation.json";
+const SHA256 = /^sha256:[0-9a-f]{64}$/;
+const compareStrings = (left: string, right: string): number => (left < right ? -1 : left > right ? 1 : 0);
+
+export interface AttestationVerificationFacade {
+  verify(filePath: string): Promise<VerifyAttestationOutput>;
+}
+
+export class AttestationVerificationHandlerAdapter implements AttestationVerificationFacade {
+  constructor(private readonly handler: Pick<VerifyAttestationHandler, "handle">) {}
+
+  async verify(filePath: string): Promise<VerifyAttestationOutput> {
+    const result = await this.handler.handle({ file: filePath, emitJson: true });
+    const parsed = JSON.parse(result.output) as VerifyAttestationOutput;
+    if (
+      typeof parsed !== "object" ||
+      parsed === null ||
+      typeof parsed.ok !== "boolean" ||
+      typeof parsed.checks !== "object" ||
+      parsed.checks === null ||
+      !Array.isArray(parsed.mismatches)
+    ) {
+      throw new Error("public attestation verify handler returned an invalid DTO");
+    }
+    return parsed;
+  }
+}
+
+export interface AttestationFactExtractorDeps {
+  readonly rootDir: string;
+  readonly hashingPort: WorldHashingPort;
+  readonly verificationFacade: AttestationVerificationFacade;
+  readonly attestationPath?: string;
+  readonly serializer?: CanonicalJsonSerializer;
+}
+
+export class AttestationFactExtractor {
+  private readonly deps: AttestationFactExtractorDeps;
+  private readonly serializer: CanonicalJsonSerializer;
+
+  constructor(deps: AttestationFactExtractorDeps) {
+    this.deps = deps;
+    this.serializer = deps.serializer ?? new CanonicalJsonSerializer();
+  }
+
+  async extract(): Promise<RuntimeFactExtraction> {
+    const relativePath = this.deps.attestationPath ?? DEFAULT_ATTESTATION_PATH;
+    const read = await readOptionalJson(this.deps.rootDir, relativePath, "attestation");
+    if (read.state !== "present") {
+      return { nodes: [], edges: [], diagnostics: [read.diagnostic] };
+    }
+    try {
+      const document = this.parseDocument(read.value);
+      let verification: VerifyAttestationOutput;
+      try {
+        verification = await this.deps.verificationFacade.verify(relativePath);
+      } catch (error) {
+        return {
+          nodes: [],
+          edges: [],
+          diagnostics: [
+            ExtractionDiagnostic.create({
+              code: "attestation-verification-failure",
+              path: read.path,
+              payload: { message: error instanceof Error ? error.message : String(error) },
+            }),
+          ],
+        };
+      }
+      const projection = this.project(document, verification);
+      const artifact = WorldNode.artifact({
+        artifactKind: ArtifactKind.generatedArtifact(),
+        corpusRole: CorpusRole.generated(),
+        path: read.path,
+        digest: this.deps.hashingPort.sha256(this.serializer.serialize(projection)),
+        attributes: projection as unknown as CanonicalJsonObject,
+      });
+      return { nodes: [artifact], edges: [], diagnostics: [] };
+    } catch (error) {
+      return {
+        nodes: [],
+        edges: [],
+        diagnostics: [projectionDiagnostic(read.path, "attestation", error)],
+      };
+    }
+  }
+
+  private parseDocument(value: unknown): AttestationDocument {
+    const root = requireObject(value, "attestation");
+    assertExactKeys(
+      root,
+      ["schemaVersion", "predicateType", "subject", "inputs", "granularity", "acBoundScope", "metadata", "signature"],
+      "attestation",
+    );
+    const schemaVersion = requireString(root.schemaVersion, "attestation.schemaVersion");
+    if (schemaVersion !== "phasegate-attestation/v1") {
+      throw new OwnerProjectionError(
+        "unsupported-provider-schema",
+        `unsupported attestation schema: ${schemaVersion}`,
+        { schemaVersion },
+      );
+    }
+    const predicateType = requireString(root.predicateType, "attestation.predicateType");
+
+    const subject = requireObject(root.subject, "attestation.subject");
+    assertExactKeys(subject, ["command", "gateResult", "validatorSet"], "attestation.subject");
+    const command = requireString(subject.command, "attestation.subject.command");
+    const gateResult = requireString(subject.gateResult, "attestation.subject.gateResult");
+    if (gateResult !== "pass" && gateResult !== "fail") {
+      throw new OwnerProjectionError("malformed-provider-document", "attestation gateResult is invalid");
+    }
+    const validatorSet = requireArray(subject.validatorSet, "attestation.subject.validatorSet").map((raw, index) => {
+      const field = `attestation.subject.validatorSet[${index}]`;
+      const outcome = requireObject(raw, field);
+      assertExactKeys(outcome, ["validatorId", "passed", "skipped"], field);
+      return {
+        validatorId: requireString(outcome.validatorId, `${field}.validatorId`),
+        passed: requireBoolean(outcome.passed, `${field}.passed`),
+        skipped: requireBoolean(outcome.skipped, `${field}.skipped`),
+      };
+    });
+
+    const inputs = requireObject(root.inputs, "attestation.inputs");
+    assertExactKeys(inputs, ["digestAlgorithm", "sources", "inputDigest"], "attestation.inputs");
+    if (inputs.digestAlgorithm !== "sha256") {
+      throw new OwnerProjectionError("malformed-provider-document", "attestation digestAlgorithm is invalid");
+    }
+    const sources = requireArray(inputs.sources, "attestation.inputs.sources").map((raw, index) => {
+      const field = `attestation.inputs.sources[${index}]`;
+      const source = requireObject(raw, field);
+      assertExactKeys(source, ["path", "digest"], field);
+      const digest = requireString(source.digest, `${field}.digest`);
+      this.assertDigest(digest, `${field}.digest`);
+      return {
+        path: requireString(source.path, `${field}.path`),
+        digest,
+      };
+    });
+    const inputDigest = requireString(inputs.inputDigest, "attestation.inputs.inputDigest");
+    this.assertDigest(inputDigest, "attestation.inputs.inputDigest");
+
+    const granularity = requireObject(root.granularity, "attestation.granularity");
+    assertExactKeys(granularity, ["traceability"], "attestation.granularity");
+    const traceability = requireObject(granularity.traceability, "attestation.granularity.traceability");
+    assertExactKeys(
+      traceability,
+      ["validator", "level", "claim", "knownLimitations"],
+      "attestation.granularity.traceability",
+    );
+    const level = requireString(traceability.level, "attestation.granularity.traceability.level");
+    if (level !== "file" && level !== "ac") {
+      throw new OwnerProjectionError("malformed-provider-document", "attestation granularity level is invalid");
+    }
+    const knownLimitations = requireArray(
+      traceability.knownLimitations,
+      "attestation.granularity.traceability.knownLimitations",
+    ).map((item, index) => requireString(item, `attestation.granularity.traceability.knownLimitations[${index}]`));
+    const acBoundScope = requireArray(root.acBoundScope, "attestation.acBoundScope").map((item, index) =>
+      requireString(item, `attestation.acBoundScope[${index}]`),
+    );
+
+    const metadata = requireObject(root.metadata, "attestation.metadata");
+    assertExactKeys(metadata, ["producedAt", "producer", "gitCommit"], "attestation.metadata");
+    const gitCommit =
+      metadata.gitCommit === null ? null : requireString(metadata.gitCommit, "attestation.metadata.gitCommit");
+
+    const signature = requireObject(root.signature, "attestation.signature");
+    assertExactKeys(signature, ["mode", "attestationDigest", "algorithm", "keyId", "value"], "attestation.signature");
+    const mode = requireString(signature.mode, "attestation.signature.mode");
+    if (mode !== "unsigned-poc" && mode !== "signed") {
+      throw new OwnerProjectionError("malformed-provider-document", "attestation signature mode is invalid");
+    }
+    const attestationDigest = requireString(signature.attestationDigest, "attestation.signature.attestationDigest");
+    this.assertDigest(attestationDigest, "attestation.signature.attestationDigest");
+    const nullableString = (candidate: unknown, field: string): string | null =>
+      candidate === null ? null : requireString(candidate, field);
+
+    return {
+      schemaVersion,
+      predicateType,
+      subject: { command, gateResult, validatorSet },
+      inputs: {
+        digestAlgorithm: "sha256",
+        sources,
+        inputDigest,
+      },
+      granularity: {
+        traceability: {
+          validator: requireString(traceability.validator, "attestation.granularity.traceability.validator"),
+          level,
+          claim: requireString(traceability.claim, "attestation.granularity.traceability.claim"),
+          knownLimitations,
+        },
+      },
+      acBoundScope,
+      metadata: {
+        producedAt: requireString(metadata.producedAt, "attestation.metadata.producedAt"),
+        producer: requireString(metadata.producer, "attestation.metadata.producer"),
+        gitCommit,
+      },
+      signature: {
+        mode,
+        attestationDigest,
+        algorithm: nullableString(signature.algorithm, "attestation.signature.algorithm"),
+        keyId: nullableString(signature.keyId, "attestation.signature.keyId"),
+        value: nullableString(signature.value, "attestation.signature.value"),
+      },
+    };
+  }
+
+  private project(document: AttestationDocument, verification: VerifyAttestationOutput): CanonicalJsonObject {
+    return {
+      schemaVersion: document.schemaVersion,
+      predicateType: document.predicateType,
+      subject: {
+        command: document.subject.command,
+        gateResult: document.subject.gateResult,
+        validatorSet: [...document.subject.validatorSet]
+          .sort((left, right) => compareStrings(left.validatorId, right.validatorId))
+          .map((outcome) => ({
+            validatorId: outcome.validatorId,
+            passed: outcome.passed,
+            skipped: outcome.skipped,
+          })),
+      },
+      inputs: {
+        digestAlgorithm: document.inputs.digestAlgorithm,
+        sources: document.inputs.sources
+          .filter((source) => source.path !== "git:HEAD")
+          .map((source) => ({ path: source.path, digest: source.digest }))
+          .sort((left, right) => compareStrings(left.path, right.path)),
+      },
+      granularity: {
+        traceability: {
+          validator: document.granularity.traceability.validator,
+          level: document.granularity.traceability.level,
+          claim: document.granularity.traceability.claim,
+          knownLimitations: [...document.granularity.traceability.knownLimitations].sort(compareStrings),
+        },
+      },
+      acBoundScope: [...document.acBoundScope].sort(compareStrings),
+      verificationStatus: {
+        ok: verification.ok,
+        checks: {
+          schema: verification.checks.schema,
+          mode: verification.checks.mode,
+          attestationDigest: verification.checks.attestationDigest,
+          inputHashes: verification.checks.inputHashes,
+          granularity: verification.checks.granularity,
+          acBoundScope: verification.checks.acBoundScope,
+        },
+      },
+    };
+  }
+
+  private assertDigest(value: string, field: string): void {
+    if (!SHA256.test(value)) {
+      throw new OwnerProjectionError("malformed-provider-document", `${field} is not SHA-256`, { field });
+    }
+  }
+}

package/scripts/harness/world-model/infrastructure/adapters/attestation-sha256-world-hashing-adapter.ts

@@ -0,0 +1,15 @@
+// @unit world-model
+// @layer infrastructure
+// @work-item-id WI-291
+
+import type { Sha256Capability } from "../../../attestation/index.js";
+import type { WorldHashingPort } from "../../domain/ports/world-hashing-port.js";
+import { Sha256Digest } from "../../domain/value-objects/sha256-digest.js";
+
+export class AttestationSha256WorldHashingAdapter implements WorldHashingPort {
+  constructor(private readonly capability: Sha256Capability) {}
+
+  sha256(bytes: Uint8Array): Sha256Digest {
+    return Sha256Digest.create(this.capability.hashBytes(bytes));
+  }
+}

package/scripts/harness/world-model/infrastructure/adapters/composite-design-fact-source.ts

@@ -0,0 +1,23 @@
+// @unit world-model
+// @layer infrastructure
+// @work-item-id WI-291
+
+import type {
+  DesignFactCandidateExtraction,
+  DesignFactSource,
+  TraceabilityDesignFactIndex,
+} from "./design-fact-extraction.js";
+
+export class CompositeDesignFactSource implements DesignFactSource {
+  constructor(private readonly sources: readonly DesignFactSource[]) {}
+
+  async extract(ownerIndex: TraceabilityDesignFactIndex): Promise<DesignFactCandidateExtraction> {
+    const results = await Promise.all(this.sources.map((source) => source.extract(ownerIndex)));
+    return {
+      nodeCandidates: results.flatMap((result) => result.nodeCandidates),
+      workItemReferences: results.flatMap((result) => result.workItemReferences),
+      reflectionReferences: results.flatMap((result) => result.reflectionReferences),
+      diagnostics: results.flatMap((result) => result.diagnostics),
+    };
+  }
+}