phasegate 0.222.0 → 0.254.0

package/scripts/harness/world-model/domain/entities/extraction-diagnostic.ts

@@ -0,0 +1,60 @@
+// @unit world-model
+// @layer domain
+// @work-item-id WI-287
+import type { CanonicalJsonObject } from "../services/canonical-json-serializer.js";
+import type { PathKey } from "../value-objects/path-key.js";
+import type { WorldNodeId } from "../value-objects/world-node-id.js";
+
+const DIAGNOSTIC_CODE_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+
+export interface ExtractionDiagnosticProps {
+  readonly code: string;
+  readonly nodeId?: WorldNodeId;
+  readonly path?: PathKey;
+  readonly line?: number;
+  readonly payload?: CanonicalJsonObject;
+}
+
+export class InvalidExtractionDiagnosticError extends Error {
+  constructor(message: string) {
+    super(`Invalid World extraction diagnostic: ${message}`);
+    this.name = "InvalidExtractionDiagnosticError";
+  }
+}
+
+export class ExtractionDiagnostic {
+  readonly code: string;
+  readonly nodeId?: WorldNodeId;
+  readonly path?: PathKey;
+  readonly line?: number;
+  readonly payload: CanonicalJsonObject;
+
+  private constructor(props: ExtractionDiagnosticProps) {
+    this.code = props.code;
+    this.nodeId = props.nodeId;
+    this.path = props.path;
+    this.line = props.line;
+    this.payload = Object.freeze({ ...(props.payload ?? {}) });
+    Object.freeze(this);
+  }
+
+  static create(props: ExtractionDiagnosticProps): ExtractionDiagnostic {
+    if (!DIAGNOSTIC_CODE_PATTERN.test(props.code)) {
+      throw new InvalidExtractionDiagnosticError(`invalid code "${props.code}"`);
+    }
+    if (props.line !== undefined && (!Number.isInteger(props.line) || props.line < 1)) {
+      throw new InvalidExtractionDiagnosticError(`invalid line "${props.line}"`);
+    }
+    return new ExtractionDiagnostic(props);
+  }
+
+  toCanonicalValue(): CanonicalJsonObject {
+    return {
+      code: this.code,
+      line: this.line ?? null,
+      nodeId: this.nodeId?.toString() ?? null,
+      pathKey: this.path?.toString() ?? null,
+      payload: this.payload,
+    };
+  }
+}

package/scripts/harness/world-model/domain/entities/snapshot.ts

@@ -0,0 +1,75 @@
+// @unit world-model
+// @layer domain
+// @work-item-id WI-287
+
+import type { EvaluationId } from "../value-objects/evaluation-id.js";
+import type { Sha256Digest } from "../value-objects/sha256-digest.js";
+import { WorldNodeId } from "../value-objects/world-node-id.js";
+import type { Edge } from "./edge.js";
+import type { ExtractionDiagnostic } from "./extraction-diagnostic.js";
+import type { WorldNode } from "./world-node.js";
+
+export interface SnapshotProps {
+  readonly schemaVersion: string;
+  readonly extractorVersion: string;
+  readonly corpusConfigDigest: Sha256Digest;
+  readonly nodes: readonly WorldNode[];
+  readonly edges: readonly Edge[];
+  readonly extractionDiagnostics: readonly ExtractionDiagnostic[];
+  readonly corpusRoot: Sha256Digest;
+  readonly canonicalBytes: Uint8Array;
+  readonly constraintRoot?: Sha256Digest;
+  readonly evaluationId?: EvaluationId;
+}
+
+export class Snapshot {
+  readonly id: WorldNodeId;
+  readonly schemaVersion: string;
+  readonly extractorVersion: string;
+  readonly corpusConfigDigest: Sha256Digest;
+  readonly nodes: readonly WorldNode[];
+  readonly edges: readonly Edge[];
+  readonly extractionDiagnostics: readonly ExtractionDiagnostic[];
+  readonly corpusRoot: Sha256Digest;
+  readonly constraintRoot?: Sha256Digest;
+  readonly evaluationId?: EvaluationId;
+  private readonly canonicalBytesValue: Uint8Array;
+
+  private constructor(props: SnapshotProps) {
+    this.id = WorldNodeId.snapshot(props.corpusRoot);
+    this.schemaVersion = props.schemaVersion;
+    this.extractorVersion = props.extractorVersion;
+    this.corpusConfigDigest = props.corpusConfigDigest;
+    this.nodes = Object.freeze([...props.nodes]);
+    this.edges = Object.freeze([...props.edges]);
+    this.extractionDiagnostics = Object.freeze([...props.extractionDiagnostics]);
+    this.corpusRoot = props.corpusRoot;
+    this.canonicalBytesValue = Uint8Array.from(props.canonicalBytes);
+    this.constraintRoot = props.constraintRoot;
+    this.evaluationId = props.evaluationId;
+    Object.freeze(this);
+  }
+
+  static create(props: SnapshotProps): Snapshot {
+    return new Snapshot(props);
+  }
+
+  get canonicalBytes(): Uint8Array {
+    return Uint8Array.from(this.canonicalBytesValue);
+  }
+
+  withEvaluationRoots(constraintRoot: Sha256Digest, evaluationId: EvaluationId): Snapshot {
+    return new Snapshot({
+      schemaVersion: this.schemaVersion,
+      extractorVersion: this.extractorVersion,
+      corpusConfigDigest: this.corpusConfigDigest,
+      nodes: this.nodes,
+      edges: this.edges,
+      extractionDiagnostics: this.extractionDiagnostics,
+      corpusRoot: this.corpusRoot,
+      canonicalBytes: this.canonicalBytes,
+      constraintRoot,
+      evaluationId,
+    });
+  }
+}

