phasegate 0.229.0 → 0.254.0

package/scripts/harness/world-model/composition-root.ts

@@ -0,0 +1,218 @@
+// @unit world-model
+// @layer composition
+// @work-item-id WI-291
+// @work-item-id WI-292
+// @work-item-id WI-295
+// @work-item-id WI-296, WI-297
+
+import { createAttestationModule, createSha256Capability } from "../attestation/index.js";
+import { createTraceabilityModelModule } from "../traceability-model/index.js";
+import {
+  resolveWorldCorpusConfig,
+  type WorldResolvedConfigInput,
+} from "./application/dto/world-resolved-config-input.js";
+import { BuildSnapshotUseCase } from "./application/usecases/build-snapshot-use-case.js";
+import { DeriveObligationsUseCase } from "./application/usecases/derive-obligations-use-case.js";
+import {
+  DeriveWorldObligationsUseCase,
+  type PolicyDatePort,
+} from "./application/usecases/derive-world-obligations-use-case.js";
+import { InspectWorldUseCase } from "./application/usecases/inspect-world-use-case.js";
+import { PinConstraintEndpointUseCase } from "./application/usecases/pin-constraint-endpoint-use-case.js";
+import { CanonicalJsonSerializer } from "./domain/services/canonical-json-serializer.js";
+import { ObligationDerivationService } from "./domain/services/obligation-derivation-service.js";
+import { PolicyInputsDigestDeriver } from "./domain/services/policy-inputs-digest-deriver.js";
+import { SnapshotRootDeriver } from "./domain/services/snapshot-root-deriver.js";
+import { ViolationFingerprintDeriver } from "./domain/services/violation-fingerprint-deriver.js";
+import { AdrFactExtractor } from "./infrastructure/adapters/adr-fact-extractor.js";
+import { AssembledWorldFactSource } from "./infrastructure/adapters/assembled-world-fact-source.js";
+import {
+  AttestationFactExtractor,
+  AttestationVerificationHandlerAdapter,
+} from "./infrastructure/adapters/attestation-fact-extractor.js";
+import { AttestationSha256WorldHashingAdapter } from "./infrastructure/adapters/attestation-sha256-world-hashing-adapter.js";
+import { CompositeDesignFactSource } from "./infrastructure/adapters/composite-design-fact-source.js";
+import { DesignCorpusFactExtractor } from "./infrastructure/adapters/design-corpus-fact-extractor.js";
+import { FileSystemObligationReportWriterAdapter } from "./infrastructure/adapters/file-system-obligation-report-writer-adapter.js";
+import {
+  FileSystemAdoptionBaselineRepositoryAdapter,
+  FileSystemConstraintDeclarationRepositoryAdapter,
+  FileSystemSemanticDebtRepositoryAdapter,
+  FileSystemWaiverDeclarationRepositoryAdapter,
+} from "./infrastructure/adapters/file-system-world-control-repository-adapters.js";
+import { IntegrityManifestFactExtractor } from "./infrastructure/adapters/integrity-manifest-fact-extractor.js";
+import { MarkdownDesignFactExtractor } from "./infrastructure/adapters/markdown-design-fact-extractor.js";
+import { MatrixFactExtractor } from "./infrastructure/adapters/matrix-fact-extractor.js";
+import { ProductFactExtractor } from "./infrastructure/adapters/product-fact-extractor.js";
+import { ProposalFactExtractor } from "./infrastructure/adapters/proposal-fact-extractor.js";
+import { SourceMetadataFactExtractor } from "./infrastructure/adapters/source-metadata-fact-extractor.js";
+import { TestReferenceSourceFactExtractor } from "./infrastructure/adapters/test-reference-source-fact-extractor.js";
+import { TraceabilityDesignFactAdapter } from "./infrastructure/adapters/traceability-design-fact-adapter.js";
+import { TraceabilityWorldReadFacadeMerger } from "./infrastructure/adapters/traceability-world-read-facade-merger.js";
+import { UnitFactExtractor } from "./infrastructure/adapters/unit-fact-extractor.js";
+import { WorldDeriveCommandHandler } from "./presentation/cli/world-derive-command-handler.js";
+import { WorldInspectCommandHandler } from "./presentation/cli/world-inspect-command-handler.js";
+import { WorldPinCommandHandler } from "./presentation/cli/world-pin-command-handler.js";
+
+const WORLD_SNAPSHOT_SCHEMA_VERSION = "phasegate-world-snapshot/v1";
+const WORLD_EXTRACTOR_VERSION = "phasegate-world-extractor/v2";
+
+export interface WorldModelModuleOptions {
+  readonly rootDir: string;
+  readonly resolvedConfig?: WorldResolvedConfigInput;
+  readonly policyDate?: PolicyDatePort;
+}
+
+export function createWorldModelModule(options: WorldModelModuleOptions) {
+  const config = resolveWorldCorpusConfig(options.resolvedConfig);
+  const hashingPort = new AttestationSha256WorldHashingAdapter(createSha256Capability());
+  const serializer = new CanonicalJsonSerializer();
+  const markdownExtractor = new MarkdownDesignFactExtractor({ hashingPort });
+  const traceabilityFacades = config.productScopes.map(
+    (scope) =>
+      createTraceabilityModelModule(options.rootDir, {
+        pathRoots: {
+          designDocsRoot: scope.designDocsRoot,
+          inceptionRoot: config.inceptionRoot,
+          testRoots: [`${config.sourceRoot}/__tests__`],
+        },
+      }).worldReadFacade,
+  );
+  const designCorpus = new DesignCorpusFactExtractor({
+    traceabilityAdapter: new TraceabilityDesignFactAdapter({
+      facade: new TraceabilityWorldReadFacadeMerger(traceabilityFacades),
+      hashingPort,
+      serializer,
+    }),
+    productExtractor: new CompositeDesignFactSource(
+      config.productScopes.map(
+        (scope) =>
+          new ProductFactExtractor({
+            rootDir: options.rootDir,
+            markdownExtractor,
+            productRoot: scope.productRoot,
+          }),
+      ),
+    ),
+    proposalExtractor: new ProposalFactExtractor({
+      rootDir: options.rootDir,
+      markdownExtractor,
+      inceptionRoot: config.inceptionRoot,
+    }),
+    adrExtractor: new AdrFactExtractor({
+      rootDir: options.rootDir,
+      markdownExtractor,
+      adrRoot: config.adrRoot,
+    }),
+    unitExtractor: new CompositeDesignFactSource(
+      config.productScopes.map(
+        (scope) =>
+          new UnitFactExtractor({
+            rootDir: options.rootDir,
+            markdownExtractor,
+            unitRoot: scope.unitRoot,
+          }),
+      ),
+    ),
+  });
+  const attestationModule = createAttestationModule(options.rootDir);
+  const factSource = new AssembledWorldFactSource([
+    designCorpus,
+    new SourceMetadataFactExtractor({
+      rootDir: options.rootDir,
+      hashingPort,
+      sourceRoot: config.sourceRoot,
+    }),
+    new TestReferenceSourceFactExtractor({
+      rootDir: options.rootDir,
+      hashingPort,
+      sourceRoot: config.sourceRoot,
+    }),
+    new MatrixFactExtractor({
+      rootDir: options.rootDir,
+      hashingPort,
+      matrixPath: config.matrixPath,
+      serializer,
+    }),
+    new AttestationFactExtractor({
+      rootDir: options.rootDir,
+      hashingPort,
+      attestationPath: config.attestationPath,
+      verificationFacade: new AttestationVerificationHandlerAdapter(attestationModule.verifyAttestationHandler),
+      serializer,
+    }),
+    new IntegrityManifestFactExtractor({
+      rootDir: options.rootDir,
+      hashingPort,
+      manifestPath: config.integrityManifestPath,
+      serializer,
+    }),
+  ]);
+  const corpusConfigDigest = hashingPort.sha256(serializer.serialize(config));
+  const buildSnapshotUseCase = new BuildSnapshotUseCase({
+    factSource,
+    rootDeriver: new SnapshotRootDeriver(serializer, hashingPort),
+    serializer,
+    schemaVersion: WORLD_SNAPSHOT_SCHEMA_VERSION,
+    extractorVersion: WORLD_EXTRACTOR_VERSION,
+    corpusConfigDigest,
+  });
+  const inspectWorldUseCase = new InspectWorldUseCase({ buildSnapshot: buildSnapshotUseCase });
+  const fingerprintDeriver = new ViolationFingerprintDeriver(serializer, hashingPort);
+  const constraintRepository = new FileSystemConstraintDeclarationRepositoryAdapter({
+    rootDir: options.rootDir,
+  });
+  const rootDeriver = new SnapshotRootDeriver(serializer, hashingPort);
+  const deriveObligationsUseCase = new DeriveObligationsUseCase({
+    baselineRepository: new FileSystemAdoptionBaselineRepositoryAdapter({
+      rootDir: options.rootDir,
+    }),
+    waiverRepository: new FileSystemWaiverDeclarationRepositoryAdapter({
+      rootDir: options.rootDir,
+    }),
+    semanticDebtRepository: new FileSystemSemanticDebtRepositoryAdapter({
+      rootDir: options.rootDir,
+    }),
+    policyInputsDigestDeriver: new PolicyInputsDigestDeriver(serializer, hashingPort),
+    evaluationIdDeriver: new SnapshotRootDeriver(serializer, hashingPort),
+    obligationDerivationService: new ObligationDerivationService(fingerprintDeriver),
+    serializer,
+    writer: new FileSystemObligationReportWriterAdapter({ rootDir: options.rootDir }),
+  });
+  const deriveWorldObligationsUseCase = new DeriveWorldObligationsUseCase({
+    buildSnapshot: buildSnapshotUseCase,
+    constraintRepository,
+    rootDeriver,
+    deriveObligations: deriveObligationsUseCase,
+    policyDate: options.policyDate ?? {
+      currentUtcDate: () => new Date().toISOString().slice(0, 10),
+    },
+    constraintConfigDigest: hashingPort.sha256(
+      serializer.serialize({
+        schemaVersion: "phasegate-world-constraint-config/v1",
+        constraintsPath: "phasegate.world-constraints.json",
+      }),
+    ),
+    evaluationConfigDigest: hashingPort.sha256(
+      serializer.serialize({
+        schemaVersion: "phasegate-world-evaluation-config/v1",
+        rulesetVersion: "phasegate-world-wcr/v1",
+      }),
+    ),
+  });
+  const pinConstraintEndpointUseCase = new PinConstraintEndpointUseCase(buildSnapshotUseCase, constraintRepository);
+  const worldInspectCommandHandler = new WorldInspectCommandHandler({ inspectWorld: inspectWorldUseCase });
+  const worldPinCommandHandler = new WorldPinCommandHandler(pinConstraintEndpointUseCase);
+  const worldDeriveCommandHandler = new WorldDeriveCommandHandler(deriveWorldObligationsUseCase);
+
+  return {
+    buildSnapshotUseCase,
+    deriveObligationsUseCase,
+    deriveWorldObligationsUseCase,
+    inspectWorldUseCase,
+    pinConstraintEndpointUseCase,
+    worldDeriveCommandHandler,
+    worldInspectCommandHandler,
+    worldPinCommandHandler,
+  } as const;
+}

