phasegate 0.229.0 → 0.254.0

package/scripts/harness/world-model/domain/value-objects/corpus-role.ts

@@ -0,0 +1,57 @@
+// @unit world-model
+// @layer domain
+// @work-item-id WI-287
+export type CorpusRoleValue = "product" | "inception" | "adr" | "generated" | "external";
+
+const VALUES: readonly CorpusRoleValue[] = ["product", "inception", "adr", "generated", "external"];
+
+export class InvalidCorpusRoleError extends Error {
+  constructor(value: string) {
+    super(`Invalid World corpus role: "${value}"`);
+    this.name = "InvalidCorpusRoleError";
+  }
+}
+
+export class CorpusRole {
+  readonly value: CorpusRoleValue;
+
+  private constructor(value: CorpusRoleValue) {
+    this.value = value;
+    Object.freeze(this);
+  }
+
+  static parse(value: string): CorpusRole {
+    if (!VALUES.includes(value as CorpusRoleValue)) {
+      throw new InvalidCorpusRoleError(value);
+    }
+    return new CorpusRole(value as CorpusRoleValue);
+  }
+
+  static product(): CorpusRole {
+    return new CorpusRole("product");
+  }
+
+  static inception(): CorpusRole {
+    return new CorpusRole("inception");
+  }
+
+  static adr(): CorpusRole {
+    return new CorpusRole("adr");
+  }
+
+  static generated(): CorpusRole {
+    return new CorpusRole("generated");
+  }
+
+  static external(): CorpusRole {
+    return new CorpusRole("external");
+  }
+
+  equals(other: CorpusRole): boolean {
+    return this.value === other.value;
+  }
+
+  toString(): string {
+    return this.value;
+  }
+}

package/scripts/harness/world-model/domain/value-objects/declared-key.ts

@@ -0,0 +1,35 @@
+// @unit world-model
+// @layer domain
+// @work-item-id WI-287
+const DECLARED_KEY_PATTERN = /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/;
+
+export class InvalidDeclaredKeyError extends Error {
+  constructor(value: string) {
+    super(`Invalid World declared key: "${value}"`);
+    this.name = "InvalidDeclaredKeyError";
+  }
+}
+
+export class DeclaredKey {
+  readonly value: string;
+
+  private constructor(value: string) {
+    this.value = value;
+    Object.freeze(this);
+  }
+
+  static create(value: string): DeclaredKey {
+    if (!DECLARED_KEY_PATTERN.test(value)) {
+      throw new InvalidDeclaredKeyError(value);
+    }
+    return new DeclaredKey(value);
+  }
+
+  equals(other: DeclaredKey): boolean {
+    return this.value === other.value;
+  }
+
+  toString(): string {
+    return this.value;
+  }
+}

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

@@ -0,0 +1,41 @@
+// @unit world-model
+// @layer domain
+// @work-item-id WI-287
+import type { Sha256Digest } from "./sha256-digest.js";
+
+const EVALUATION_ID_PATTERN = /^pgw:v1:evaluation:sha256:[0-9a-f]{64}$/;
+
+export class InvalidEvaluationIdError extends Error {
+  constructor(value: string) {
+    super(`Invalid World evaluation ID: "${value}"`);
+    this.name = "InvalidEvaluationIdError";
+  }
+}
+
+export class EvaluationId {
+  readonly value: string;
+
+  private constructor(value: string) {
+    this.value = value;
+    Object.freeze(this);
+  }
+
+  static fromDigest(digest: Sha256Digest): EvaluationId {
+    return new EvaluationId(`pgw:v1:evaluation:${digest.toString()}`);
+  }
+
+  static parse(value: string): EvaluationId {
+    if (!EVALUATION_ID_PATTERN.test(value)) {
+      throw new InvalidEvaluationIdError(value);
+    }
+    return new EvaluationId(value);
+  }
+
+  equals(other: EvaluationId): boolean {
+    return this.value === other.value;
+  }
+
+  toString(): string {
+    return this.value;
+  }
+}

package/scripts/harness/world-model/domain/value-objects/explicit-constraint-relation.ts

@@ -0,0 +1,53 @@
+// @unit world-model
+// @layer domain
+// @work-item-id WI-293
+
+import type { ConstraintFactType } from "../entities/constraint-record.js";
+import type { CanonicalJsonObject } from "../services/canonical-json-serializer.js";
+import type { WorldNodeId } from "./world-node-id.js";
+
+export interface ExplicitConstraintRelationProps {
+  readonly constraintId: WorldNodeId;
+  readonly factType: ConstraintFactType;
+  readonly claimantId: WorldNodeId;
+  readonly premiseId: WorldNodeId;
+}
+
+export class InvalidExplicitConstraintRelationError extends Error {
+  constructor(message: string) {
+    super(`Invalid explicit World constraint relation: ${message}`);
+    this.name = "InvalidExplicitConstraintRelationError";
+  }
+}
+
+export class ExplicitConstraintRelation {
+  readonly constraintId: WorldNodeId;
+  readonly factType: ConstraintFactType;
+  readonly claimantId: WorldNodeId;
+  readonly premiseId: WorldNodeId;
+
+  private constructor(props: ExplicitConstraintRelationProps) {
+    this.constraintId = props.constraintId;
+    this.factType = props.factType;
+    this.claimantId = props.claimantId;
+    this.premiseId = props.premiseId;
+    Object.freeze(this);
+  }
+
+  static create(props: ExplicitConstraintRelationProps): ExplicitConstraintRelation {
+    if (props.constraintId.nodeType !== "constraint") {
+      throw new InvalidExplicitConstraintRelationError("constraintId must be a constraint node ID");
+    }
+    return new ExplicitConstraintRelation(props);
+  }
+
+  toCanonicalValue(): CanonicalJsonObject {
+    return {
+      claimantId: this.claimantId.toString(),
+      constraintId: this.constraintId.toString(),
+      factType: this.factType,
+      premiseId: this.premiseId.toString(),
+      source: "constraint-declaration",
+    };
+  }
+}

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