package/scripts/harness/world-model/domain/entities/world-node.ts

@@ -0,0 +1,210 @@
+// @unit world-model
+// @layer domain
+// @work-item-id WI-287, WI-290
+import type { CanonicalJsonObject } from "../services/canonical-json-serializer.js";
+import type { ArtifactKind } from "../value-objects/artifact-kind.js";
+import type { CorpusRole } from "../value-objects/corpus-role.js";
+import type { DeclaredKey } from "../value-objects/declared-key.js";
+import type { PathKey } from "../value-objects/path-key.js";
+import type { Sha256Digest } from "../value-objects/sha256-digest.js";
+import { type TestReferenceBinding, type TestReferenceType, WorldNodeId } from "../value-objects/world-node-id.js";
+
+export type WorldNodeProjection =
+  | {
+      readonly type: "artifact";
+      readonly artifactKind: string;
+      readonly corpusRole: string;
+      readonly pathKey: string;
+    }
+  | { readonly type: "source-file"; readonly pathKey: string }
+  | {
+      readonly type: "fragment";
+      readonly identityMode: "explicit" | "legacy-whole-file";
+      readonly corpusRole: string;
+      readonly artifactId: string;
+    }
+  | { readonly type: "work-item"; readonly providerId: string }
+  | {
+      readonly type: "test-reference";
+      readonly storyId: string;
+      readonly acId: string;
+      readonly binding: TestReferenceBinding;
+      readonly testType: TestReferenceType;
+      readonly filePath: string;
+      readonly testName: string | null;
+    };
+
+interface CommonNodeProps {
+  readonly digest: Sha256Digest;
+  readonly attributes?: CanonicalJsonObject;
+}
+
+export interface ArtifactNodeProps extends CommonNodeProps {
+  readonly artifactKind: ArtifactKind;
+  readonly corpusRole: CorpusRole;
+  readonly path: PathKey;
+}
+
+export interface SourceFileNodeProps extends CommonNodeProps {
+  readonly path: PathKey;
+}
+
+export interface ExplicitFragmentNodeProps extends CommonNodeProps {
+  readonly corpusRole: CorpusRole;
+  readonly declaredKey: DeclaredKey;
+  readonly artifactId: WorldNodeId;
+}
+
+export interface LegacyFragmentNodeProps extends CommonNodeProps {
+  readonly artifactKind: ArtifactKind;
+  readonly corpusRole: CorpusRole;
+  readonly path: PathKey;
+  readonly artifactId: WorldNodeId;
+}
+
+export interface WorkItemNodeProps extends CommonNodeProps {
+  readonly workItemId: string;
+}
+
+export interface TestReferenceNodeProps extends CommonNodeProps {
+  readonly storyId: string;
+  readonly acId: string;
+  readonly binding?: TestReferenceBinding;
+  readonly testType: TestReferenceType;
+  readonly filePath: PathKey;
+  readonly testName?: string;
+}
+
+export class InvalidWorldNodeError extends Error {
+  constructor(message: string) {
+    super(`Invalid World node: ${message}`);
+    this.name = "InvalidWorldNodeError";
+  }
+}
+
+export class WorldNode {
+  readonly id: WorldNodeId;
+  readonly contentDigest: Sha256Digest;
+  readonly projection: WorldNodeProjection;
+  readonly attributes: CanonicalJsonObject;
+
+  private constructor(
+    id: WorldNodeId,
+    contentDigest: Sha256Digest,
+    projection: WorldNodeProjection,
+    attributes?: CanonicalJsonObject,
+  ) {
+    this.id = id;
+    this.contentDigest = contentDigest;
+    this.projection = Object.freeze({ ...projection });
+    this.attributes = Object.freeze({ ...(attributes ?? {}) });
+    Object.freeze(this);
+  }
+
+  static artifact(props: ArtifactNodeProps): WorldNode {
+    const id = WorldNodeId.artifact(props.artifactKind, props.corpusRole, props.path);
+    return new WorldNode(
+      id,
+      props.digest,
+      {
+        type: "artifact",
+        artifactKind: props.artifactKind.toString(),
+        corpusRole: props.corpusRole.toString(),
+        pathKey: props.path.toString(),
+      },
+      props.attributes,
+    );
+  }
+
+  static sourceFile(props: SourceFileNodeProps): WorldNode {
+    return new WorldNode(
+      WorldNodeId.sourceFile(props.path),
+      props.digest,
+      { type: "source-file", pathKey: props.path.toString() },
+      props.attributes,
+    );
+  }
+
+  static explicitFragment(props: ExplicitFragmentNodeProps): WorldNode {
+    if (props.artifactId.nodeType !== "artifact") {
+      throw new InvalidWorldNodeError("explicit Fragment parent must be an Artifact");
+    }
+    const parentRole = /^pgw:v1:artifact:[^:]+:([^:]+):/.exec(props.artifactId.toString())?.[1];
+    if (parentRole !== props.corpusRole.toString()) {
+      throw new InvalidWorldNodeError("explicit Fragment corpus role must match its parent Artifact");
+    }
+    return new WorldNode(
+      WorldNodeId.fragment(props.corpusRole, props.declaredKey),
+      props.digest,
+      {
+        type: "fragment",
+        identityMode: "explicit",
+        corpusRole: props.corpusRole.toString(),
+        artifactId: props.artifactId.toString(),
+      },
+      props.attributes,
+    );
+  }
+
+  static legacyFragment(props: LegacyFragmentNodeProps): WorldNode {
+    const expectedArtifactId = WorldNodeId.artifact(props.artifactKind, props.corpusRole, props.path);
+    if (!props.artifactId.equals(expectedArtifactId)) {
+      throw new InvalidWorldNodeError("legacy Fragment parent does not match its artifact tuple");
+    }
+    return new WorldNode(
+      WorldNodeId.legacyFragment(props.artifactKind, props.corpusRole, props.path),
+      props.digest,
+      {
+        type: "fragment",
+        identityMode: "legacy-whole-file",
+        corpusRole: props.corpusRole.toString(),
+        artifactId: props.artifactId.toString(),
+      },
+      props.attributes,
+    );
+  }
+
+  static workItem(props: WorkItemNodeProps): WorldNode {
+    return new WorldNode(
+      WorldNodeId.workItem(props.workItemId),
+      props.digest,
+      { type: "work-item", providerId: props.workItemId },
+      props.attributes,
+    );
+  }
+
+  static testReference(props: TestReferenceNodeProps): WorldNode {
+    const binding = props.binding ?? "file";
+    return new WorldNode(
+      WorldNodeId.testReference({
+        storyId: props.storyId,
+        acId: props.acId,
+        binding,
+        testType: props.testType,
+        filePath: props.filePath,
+        testName: props.testName,
+      }),
+      props.digest,
+      {
+        type: "test-reference",
+        storyId: props.storyId,
+        acId: props.acId,
+        binding,
+        testType: props.testType,
+        filePath: props.filePath.toString(),
+        testName: props.testName ?? null,
+      },
+      props.attributes,
+    );
+  }
+
+  toCanonicalValue(): CanonicalJsonObject {
+    return {
+      attributes: this.attributes,
+      contentDigest: this.contentDigest.toString(),
+      id: this.id.toString(),
+      nodeType: this.id.nodeType,
+      projection: this.projection as CanonicalJsonObject,
+    };
+  }
+}