package/scripts/harness/world-model/domain/entities/constraint-record.ts

@@ -0,0 +1,148 @@
+// @unit world-model
+// @layer domain
+// @work-item-id WI-293
+
+import type { CanonicalJsonObject } from "../services/canonical-json-serializer.js";
+import type { NodePin } from "../value-objects/node-pin.js";
+import type { WcrRuleId } from "../value-objects/wcr-rule-id.js";
+import type { WorldNodeId } from "../value-objects/world-node-id.js";
+
+export type ConstraintFactType = "references" | "depends-on" | "refines" | "content-equals";
+
+const FACT_TYPES: readonly ConstraintFactType[] = ["references", "depends-on", "refines", "content-equals"];
+const SCHEMA_VERSION = "phasegate-world-constraints/v1";
+const compareStrings = (left: string, right: string): number => (left < right ? -1 : left > right ? 1 : 0);
+
+export interface ConstraintRecordProps {
+  readonly constraintId: WorldNodeId;
+  readonly schemaVersion: string;
+  readonly factType: ConstraintFactType;
+  readonly claimant: NodePin;
+  readonly premise: NodePin;
+  readonly applicableRuleIds: readonly WcrRuleId[];
+  readonly declarationArtifactId: WorldNodeId;
+  readonly declarationLocator: string;
+}
+
+export class InvalidConstraintRecordError extends Error {
+  constructor(message: string) {
+    super(`Invalid World constraint record: ${message}`);
+    this.name = "InvalidConstraintRecordError";
+  }
+}
+
+export class ConstraintRecord {
+  readonly constraintId: WorldNodeId;
+  readonly schemaVersion: string;
+  readonly factType: ConstraintFactType;
+  readonly claimant: NodePin;
+  readonly premise: NodePin;
+  readonly applicableRuleIds: readonly WcrRuleId[];
+  readonly declarationArtifactId: WorldNodeId;
+  readonly declarationLocator: string;
+
+  private constructor(props: ConstraintRecordProps, ruleIds: readonly WcrRuleId[]) {
+    this.constraintId = props.constraintId;
+    this.schemaVersion = props.schemaVersion;
+    this.factType = props.factType;
+    this.claimant = props.claimant;
+    this.premise = props.premise;
+    this.applicableRuleIds = ruleIds;
+    this.declarationArtifactId = props.declarationArtifactId;
+    this.declarationLocator = props.declarationLocator;
+    Object.freeze(this);
+  }
+
+  static create(props: ConstraintRecordProps): ConstraintRecord {
+    if (props.constraintId.nodeType !== "constraint") {
+      throw new InvalidConstraintRecordError("constraintId must be a constraint node ID");
+    }
+    if (props.schemaVersion !== SCHEMA_VERSION) {
+      throw new InvalidConstraintRecordError(`unsupported schemaVersion "${props.schemaVersion}"`);
+    }
+    if (!FACT_TYPES.includes(props.factType)) {
+      throw new InvalidConstraintRecordError(`unsupported factType "${props.factType}"`);
+    }
+    if (props.applicableRuleIds.length === 0) {
+      throw new InvalidConstraintRecordError("applicableRuleIds must be non-empty");
+    }
+    const sortedRuleIds = [...props.applicableRuleIds].sort((left, right) =>
+      compareStrings(left.toString(), right.toString()),
+    );
+    const uniqueRuleIds = new Set(sortedRuleIds.map((ruleId) => ruleId.toString()));
+    if (uniqueRuleIds.size !== sortedRuleIds.length) {
+      throw new InvalidConstraintRecordError("applicableRuleIds must be unique");
+    }
+    if (
+      props.declarationArtifactId.nodeType !== "artifact" ||
+      !props.declarationArtifactId.toString().startsWith("pgw:v1:artifact:external-declaration:external:")
+    ) {
+      throw new InvalidConstraintRecordError("declarationArtifactId must identify an external declaration artifact");
+    }
+    if (props.declarationLocator.trim().length === 0) {
+      throw new InvalidConstraintRecordError("declarationLocator must be non-empty");
+    }
+    return new ConstraintRecord(props, Object.freeze(sortedRuleIds));
+  }
+
+  applies(ruleId: string): boolean {
+    return this.applicableRuleIds.some((candidate) => candidate.toString() === ruleId);
+  }
+
+  toCanonicalValue(): CanonicalJsonObject {
+    return {
+      applicableRuleIds: this.applicableRuleIds.map((ruleId) => ruleId.toString()),
+      claimant: this.claimant.toCanonicalValue(),
+      constraintId: this.constraintId.toString(),
+      declarationArtifactId: this.declarationArtifactId.toString(),
+      declarationLocator: this.declarationLocator,
+      factType: this.factType,
+      premise: this.premise.toCanonicalValue(),
+      schemaVersion: this.schemaVersion,
+    };
+  }
+}
+
+export interface MalformedConstraintDeclarationProps {
+  readonly declaredConstraintId?: string;
+  readonly declarationArtifactId: WorldNodeId;
+  readonly declarationLocator: string;
+  readonly reasons: readonly string[];
+}
+
+export class MalformedConstraintDeclaration {
+  readonly declaredConstraintId: string | null;
+  readonly declarationArtifactId: WorldNodeId;
+  readonly declarationLocator: string;
+  readonly reasons: readonly string[];
+
+  private constructor(props: MalformedConstraintDeclarationProps) {
+    this.declaredConstraintId = props.declaredConstraintId ?? null;
+    this.declarationArtifactId = props.declarationArtifactId;
+    this.declarationLocator = props.declarationLocator;
+    this.reasons = Object.freeze([...props.reasons].sort());
+    Object.freeze(this);
+  }
+
+  static create(props: MalformedConstraintDeclarationProps): MalformedConstraintDeclaration {
+    if (
+      props.declarationArtifactId.nodeType !== "artifact" ||
+      !props.declarationArtifactId.toString().startsWith("pgw:v1:artifact:external-declaration:external:")
+    ) {
+      throw new InvalidConstraintRecordError("malformed declaration provenance must be an external declaration");
+    }
+    if (props.declarationLocator.trim().length === 0 || props.reasons.length === 0) {
+      throw new InvalidConstraintRecordError("malformed declaration requires locator and reasons");
+    }
+    return new MalformedConstraintDeclaration(props);
+  }
+
+  toCanonicalValue(): CanonicalJsonObject {
+    return {
+      declarationArtifactId: this.declarationArtifactId.toString(),
+      declarationLocator: this.declarationLocator,
+      declaredConstraintId: this.declaredConstraintId,
+      reasons: this.reasons,
+    };
+  }
+}