@@ -0,0 +1,30 @@
+// @unit world-model
+// @layer domain
+// @work-item-id WI-293
+
+import type { CanonicalJsonObject } from "../services/canonical-json-serializer.js";
+import type { WorldNodeId } from "./world-node-id.js";
+
+export interface ExplicitNodeAliasProps {
+  readonly from: WorldNodeId;
+  readonly to: WorldNodeId;
+}
+
+export class ExplicitNodeAlias {
+  readonly from: WorldNodeId;
+  readonly to: WorldNodeId;
+
+  private constructor(props: ExplicitNodeAliasProps) {
+    this.from = props.from;
+    this.to = props.to;
+    Object.freeze(this);
+  }
+
+  static create(props: ExplicitNodeAliasProps): ExplicitNodeAlias {
+    return new ExplicitNodeAlias(props);
+  }
+
+  toCanonicalValue(): CanonicalJsonObject {
+    return { from: this.from.toString(), to: this.to.toString() };
+  }
+}

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

@@ -0,0 +1,34 @@
+// @unit world-model
+// @layer domain
+// @work-item-id WI-293
+
+import type { CanonicalJsonObject } from "../services/canonical-json-serializer.js";
+import type { Sha256Digest } from "./sha256-digest.js";
+import type { WorldNodeId } from "./world-node-id.js";
+
+export interface NodePinProps {
+  readonly nodeId: WorldNodeId;
+  readonly contentDigest: Sha256Digest;
+}
+
+export class NodePin {
+  readonly nodeId: WorldNodeId;
+  readonly contentDigest: Sha256Digest;
+
+  private constructor(props: NodePinProps) {
+    this.nodeId = props.nodeId;
+    this.contentDigest = props.contentDigest;
+    Object.freeze(this);
+  }
+
+  static create(props: NodePinProps): NodePin {
+    return new NodePin(props);
+  }
+
+  toCanonicalValue(): CanonicalJsonObject {
+    return {
+      contentDigest: this.contentDigest.toString(),
+      nodeId: this.nodeId.toString(),
+    };
+  }
+}

package/scripts/harness/world-model/domain/value-objects/path-key.ts