package/scripts/harness/world-model/domain/ports/world-hashing-port.ts

@@ -0,0 +1,8 @@
+// @unit world-model
+// @layer domain
+// @work-item-id WI-287
+import type { Sha256Digest } from "../value-objects/sha256-digest.js";
+
+export interface WorldHashingPort {
+  sha256(bytes: Uint8Array): Sha256Digest;
+}

package/scripts/harness/world-model/domain/services/canonical-json-serializer.ts

@@ -0,0 +1,113 @@
+// @unit world-model
+// @layer domain
+// @work-item-id WI-287
+export type CanonicalJsonPrimitive = null | boolean | number | string;
+export type CanonicalJsonArray = readonly CanonicalJsonValue[];
+export interface CanonicalJsonObject {
+  readonly [key: string]: CanonicalJsonValue;
+}
+export type CanonicalJsonValue = CanonicalJsonPrimitive | CanonicalJsonArray | CanonicalJsonObject;
+
+export class CanonicalizationError extends Error {
+  constructor(message: string) {
+    super(`World canonicalization failed: ${message}`);
+    this.name = "CanonicalizationError";
+  }
+}
+
+const isPlainObject = (value: object): boolean => {
+  const prototype = Object.getPrototypeOf(value);
+  return prototype === Object.prototype || prototype === null;
+};
+
+const stringifyValue = (value: unknown, ancestors: WeakSet<object>, path: string): string => {
+  if (value === null) {
+    return "null";
+  }
+
+  switch (typeof value) {
+    case "boolean":
+    case "string":
+      return JSON.stringify(value);
+    case "number":
+      if (!Number.isFinite(value)) {
+        throw new CanonicalizationError(`${path} contains a non-finite number`);
+      }
+      return JSON.stringify(value);
+    case "undefined":
+    case "bigint":
+    case "function":
+    case "symbol":
+      throw new CanonicalizationError(`${path} contains unsupported ${typeof value}`);
+    case "object":
+      break;
+    default:
+      throw new CanonicalizationError(`${path} contains an unsupported value`);
+  }
+
+  if (ancestors.has(value)) {
+    throw new CanonicalizationError(`${path} contains a cycle`);
+  }
+  ancestors.add(value);
+
+  try {
+    if (Array.isArray(value)) {
+      if (Object.getOwnPropertySymbols(value).length > 0) {
+        throw new CanonicalizationError(`${path} contains a symbol-keyed array property`);
+      }
+      const propertyNames = Object.getOwnPropertyNames(value);
+      const allowedNames = new Set(["length", ...value.map((_, index) => String(index))]);
+      if (propertyNames.some((name) => !allowedNames.has(name))) {
+        throw new CanonicalizationError(`${path} contains a non-index array property`);
+      }
+
+      const entries: string[] = [];
+      for (let index = 0; index < value.length; index += 1) {
+        if (!(index in value)) {
+          throw new CanonicalizationError(`${path}[${index}] is sparse`);
+        }
+        const descriptor = Object.getOwnPropertyDescriptor(value, String(index));
+        if (!descriptor || !("value" in descriptor)) {
+          throw new CanonicalizationError(`${path}[${index}] is an accessor property`);
+        }
+        entries.push(stringifyValue(value[index], ancestors, `${path}[${index}]`));
+      }
+      return `[${entries.join(",")}]`;
+    }
+
+    if (!isPlainObject(value)) {
+      throw new CanonicalizationError(`${path} is not a plain object`);
+    }
+    if (Object.getOwnPropertySymbols(value).length > 0) {
+      throw new CanonicalizationError(`${path} contains a symbol-keyed property`);
+    }
+
+    const propertyNames = Object.getOwnPropertyNames(value);
+    const enumerableKeys = Object.keys(value);
+    if (propertyNames.length !== enumerableKeys.length) {
+      throw new CanonicalizationError(`${path} contains a non-enumerable property`);
+    }
+
+    const record = value as Record<string, unknown>;
+    const entries = enumerableKeys.sort().map((key) => {
+      const descriptor = Object.getOwnPropertyDescriptor(value, key);
+      if (!descriptor || !("value" in descriptor)) {
+        throw new CanonicalizationError(`${path}.${key} is an accessor property`);
+      }
+      return `${JSON.stringify(key)}:${stringifyValue(record[key], ancestors, `${path}.${key}`)}`;
+    });
+    return `{${entries.join(",")}}`;
+  } finally {
+    ancestors.delete(value);
+  }
+};
+
+export class CanonicalJsonSerializer {
+  serialize(value: unknown): Uint8Array {
+    return new TextEncoder().encode(this.stringify(value));
+  }
+
+  stringify(value: unknown): string {
+    return stringifyValue(value, new WeakSet<object>(), "$");
+  }
+}