phasegate 0.229.0 → 0.254.0

package/scripts/harness/world-model/infrastructure/adapters/file-system-world-control-repository-adapters.ts

@@ -0,0 +1,330 @@
+// @unit world-model
+// @layer infrastructure
+// @work-item-id WI-294
+
+import { readFile, rename, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import Ajv2020Module, { type ErrorObject } from "ajv/dist/2020.js";
+import type {
+  AdoptionBaselineRepositoryPort,
+  ConstraintDeclarationRepositoryPort,
+  ConstraintDeclarationSet,
+  SemanticDebtRepositoryPort,
+  WaiverDeclarationRepositoryPort,
+  WorldControlDiagnosticDto,
+  WorldControlReadResult,
+  WorldControlReplaceResult,
+} from "../../application/ports/world-control-declaration-repository-port.js";
+import type {
+  AdoptionBaseline,
+  SemanticDebtDeclaration,
+  WorldWaiver,
+} from "../../domain/entities/control-declarations.js";
+import { ArtifactKind } from "../../domain/value-objects/artifact-kind.js";
+import { CorpusRole } from "../../domain/value-objects/corpus-role.js";
+import { PathKey } from "../../domain/value-objects/path-key.js";
+import { WorldNodeId } from "../../domain/value-objects/world-node-id.js";
+import {
+  InvalidControlDeclarationError,
+  mapAdoptionBaselineDocument,
+  mapConstraintDeclarationDocument,
+  mapSemanticDebtDocument,
+  mapWaiverDocument,
+} from "./world-control-declaration-mapper.js";
+
+const Ajv2020 = Ajv2020Module.default ?? Ajv2020Module;
+
+const CONTRACT_ROOT = fileURLToPath(new URL("../../../../../docs/contracts/", import.meta.url));
+let temporarySequence = 0;
+
+interface RepositoryOptions {
+  readonly rootDir: string;
+}
+
+interface DeclarationSpec<T> {
+  readonly fileName: string;
+  readonly schemaFileName: string;
+  readonly schemaVersion: string;
+  readonly emptyValue: T;
+  readonly map: (value: unknown) => T;
+  readonly allowMalformedConstraintRecords?: boolean;
+}
+
+type RawReadResult =
+  | { readonly state: "absent" }
+  | { readonly state: "present"; readonly value: unknown }
+  | { readonly state: "invalid"; readonly diagnostic: WorldControlDiagnosticDto };
+
+const freezeDiagnostic = (
+  code: string,
+  fileName: string,
+  message: string,
+  locator: string | null = null,
+): WorldControlDiagnosticDto => Object.freeze({ code, path: fileName, locator, message });
+
+const schemaVersionOf = (value: unknown): unknown =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+    ? (value as Record<string, unknown>).schemaVersion
+    : undefined;
+
+const formatAjvErrors = (errors: readonly ErrorObject[] | null | undefined): string =>
+  (errors ?? [])
+    .map((error) => `${error.instancePath || "/"} ${error.message ?? error.keyword}`)
+    .sort()
+    .join("; ");
+
+const relaxedConstraintEnvelopeSchema = (schema: Record<string, unknown>): Record<string, unknown> => {
+  const copy = structuredClone(schema) as Record<string, unknown>;
+  const properties = copy.properties as Record<string, unknown>;
+  const constraints = properties.constraints as Record<string, unknown>;
+  const aliases = properties.aliases as Record<string, unknown>;
+  constraints.items = { type: "object" };
+  aliases.items = { type: "object" };
+  return copy;
+};
+
+class FileSystemWorldControlRepository<T> {
+  constructor(
+    private readonly options: RepositoryOptions,
+    private readonly spec: DeclarationSpec<T>,
+  ) {}
+
+  async load(): Promise<WorldControlReadResult<T>> {
+    const raw = await this.readRaw();
+    if (raw.state === "absent") {
+      return Object.freeze({ state: "absent", value: this.spec.emptyValue, diagnostics: Object.freeze([]) });
+    }
+    if (raw.state === "invalid") {
+      return Object.freeze({ state: "invalid", diagnostics: Object.freeze([raw.diagnostic]) });
+    }
+    const admitted = await this.admit(raw.value, this.spec.allowMalformedConstraintRecords === true);
+    if (admitted.state === "invalid") return admitted;
+    return Object.freeze({
+      state: "loaded",
+      value: admitted.value,
+      diagnostics: Object.freeze(this.isConstraintSet(admitted.value) ? [...admitted.value.diagnostics] : []),
+    });
+  }
+
+  async replaceAtomically(document: unknown): Promise<WorldControlReplaceResult> {
+    const admitted = await this.admit(document, false);
+    if (admitted.state === "invalid") return admitted;
+    const absolutePath = path.join(this.options.rootDir, this.spec.fileName);
+    const temporaryPath = `${absolutePath}.${process.pid}-${temporarySequence++}.tmp`;
+    try {
+      await writeFile(temporaryPath, `${JSON.stringify(document, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
+      await rename(temporaryPath, absolutePath);
+      return Object.freeze({ state: "written", path: this.spec.fileName });
+    } catch (error) {
+      await rm(temporaryPath, { force: true }).catch(() => undefined);
+      return Object.freeze({
+        state: "invalid",
+        diagnostics: Object.freeze([
+          freezeDiagnostic(
+            "control-write-failure",
+            this.spec.fileName,
+            error instanceof Error ? error.message : String(error),
+          ),
+        ]),
+      });
+    }
+  }
+
+  private async readRaw(): Promise<RawReadResult> {
+    let bytes: Uint8Array;
+    try {
+      bytes = await readFile(path.join(this.options.rootDir, this.spec.fileName));
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return { state: "absent" };
+      return {
+        state: "invalid",
+        diagnostic: freezeDiagnostic(
+          "control-read-failure",
+          this.spec.fileName,
+          error instanceof Error ? error.message : String(error),
+        ),
+      };
+    }
+    let text: string;
+    try {
+      text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+    } catch {
+      return {
+        state: "invalid",
+        diagnostic: freezeDiagnostic("invalid-utf8", this.spec.fileName, "Control file is not valid UTF-8"),
+      };
+    }
+    try {
+      return { state: "present", value: JSON.parse(text) };
+    } catch (error) {
+      return {
+        state: "invalid",
+        diagnostic: freezeDiagnostic(
+          "invalid-json",
+          this.spec.fileName,
+          error instanceof Error ? error.message : String(error),
+        ),
+      };
+    }
+  }
+
+  private async admit(
+    value: unknown,
+    allowMalformedConstraintRecords: boolean,
+  ): Promise<WorldControlReadResult<T> & { readonly state: "loaded" | "invalid" }> {
+    const schemaVersion = schemaVersionOf(value);
+    if (schemaVersion === undefined) {
+      return this.invalid("missing-schema-version", "schemaVersion is required");
+    }
+    if (schemaVersion !== this.spec.schemaVersion) {
+      return this.invalid(
+        "unsupported-schema-version",
+        `Expected ${this.spec.schemaVersion}, received ${String(schemaVersion)}`,
+      );
+    }
+    let schema: Record<string, unknown>;
+    try {
+      schema = JSON.parse(await readFile(path.join(CONTRACT_ROOT, this.spec.schemaFileName), "utf8")) as Record<
+        string,
+        unknown
+      >;
+    } catch (error) {
+      return this.invalid("schema-load-failure", error instanceof Error ? error.message : String(error));
+    }
+    const validationSchema = allowMalformedConstraintRecords ? relaxedConstraintEnvelopeSchema(schema) : schema;
+    const ajv = new Ajv2020({ allErrors: true, strict: false });
+    const validate = ajv.compile(validationSchema);
+    if (!validate(value)) {
+      return this.invalid("malformed-control-document", formatAjvErrors(validate.errors));
+    }
+    try {
+      return Object.freeze({ state: "loaded", value: this.spec.map(value), diagnostics: Object.freeze([]) });
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return this.invalid(
+        error instanceof InvalidControlDeclarationError ? "malformed-control-document" : "control-mapping-failure",
+        message,
+      );
+    }
+  }
+
+  private invalid(
+    code: string,
+    message: string,
+  ): { readonly state: "invalid"; readonly diagnostics: readonly WorldControlDiagnosticDto[] } {
+    return Object.freeze({
+      state: "invalid",
+      diagnostics: Object.freeze([freezeDiagnostic(code, this.spec.fileName, message)]),
+    });
+  }
+
+  private isConstraintSet(value: T): value is T & ConstraintDeclarationSet {
+    return typeof value === "object" && value !== null && "malformedDeclarations" in value;
+  }
+}
+
+const emptyConstraints = (): ConstraintDeclarationSet =>
+  Object.freeze({
+    schemaVersion: "phasegate-world-constraints/v1",
+    records: Object.freeze([]),
+    malformedDeclarations: Object.freeze([]),
+    aliases: Object.freeze([]),
+    relations: Object.freeze([]),
+    diagnostics: Object.freeze([]),
+  });
+
+export class FileSystemConstraintDeclarationRepositoryAdapter implements ConstraintDeclarationRepositoryPort {
+  private readonly repository: FileSystemWorldControlRepository<ConstraintDeclarationSet>;
+
+  constructor(options: RepositoryOptions) {
+    const fileName = "phasegate.world-constraints.json";
+    const artifactId = WorldNodeId.artifact(
+      ArtifactKind.externalDeclaration(),
+      CorpusRole.external(),
+      PathKey.create(fileName),
+    );
+    this.repository = new FileSystemWorldControlRepository(options, {
+      fileName,
+      schemaFileName: "world-constraints.schema.json",
+      schemaVersion: "phasegate-world-constraints/v1",
+      emptyValue: emptyConstraints(),
+      map: (value) => mapConstraintDeclarationDocument(value, artifactId),
+      allowMalformedConstraintRecords: true,
+    });
+  }
+
+  load(): Promise<WorldControlReadResult<ConstraintDeclarationSet>> {
+    return this.repository.load();
+  }
+
+  replaceAtomically(document: unknown): Promise<WorldControlReplaceResult> {
+    return this.repository.replaceAtomically(document);
+  }
+}
+
+export class FileSystemAdoptionBaselineRepositoryAdapter implements AdoptionBaselineRepositoryPort {
+  private readonly repository: FileSystemWorldControlRepository<AdoptionBaseline | null>;
+
+  constructor(options: RepositoryOptions) {
+    this.repository = new FileSystemWorldControlRepository(options, {
+      fileName: "phasegate.world-baseline.json",
+      schemaFileName: "world-baseline.schema.json",
+      schemaVersion: "phasegate-world-adoption-baseline/v1",
+      emptyValue: null,
+      map: mapAdoptionBaselineDocument,
+    });
+  }
+
+  load(): Promise<WorldControlReadResult<AdoptionBaseline | null>> {
+    return this.repository.load();
+  }
+
+  replaceAtomically(document: unknown): Promise<WorldControlReplaceResult> {
+    return this.repository.replaceAtomically(document);
+  }
+}
+
+export class FileSystemWaiverDeclarationRepositoryAdapter implements WaiverDeclarationRepositoryPort {
+  private readonly repository: FileSystemWorldControlRepository<readonly WorldWaiver[]>;
+
+  constructor(options: RepositoryOptions) {
+    this.repository = new FileSystemWorldControlRepository(options, {
+      fileName: "phasegate.world-waivers.json",
+      schemaFileName: "world-waivers.schema.json",
+      schemaVersion: "phasegate-world-waivers/v1",
+      emptyValue: Object.freeze([]),
+      map: mapWaiverDocument,
+    });
+  }
+
+  load(): Promise<WorldControlReadResult<readonly WorldWaiver[]>> {
+    return this.repository.load();
+  }
+
+  replaceAtomically(document: unknown): Promise<WorldControlReplaceResult> {
+    return this.repository.replaceAtomically(document);
+  }
+}
+
+export class FileSystemSemanticDebtRepositoryAdapter implements SemanticDebtRepositoryPort {
+  private readonly repository: FileSystemWorldControlRepository<readonly SemanticDebtDeclaration[]>;
+
+  constructor(options: RepositoryOptions) {
+    this.repository = new FileSystemWorldControlRepository(options, {
+      fileName: "phasegate.world-debts.json",
+      schemaFileName: "world-debts.schema.json",
+      schemaVersion: "phasegate-world-debts/v1",
+      emptyValue: Object.freeze([]),
+      map: mapSemanticDebtDocument,
+    });
+  }
+
+  load(): Promise<WorldControlReadResult<readonly SemanticDebtDeclaration[]>> {
+    return this.repository.load();
+  }
+
+  replaceAtomically(document: unknown): Promise<WorldControlReplaceResult> {
+    return this.repository.replaceAtomically(document);
+  }
+}

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

@@ -0,0 +1,101 @@
+// @unit world-model
+// @layer infrastructure
+// @work-item-id WI-290
+
+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 { PathKey } from "../../domain/value-objects/path-key.js";
+import {
+  assertExactKeys,
+  OwnerProjectionError,
+  projectionDiagnostic,
+  readOptionalJson,
+  requireObject,
+  requireString,
+} from "./json-fact-extractor-support.js";
+import type { RuntimeFactExtraction } from "./runtime-fact-extraction.js";
+
+const DEFAULT_INTEGRITY_PATH = "phasegate.integrity.json";
+const RAW_SHA256 = /^[0-9a-f]{64}$/;
+const compareStrings = (left: string, right: string): number => (left < right ? -1 : left > right ? 1 : 0);
+
+interface IntegrityProjection {
+  readonly version: 1;
+  readonly algorithm: "sha256";
+  readonly declarations: readonly {
+    readonly path: string;
+    readonly digest: string;
+  }[];
+}
+
+export interface IntegrityManifestFactExtractorDeps {
+  readonly rootDir: string;
+  readonly hashingPort: WorldHashingPort;
+  readonly manifestPath?: string;
+  readonly serializer?: CanonicalJsonSerializer;
+}
+
+export class IntegrityManifestFactExtractor {
+  private readonly deps: IntegrityManifestFactExtractorDeps;
+  private readonly serializer: CanonicalJsonSerializer;
+
+  constructor(deps: IntegrityManifestFactExtractorDeps) {
+    this.deps = deps;
+    this.serializer = deps.serializer ?? new CanonicalJsonSerializer();
+  }
+
+  async extract(): Promise<RuntimeFactExtraction> {
+    const relativePath = this.deps.manifestPath ?? DEFAULT_INTEGRITY_PATH;
+    const read = await readOptionalJson(this.deps.rootDir, relativePath, "integrity");
+    if (read.state !== "present") {
+      return { nodes: [], edges: [], diagnostics: [read.diagnostic] };
+    }
+    try {
+      const projection = this.project(read.value);
+      const artifact = WorldNode.artifact({
+        artifactKind: ArtifactKind.externalDeclaration(),
+        corpusRole: CorpusRole.external(),
+        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, "integrity", error)],
+      };
+    }
+  }
+
+  private project(value: unknown): IntegrityProjection {
+    const root = requireObject(value, "integrity");
+    assertExactKeys(root, ["version", "algorithm", "files"], "integrity");
+    if (root.version !== 1 || root.algorithm !== "sha256") {
+      throw new OwnerProjectionError("unsupported-provider-schema", "unsupported integrity schema", {
+        algorithm: typeof root.algorithm === "string" ? root.algorithm : null,
+        version: typeof root.version === "number" ? root.version : -1,
+      });
+    }
+    const files = requireObject(root.files, "integrity.files");
+    const declarations = Object.entries(files).map(([filePath, rawDigest]) => {
+      PathKey.create(filePath);
+      const digest = requireString(rawDigest, `integrity.files.${filePath}`);
+      if (!RAW_SHA256.test(digest)) {
+        throw new OwnerProjectionError("malformed-provider-document", `integrity digest is invalid for ${filePath}`, {
+          filePath,
+        });
+      }
+      return { path: filePath, digest: `sha256:${digest}` };
+    });
+    return {
+      version: 1,
+      algorithm: "sha256",
+      declarations: declarations.sort((left, right) => compareStrings(left.path, right.path)),
+    };
+  }
+}

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

@@ -0,0 +1,151 @@
+// @unit world-model
+// @layer infrastructure
+// @work-item-id WI-290
+
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { ExtractionDiagnostic } from "../../domain/entities/extraction-diagnostic.js";
+import { PathKey } from "../../domain/value-objects/path-key.js";
+
+export class OwnerProjectionError extends Error {
+  readonly code: string;
+  readonly payload: Readonly<Record<string, string | number | boolean | null | readonly string[]>>;
+
+  constructor(
+    code: string,
+    message: string,
+    payload: Record<string, string | number | boolean | null | readonly string[]> = {},
+  ) {
+    super(message);
+    this.name = "OwnerProjectionError";
+    this.code = code;
+    this.payload = Object.freeze({ ...payload });
+  }
+}
+
+export type OptionalJsonReadResult =
+  | { readonly state: "present"; readonly value: unknown; readonly path: PathKey }
+  | { readonly state: "not-present"; readonly diagnostic: ExtractionDiagnostic }
+  | { readonly state: "invalid"; readonly diagnostic: ExtractionDiagnostic };
+
+export const readOptionalJson = async (
+  rootDir: string,
+  relativePath: string,
+  provider: string,
+): Promise<OptionalJsonReadResult> => {
+  const pathKey = PathKey.create(relativePath);
+  let bytes: Uint8Array;
+  try {
+    bytes = await readFile(path.join(rootDir, relativePath));
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") {
+      return {
+        state: "not-present",
+        diagnostic: ExtractionDiagnostic.create({
+          code: "not-present",
+          path: pathKey,
+          payload: { provider },
+        }),
+      };
+    }
+    return {
+      state: "invalid",
+      diagnostic: ExtractionDiagnostic.create({
+        code: "provider-read-failure",
+        path: pathKey,
+        payload: {
+          message: error instanceof Error ? error.message : String(error),
+          provider,
+        },
+      }),
+    };
+  }
+
+  let text: string;
+  try {
+    text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
+  } catch {
+    return {
+      state: "invalid",
+      diagnostic: ExtractionDiagnostic.create({
+        code: "invalid-utf8",
+        path: pathKey,
+        payload: { byteLength: bytes.byteLength, provider },
+      }),
+    };
+  }
+  try {
+    return { state: "present", value: JSON.parse(text), path: pathKey };
+  } catch (error) {
+    return {
+      state: "invalid",
+      diagnostic: ExtractionDiagnostic.create({
+        code: "provider-parse-failure",
+        path: pathKey,
+        payload: {
+          message: error instanceof Error ? error.message : String(error),
+          provider,
+        },
+      }),
+    };
+  }
+};
+
+export const projectionDiagnostic = (pathKey: PathKey, provider: string, error: unknown): ExtractionDiagnostic => {
+  if (error instanceof OwnerProjectionError) {
+    return ExtractionDiagnostic.create({
+      code: error.code,
+      path: pathKey,
+      payload: { ...error.payload, message: error.message, provider },
+    });
+  }
+  return ExtractionDiagnostic.create({
+    code: "provider-projection-failure",
+    path: pathKey,
+    payload: {
+      message: error instanceof Error ? error.message : String(error),
+      provider,
+    },
+  });
+};
+
+export const requireObject = (value: unknown, field: string): Record<string, unknown> => {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new OwnerProjectionError("malformed-provider-document", `${field} must be an object`, { field });
+  }
+  return value as Record<string, unknown>;
+};
+
+export const requireArray = (value: unknown, field: string): readonly unknown[] => {
+  if (!Array.isArray(value)) {
+    throw new OwnerProjectionError("malformed-provider-document", `${field} must be an array`, { field });
+  }
+  return value;
+};
+
+export const requireString = (value: unknown, field: string): string => {
+  if (typeof value !== "string") {
+    throw new OwnerProjectionError("malformed-provider-document", `${field} must be a string`, { field });
+  }
+  return value;
+};
+
+export const requireBoolean = (value: unknown, field: string): boolean => {
+  if (typeof value !== "boolean") {
+    throw new OwnerProjectionError("malformed-provider-document", `${field} must be a boolean`, { field });
+  }
+  return value;
+};
+
+export const assertExactKeys = (value: Record<string, unknown>, allowed: readonly string[], field: string): void => {
+  const unsupported = Object.keys(value)
+    .filter((key) => !allowed.includes(key))
+    .sort();
+  if (unsupported.length > 0) {
+    throw new OwnerProjectionError(
+      "unsupported-projection-field",
+      `${field} contains unsupported fields: ${unsupported.join(", ")}`,
+      { field, unsupported },
+    );
+  }
+};