@@ -0,0 +1,103 @@
+// @unit world-model
+// @layer domain
+// @work-item-id WI-287
+export class InvalidPathKeyError extends Error {
+  constructor(value: string) {
+    super(`Invalid World PathKey: "${value}"`);
+    this.name = "InvalidPathKeyError";
+  }
+}
+
+const encodeRfc3986Component = (value: string): string =>
+  encodeURIComponent(value).replace(
+    /[!'()*]/g,
+    (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`,
+  );
+
+export const encodeWorldIdComponent = (value: string): string => {
+  if (value.length === 0) {
+    throw new InvalidPathKeyError(value);
+  }
+  return encodeRfc3986Component(value);
+};
+
+export const decodeWorldIdComponent = (encoded: string): string => {
+  if (encoded.length === 0) {
+    throw new InvalidPathKeyError(encoded);
+  }
+  let decoded: string;
+  try {
+    decoded = decodeURIComponent(encoded);
+  } catch {
+    throw new InvalidPathKeyError(encoded);
+  }
+  if (encodeWorldIdComponent(decoded) !== encoded) {
+    throw new InvalidPathKeyError(encoded);
+  }
+  return decoded;
+};
+
+const normalizeSegments = (value: string): readonly string[] => {
+  const trimmed = value.trim();
+  if (trimmed.length === 0 || trimmed.includes("\\") || trimmed.startsWith("/") || /^[A-Za-z]:\//.test(trimmed)) {
+    throw new InvalidPathKeyError(value);
+  }
+
+  const segments = trimmed
+    .split("/")
+    .filter((segment) => segment.length > 0 && segment !== ".")
+    .map((segment) => {
+      if (segment === "..") {
+        throw new InvalidPathKeyError(value);
+      }
+      return segment;
+    });
+
+  if (segments.length === 0) {
+    throw new InvalidPathKeyError(value);
+  }
+  return Object.freeze(segments);
+};
+
+export class PathKey {
+  readonly value: string;
+
+  private constructor(value: string) {
+    this.value = value;
+    Object.freeze(this);
+  }
+
+  static create(value: string): PathKey {
+    return new PathKey(normalizeSegments(value).join("/"));
+  }
+
+  static fromEncodedString(value: string): PathKey {
+    if (value.includes("\\") || value.startsWith("/") || value.split("/").some((part) => part === "")) {
+      throw new InvalidPathKeyError(value);
+    }
+    const decoded = value
+      .split("/")
+      .map((segment) => decodeWorldIdComponent(segment))
+      .join("/");
+    const path = PathKey.create(decoded);
+    if (path.toEncodedString() !== value) {
+      throw new InvalidPathKeyError(value);
+    }
+    return path;
+  }
+
+  toEncodedString(): string {
+    return this.value
+      .split("/")
+      .map((segment) => encodeWorldIdComponent(segment))
+      .join("/");
+  }
+
+  equals(other: PathKey): boolean {
+    return this.value === other.value;
+  }
+
+  toString(): string {
+    return this.value;
+  }
+}

package/scripts/harness/world-model/domain/value-objects/sha256-digest.ts

@@ -0,0 +1,39 @@
+// @unit world-model
+// @layer domain
+// @work-item-id WI-287
+const SHA256_PATTERN = /^sha256:[0-9a-f]{64}$/;
+
+export class InvalidSha256DigestError extends Error {
+  constructor(value: string) {
+    super(`Invalid World SHA-256 digest: "${value}"`);
+    this.name = "InvalidSha256DigestError";
+  }
+}
+
+export class Sha256Digest {
+  readonly value: string;
+
+  private constructor(value: string) {
+    this.value = value;
+    Object.freeze(this);
+  }
+
+  static create(value: string): Sha256Digest {
+    if (!SHA256_PATTERN.test(value)) {
+      throw new InvalidSha256DigestError(value);
+    }
+    return new Sha256Digest(value);
+  }
+
+  static fromHex(hex: string): Sha256Digest {
+    return Sha256Digest.create(`sha256:${hex}`);
+  }
+
+  equals(other: Sha256Digest): boolean {
+    return this.value === other.value;
+  }
+
+  toString(): string {
+    return this.value;
+  }
+}

package/scripts/harness/world-model/domain/value-objects/violation-fingerprint.ts

@@ -0,0 +1,36 @@
+// @unit world-model
+// @layer domain
+// @work-item-id WI-294
+
+const VIOLATION_FINGERPRINT_PATTERN = /^pgw:v1:violation-fingerprint:sha256:[0-9a-f]{64}$/;
+
+export class InvalidViolationFingerprintError extends Error {
+  constructor(value: string) {
+    super(`Invalid World violation fingerprint: "${value}"`);
+    this.name = "InvalidViolationFingerprintError";
+  }
+}
+
+export class ViolationFingerprint {
+  readonly value: string;
+
+  private constructor(value: string) {
+    this.value = value;
+    Object.freeze(this);
+  }
+
+  static create(value: string): ViolationFingerprint {
+    if (!VIOLATION_FINGERPRINT_PATTERN.test(value)) {
+      throw new InvalidViolationFingerprintError(value);
+    }
+    return new ViolationFingerprint(value);
+  }
+
+  equals(other: ViolationFingerprint): boolean {
+    return this.value === other.value;
+  }
+
+  toString(): string {
+    return this.value;
+  }
+}

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

@@ -0,0 +1,59 @@
+// @unit world-model
+// @layer domain
+// @work-item-id WI-293
+
+export type WcrRuleIdValue =
+  | "WCR-001"
+  | "WCR-002"
+  | "WCR-003"
+  | "WCR-004"
+  | "WCR-005"
+  | "WCR-006"
+  | "WCR-007"
+  | "WCR-008";
+
+const VALUES: readonly WcrRuleIdValue[] = [
+  "WCR-001",
+  "WCR-002",
+  "WCR-003",
+  "WCR-004",
+  "WCR-005",
+  "WCR-006",
+  "WCR-007",
+  "WCR-008",
+];
+
+export class InvalidWcrRuleIdError extends Error {
+  constructor(value: string) {
+    super(`Invalid World constraint rule ID: "${value}"`);
+    this.name = "InvalidWcrRuleIdError";
+  }
+}
+
+export class WcrRuleId {
+  readonly value: WcrRuleIdValue;
+
+  private constructor(value: WcrRuleIdValue) {
+    this.value = value;
+    Object.freeze(this);
+  }
+
+  static create(value: string): WcrRuleId {
+    if (!VALUES.includes(value as WcrRuleIdValue)) {
+      throw new InvalidWcrRuleIdError(value);
+    }
+    return new WcrRuleId(value as WcrRuleIdValue);
+  }
+
+  static all(): readonly WcrRuleId[] {
+    return Object.freeze(VALUES.map((value) => new WcrRuleId(value)));
+  }
+
+  equals(other: WcrRuleId): boolean {
+    return this.value === other.value;
+  }
+
+  toString(): WcrRuleIdValue {
+    return this.value;
+  }
+}