package/scripts/harness/world-model/domain/entities/control-declarations.ts

@@ -0,0 +1,274 @@
+// @unit world-model
+// @layer domain
+// @work-item-id WI-294
+
+import type { CanonicalJsonObject } from "../services/canonical-json-serializer.js";
+import type { EvaluationId } from "../value-objects/evaluation-id.js";
+import type { Sha256Digest } from "../value-objects/sha256-digest.js";
+import type { ViolationFingerprint } from "../value-objects/violation-fingerprint.js";
+import type { WcrRuleId } from "../value-objects/wcr-rule-id.js";
+import type { WorldNodeId } from "../value-objects/world-node-id.js";
+
+const compareStrings = (left: string, right: string): number => (left < right ? -1 : left > right ? 1 : 0);
+const WORK_ITEM_PATTERN = /^WI-\d+$/;
+const WAIVER_ID_PATTERN = /^pgw:v1:waiver:[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/;
+const DEBT_ID_PATTERN = /^pgw:v1:semantic-debt:[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/;
+const UNIT_ID_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+
+export class InvalidControlDeclarationDomainError extends Error {
+  constructor(message: string) {
+    super(`Invalid World control declaration: ${message}`);
+    this.name = "InvalidControlDeclarationDomainError";
+  }
+}
+
+const requireNonEmpty = (value: string, field: string): string => {
+  if (value.trim().length === 0) throw new InvalidControlDeclarationDomainError(`${field} must be non-empty`);
+  return value;
+};
+
+const requireWorkItemId = (value: string, field: string): string => {
+  if (!WORK_ITEM_PATTERN.test(value)) throw new InvalidControlDeclarationDomainError(`${field} must be WI-<digits>`);
+  return value;
+};
+
+const requireCalendarDate = (value: string): string => {
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value);
+  if (!match) throw new InvalidControlDeclarationDomainError("expiresOn must be YYYY-MM-DD");
+  const year = Number(match[1]);
+  const month = Number(match[2]);
+  const day = Number(match[3]);
+  const date = new Date(Date.UTC(year, month - 1, day));
+  if (date.getUTCFullYear() !== year || date.getUTCMonth() !== month - 1 || date.getUTCDate() !== day) {
+    throw new InvalidControlDeclarationDomainError("expiresOn must be a valid calendar date");
+  }
+  return value;
+};
+
+export interface AdoptionBaselineEntryProps {
+  readonly violationFingerprint: ViolationFingerprint;
+  readonly ruleId: WcrRuleId;
+  readonly constraintId: WorldNodeId | null;
+}
+
+export class AdoptionBaselineEntry {
+  readonly violationFingerprint: ViolationFingerprint;
+  readonly ruleId: WcrRuleId;
+  readonly constraintId: WorldNodeId | null;
+
+  private constructor(props: AdoptionBaselineEntryProps) {
+    this.violationFingerprint = props.violationFingerprint;
+    this.ruleId = props.ruleId;
+    this.constraintId = props.constraintId;
+    Object.freeze(this);
+  }
+
+  static create(props: AdoptionBaselineEntryProps): AdoptionBaselineEntry {
+    if (props.ruleId.toString() === "WCR-001") {
+      throw new InvalidControlDeclarationDomainError("WCR-001 is not adoptable");
+    }
+    if (props.constraintId !== null && props.constraintId.nodeType !== "constraint") {
+      throw new InvalidControlDeclarationDomainError("baseline constraintId must identify a constraint");
+    }
+    return new AdoptionBaselineEntry(props);
+  }
+
+  toCanonicalValue(): CanonicalJsonObject {
+    return {
+      constraintId: this.constraintId?.toString() ?? null,
+      ruleId: this.ruleId.toString(),
+      violationFingerprint: this.violationFingerprint.toString(),
+    };
+  }
+}
+
+export interface AdoptionBaselineProps {
+  readonly schemaVersion: string;
+  readonly rulesetVersion: string;
+  readonly sourceEvaluationId: EvaluationId;
+  readonly sourceCorpusRoot: Sha256Digest;
+  readonly sourceConstraintRoot: Sha256Digest;
+  readonly adoptedByWorkItemId: string;
+  readonly adoptionReason: string;
+  readonly entries: readonly AdoptionBaselineEntry[];
+}
+
+export class AdoptionBaseline {
+  readonly schemaVersion: string;
+  readonly rulesetVersion: string;
+  readonly sourceEvaluationId: EvaluationId;
+  readonly sourceCorpusRoot: Sha256Digest;
+  readonly sourceConstraintRoot: Sha256Digest;
+  readonly adoptedByWorkItemId: string;
+  readonly adoptionReason: string;
+  readonly entries: readonly AdoptionBaselineEntry[];
+
+  private constructor(props: AdoptionBaselineProps, entries: readonly AdoptionBaselineEntry[]) {
+    this.schemaVersion = props.schemaVersion;
+    this.rulesetVersion = props.rulesetVersion;
+    this.sourceEvaluationId = props.sourceEvaluationId;
+    this.sourceCorpusRoot = props.sourceCorpusRoot;
+    this.sourceConstraintRoot = props.sourceConstraintRoot;
+    this.adoptedByWorkItemId = props.adoptedByWorkItemId;
+    this.adoptionReason = props.adoptionReason;
+    this.entries = entries;
+    Object.freeze(this);
+  }
+
+  static create(props: AdoptionBaselineProps): AdoptionBaseline {
+    if (props.schemaVersion !== "phasegate-world-adoption-baseline/v1") {
+      throw new InvalidControlDeclarationDomainError("unsupported adoption baseline schemaVersion");
+    }
+    requireNonEmpty(props.rulesetVersion, "rulesetVersion");
+    requireWorkItemId(props.adoptedByWorkItemId, "adoptedByWorkItemId");
+    requireNonEmpty(props.adoptionReason, "adoptionReason");
+    const entries = [...props.entries].sort((left, right) =>
+      compareStrings(left.violationFingerprint.toString(), right.violationFingerprint.toString()),
+    );
+    const fingerprints = entries.map((entry) => entry.violationFingerprint.toString());
+    if (new Set(fingerprints).size !== fingerprints.length) {
+      throw new InvalidControlDeclarationDomainError("baseline entries contain duplicate violationFingerprint");
+    }
+    return new AdoptionBaseline(props, Object.freeze(entries));
+  }
+
+  toCanonicalValue(): CanonicalJsonObject {
+    return {
+      adoptedByWorkItemId: this.adoptedByWorkItemId,
+      adoptionReason: this.adoptionReason,
+      entries: this.entries.map((entry) => entry.toCanonicalValue()),
+      rulesetVersion: this.rulesetVersion,
+      schemaVersion: this.schemaVersion,
+      sourceConstraintRoot: this.sourceConstraintRoot.toString(),
+      sourceCorpusRoot: this.sourceCorpusRoot.toString(),
+      sourceEvaluationId: this.sourceEvaluationId.toString(),
+    };
+  }
+}
+
+export interface WorldWaiverProps {
+  readonly schemaVersion: string;
+  readonly waiverId: string;
+  readonly violationFingerprint: ViolationFingerprint;
+  readonly reason: string;
+  readonly expiresOn: string;
+  readonly workItemId: string;
+  readonly renewalOf: string | null;
+}
+
+export class WorldWaiver {
+  readonly schemaVersion: string;
+  readonly waiverId: string;
+  readonly violationFingerprint: ViolationFingerprint;
+  readonly reason: string;
+  readonly expiresOn: string;
+  readonly workItemId: string;
+  readonly renewalOf: string | null;
+
+  private constructor(props: WorldWaiverProps) {
+    this.schemaVersion = props.schemaVersion;
+    this.waiverId = props.waiverId;
+    this.violationFingerprint = props.violationFingerprint;
+    this.reason = props.reason;
+    this.expiresOn = props.expiresOn;
+    this.workItemId = props.workItemId;
+    this.renewalOf = props.renewalOf;
+    Object.freeze(this);
+  }
+
+  static create(props: WorldWaiverProps): WorldWaiver {
+    if (props.schemaVersion !== "phasegate-world-waivers/v1") {
+      throw new InvalidControlDeclarationDomainError("unsupported waiver schemaVersion");
+    }
+    if (!WAIVER_ID_PATTERN.test(props.waiverId)) {
+      throw new InvalidControlDeclarationDomainError("waiverId is invalid");
+    }
+    if (props.renewalOf !== null && !WAIVER_ID_PATTERN.test(props.renewalOf)) {
+      throw new InvalidControlDeclarationDomainError("renewalOf is invalid");
+    }
+    requireNonEmpty(props.reason, "reason");
+    requireWorkItemId(props.workItemId, "workItemId");
+    requireCalendarDate(props.expiresOn);
+    return new WorldWaiver(props);
+  }
+
+  toCanonicalValue(): CanonicalJsonObject {
+    return {
+      expiresOn: this.expiresOn,
+      reason: this.reason,
+      renewalOf: this.renewalOf,
+      schemaVersion: this.schemaVersion,
+      violationFingerprint: this.violationFingerprint.toString(),
+      waiverId: this.waiverId,
+      workItemId: this.workItemId,
+    };
+  }
+}
+
+export interface SemanticDebtDeclarationProps {
+  readonly schemaVersion: string;
+  readonly debtId: string;
+  readonly kind: "semantic";
+  readonly title: string;
+  readonly reason: string;
+  readonly ownerUnit: string;
+  readonly introducedByWorkItemId: string;
+  readonly references: readonly WorldNodeId[];
+}
+
+export class SemanticDebtDeclaration {
+  readonly schemaVersion: string;
+  readonly debtId: string;
+  readonly kind = "semantic" as const;
+  readonly title: string;
+  readonly reason: string;
+  readonly ownerUnit: string;
+  readonly introducedByWorkItemId: string;
+  readonly references: readonly WorldNodeId[];
+
+  private constructor(props: SemanticDebtDeclarationProps, references: readonly WorldNodeId[]) {
+    this.schemaVersion = props.schemaVersion;
+    this.debtId = props.debtId;
+    this.title = props.title;
+    this.reason = props.reason;
+    this.ownerUnit = props.ownerUnit;
+    this.introducedByWorkItemId = props.introducedByWorkItemId;
+    this.references = references;
+    Object.freeze(this);
+  }
+
+  static create(props: SemanticDebtDeclarationProps): SemanticDebtDeclaration {
+    if (props.schemaVersion !== "phasegate-world-debts/v1") {
+      throw new InvalidControlDeclarationDomainError("unsupported semantic debt schemaVersion");
+    }
+    if (!DEBT_ID_PATTERN.test(props.debtId)) {
+      throw new InvalidControlDeclarationDomainError("debtId is invalid");
+    }
+    if (props.kind !== "semantic") throw new InvalidControlDeclarationDomainError("kind must be semantic");
+    if (!UNIT_ID_PATTERN.test(props.ownerUnit)) {
+      throw new InvalidControlDeclarationDomainError("ownerUnit is invalid");
+    }
+    requireNonEmpty(props.title, "title");
+    requireNonEmpty(props.reason, "reason");
+    requireWorkItemId(props.introducedByWorkItemId, "introducedByWorkItemId");
+    const references = [...props.references].sort((left, right) => compareStrings(left.toString(), right.toString()));
+    const values = references.map((reference) => reference.toString());
+    if (new Set(values).size !== values.length) {
+      throw new InvalidControlDeclarationDomainError("references must be unique");
+    }
+    return new SemanticDebtDeclaration(props, Object.freeze(references));
+  }
+
+  toCanonicalValue(): CanonicalJsonObject {
+    return {
+      debtId: this.debtId,
+      introducedByWorkItemId: this.introducedByWorkItemId,
+      kind: this.kind,
+      ownerUnit: this.ownerUnit,
+      reason: this.reason,
+      references: this.references.map((reference) => reference.toString()),
+      schemaVersion: this.schemaVersion,
+      title: this.title,
+    };
+  }
+}

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

@@ -0,0 +1,41 @@
+// @unit world-model
+// @layer domain
+// @work-item-id WI-287
+import type { CanonicalJsonObject } from "../services/canonical-json-serializer.js";
+import type { DeclaredKey } from "../value-objects/declared-key.js";
+import type { WorldNodeId } from "../value-objects/world-node-id.js";
+
+export interface EdgeProps {
+  readonly edgeType: DeclaredKey;
+  readonly from: WorldNodeId;
+  readonly to: WorldNodeId;
+  readonly qualifier?: CanonicalJsonObject;
+}
+
+export class Edge {
+  readonly edgeType: DeclaredKey;
+  readonly from: WorldNodeId;
+  readonly to: WorldNodeId;
+  readonly qualifier: CanonicalJsonObject;
+
+  private constructor(props: EdgeProps) {
+    this.edgeType = props.edgeType;
+    this.from = props.from;
+    this.to = props.to;
+    this.qualifier = Object.freeze({ ...(props.qualifier ?? {}) });
+    Object.freeze(this);
+  }
+
+  static create(props: EdgeProps): Edge {
+    return new Edge(props);
+  }
+
+  toCanonicalValue(): CanonicalJsonObject {
+    return {
+      edgeType: this.edgeType.toString(),
+      from: this.from.toString(),
+      qualifier: this.qualifier,
+      to: this.to.toString(),
+    };
+  }
+}