@agent-teams/engineering-foundation 0.4.1 → 0.6.0

package/dist/documentation-observation/application/model/markdown-document.d.ts

@@ -0,0 +1,70 @@
+export type MarkdownAnchorProfile = "github" | "none";
+type MarkdownReferenceKind = "definition" | "image" | "link";
+export interface MarkdownPosition {
+    readonly column: number;
+    readonly line: number;
+    readonly offset: number;
+}
+export interface MarkdownHeadingObservation {
+    readonly depth: number;
+    readonly location: MarkdownPosition;
+    readonly text: string;
+}
+export interface MarkdownAnchorObservation {
+    readonly ids: readonly string[];
+    readonly profile: MarkdownAnchorProfile;
+}
+export interface MarkdownReferenceObservation {
+    readonly kind: MarkdownReferenceKind;
+    readonly location: MarkdownPosition;
+    readonly rawTarget: string;
+}
+export type MarkdownFrontmatterObservation = {
+    readonly endOffset: 0;
+    readonly kind: "absent";
+} | {
+    readonly endOffset: number;
+    readonly kind: "invalid";
+    readonly message: string;
+} | {
+    readonly endOffset: number;
+    readonly kind: "valid";
+    readonly value: unknown;
+};
+export interface MarkdownDocumentObservation {
+    readonly anchorObservations: readonly MarkdownAnchorObservation[];
+    readonly frontmatter: MarkdownFrontmatterObservation;
+    readonly headings: readonly MarkdownHeadingObservation[];
+    readonly references: readonly MarkdownReferenceObservation[];
+    readonly repositoryPath: string;
+    readonly source: string;
+}
+type MarkdownObservationIssueKind = "root-missing" | "root-not-directory" | "source-too-large" | "source-unreadable" | "symbolic-link";
+export interface MarkdownObservationIssue {
+    readonly kind: MarkdownObservationIssueKind;
+    readonly message: string;
+    readonly repositoryPath: string;
+}
+export interface MarkdownRepositoryObservation {
+    readonly documents: readonly MarkdownDocumentObservation[];
+    readonly issues: readonly MarkdownObservationIssue[];
+}
+export type MarkdownReferenceResolution = {
+    readonly kind: "external";
+} | {
+    readonly kind: "file";
+    readonly markdownDocument?: MarkdownDocumentObservation;
+    readonly repositoryPath: string;
+    readonly fragment: string;
+} | {
+    readonly kind: "missing";
+    readonly reason: "directory-readme-missing" | "target-missing";
+    readonly repositoryPath: string;
+} | {
+    readonly kind: "unsafe";
+    readonly reason: "absolute-path" | "invalid-encoding" | "repository-escape" | "symbolic-link";
+};
+export declare function anchorsForMarkdownDocument(document: MarkdownDocumentObservation, profile: MarkdownAnchorProfile): readonly string[];
+export declare function markdownSourceWithoutFrontmatter(document: MarkdownDocumentObservation): string;
+export {};
+//# sourceMappingURL=markdown-document.d.ts.map

package/dist/documentation-observation/application/model/markdown-document.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-document.d.ts","sourceRoot":"","sources":["../../../../src/documentation-observation/application/model/markdown-document.ts"],"names":[],"mappings":"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"}

package/dist/documentation-observation/application/model/markdown-document.js

@@ -0,0 +1,10 @@
+export function anchorsForMarkdownDocument(document, profile) {
+    if (profile === "none") {
+        return [];
+    }
+    return document.anchorObservations.find((observation) => observation.profile === profile)?.ids ?? [];
+}
+export function markdownSourceWithoutFrontmatter(document) {
+    return document.source.slice(document.frontmatter.endOffset);
+}
+//# sourceMappingURL=markdown-document.js.map

package/dist/documentation-observation/application/model/markdown-document.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-document.js","sourceRoot":"","sources":["../../../../src/documentation-observation/application/model/markdown-document.ts"],"names":[],"mappings":"AA8FA,MAAM,UAAU,0BAA0B,CACxC,QAAqC,EACrC,OAA8B;IAE9B,IAAI,OAAO,KAAK,MAAM,EAAE,CAAC;QACvB,OAAO,EAAE,CAAC;IACZ,CAAC;IAED,OAAO,QAAQ,CAAC,kBAAkB,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE,EAAE,CAAC,WAAW,CAAC,OAAO,KAAK,OAAO,CAAC,EAAE,GAAG,IAAI,EAAE,CAAC;AACvG,CAAC;AAED,MAAM,UAAU,gCAAgC,CAC9C,QAAqC;IAErC,OAAO,QAAQ,CAAC,MAAM,CAAC,KAAK,CAAC,QAAQ,CAAC,WAAW,CAAC,SAAS,CAAC,CAAC;AAC/D,CAAC"}

package/dist/documentation-observation/application/ports/markdown-repository.d.ts

@@ -0,0 +1,17 @@
+import type { MarkdownDocumentObservation, MarkdownReferenceResolution, MarkdownRepositoryObservation } from "../model/markdown-document.js";
+export interface ObserveMarkdownRepositoryRequest {
+    readonly consumerRoot: string;
+    readonly roots: readonly string[];
+    readonly signal?: AbortSignal;
+}
+export interface ResolveMarkdownReferenceRequest {
+    readonly consumerRoot: string;
+    readonly rawTarget: string;
+    readonly signal?: AbortSignal;
+    readonly source: MarkdownDocumentObservation;
+}
+export interface MarkdownRepository {
+    observe(request: ObserveMarkdownRepositoryRequest): Promise<MarkdownRepositoryObservation>;
+    resolveReference(request: ResolveMarkdownReferenceRequest): Promise<MarkdownReferenceResolution>;
+}
+//# sourceMappingURL=markdown-repository.d.ts.map

package/dist/documentation-observation/application/ports/markdown-repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-repository.d.ts","sourceRoot":"","sources":["../../../../src/documentation-observation/application/ports/markdown-repository.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,2BAA2B,EAC3B,2BAA2B,EAC3B,6BAA6B,EAC9B,MAAM,+BAA+B,CAAC;AAEvC,MAAM,WAAW,gCAAgC;IAC/C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;IAClC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,2BAA2B,CAAC;CAC9C;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,CACL,OAAO,EAAE,gCAAgC,GACxC,OAAO,CAAC,6BAA6B,CAAC,CAAC;IAC1C,gBAAgB,CACd,OAAO,EAAE,+BAA+B,GACvC,OAAO,CAAC,2BAA2B,CAAC,CAAC;CACzC"}

package/dist/documentation-observation/application/ports/markdown-repository.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=markdown-repository.js.map

package/dist/documentation-observation/application/ports/markdown-repository.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdown-repository.js","sourceRoot":"","sources":["../../../../src/documentation-observation/application/ports/markdown-repository.ts"],"names":[],"mappings":""}

package/dist/filesystem-path-safety.d.ts

@@ -1,2 +1,40 @@
+import { lstat, realpath } from "node:fs/promises";
+export type ContainedFileReadFailure = "changed" | "escape" | "invalid" | "missing" | "symlink" | "unavailable";
+export declare class ContainedFileReadError extends Error {
+    readonly failure: ContainedFileReadFailure;
+    constructor(failure: ContainedFileReadFailure);
+}
+interface FileSnapshot {
+    readonly ctimeMs: number | bigint;
+    readonly dev: number | bigint;
+    readonly ino: number | bigint;
+    readonly mode: number | bigint;
+    readonly mtimeMs: number | bigint;
+    readonly size: number | bigint;
+}
+interface ContainedFileHandle {
+    close(): Promise<void>;
+    read(buffer: Buffer, offset: number, length: number, position: number | null): Promise<{
+        readonly bytesRead: number;
+    }>;
+    stat(): Promise<FileSnapshot & {
+        readonly isFile: () => boolean;
+    }>;
+}
+interface ContainedFileReadOperations {
+    readonly lstat: typeof lstat;
+    readonly open: (path: string, flags: number) => Promise<ContainedFileHandle>;
+    readonly realpath: typeof realpath;
+    readonly stat: (path: string) => Promise<FileSnapshot & {
+        readonly isDirectory: () => boolean;
+        readonly isFile: () => boolean;
+    }>;
+}
+export declare function readContainedRegularFile(input: {
+    readonly candidate: string;
+    readonly maxBytes: number;
+    readonly root: string;
+}, operations?: ContainedFileReadOperations): Promise<Buffer>;
 export declare function pathTraversesSymbolicLink(root: string, candidate: string): Promise<boolean>;
+export {};
 //# sourceMappingURL=filesystem-path-safety.d.ts.map

package/dist/filesystem-path-safety.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"filesystem-path-safety.d.ts","sourceRoot":"","sources":["../src/filesystem-path-safety.ts"],"names":[],"mappings":"AAGA,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC,CAclB"}
+{"version":3,"file":"filesystem-path-safety.d.ts","sourceRoot":"","sources":["../src/filesystem-path-safety.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAQ,QAAQ,EAAQ,MAAM,kBAAkB,CAAC;AAK/D,MAAM,MAAM,wBAAwB,GAChC,SAAS,GACT,QAAQ,GACR,SAAS,GACT,SAAS,GACT,SAAS,GACT,aAAa,CAAC;AAElB,qBAAa,sBAAuB,SAAQ,KAAK;IAC/C,QAAQ,CAAC,OAAO,EAAE,wBAAwB,CAAC;IAE3C,YAAY,OAAO,EAAE,wBAAwB,EAI5C;CACF;AAuBD,UAAU,YAAY;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IAClC,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC;IAClC,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAAC;CAChC;AAED,UAAU,mBAAmB;IAC3B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,IAAI,CACF,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,GAAG,IAAI,GACtB,OAAO,CAAC;QAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC3C,IAAI,IAAI,OAAO,CAAC,YAAY,GAAG;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAA;KAAE,CAAC,CAAC;CACpE;AAED,UAAU,2BAA2B;IACnC,QAAQ,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC;IAC7B,QAAQ,CAAC,IAAI,EAAE,CACb,IAAI,EAAE,MAAM,EACZ,KAAK,EAAE,MAAM,KACV,OAAO,CAAC,mBAAmB,CAAC,CAAC;IAClC,QAAQ,CAAC,QAAQ,EAAE,OAAO,QAAQ,CAAC;IACnC,QAAQ,CAAC,IAAI,EAAE,CACb,IAAI,EAAE,MAAM,KACT,OAAO,CAAC,YAAY,GAAG;QAC1B,QAAQ,CAAC,WAAW,EAAE,MAAM,OAAO,CAAC;QACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,OAAO,CAAC;KAChC,CAAC,CAAC;CACJ;AA0JD,wBAAsB,wBAAwB,CAAC,KAAK,EAAE;IACpD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,EAAE,UAAU,GAAE,2BAA6D,GAAG,OAAO,CAAC,MAAM,CAAC,CA2E7F;AAED,wBAAsB,yBAAyB,CAC7C,IAAI,EAAE,MAAM,EACZ,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,OAAO,CAAC,CAclB"}

package/dist/filesystem-path-safety.js

@@ -1,5 +1,231 @@
-import { lstat } from "node:fs/promises";
-import { join, relative, sep } from "node:path";
+import { constants } from "node:fs";
+import { lstat, open, realpath, stat } from "node:fs/promises";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+const READ_CHUNK_BYTES = 64 * 1024;
+export class ContainedFileReadError extends Error {
+    failure;
+    constructor(failure) {
+        super(`Contained file read failed: ${failure}.`);
+        this.name = "ContainedFileReadError";
+        this.failure = failure;
+    }
+}
+function errorCode(error) {
+    return typeof error === "object" && error !== null && "code" in error
+        ? String(error.code)
+        : undefined;
+}
+function contained(root, candidate) {
+    const relation = relative(root, candidate);
+    return (relation === "" ||
+        (!isAbsolute(relation) && relation !== ".." && !relation.startsWith(`..${sep}`)));
+}
+function sameIdentity(left, right) {
+    return String(left.dev) === String(right.dev) && String(left.ino) === String(right.ino);
+}
+const nodeContainedFileReadOperations = {
+    lstat,
+    async open(path, flags) {
+        const handle = await open(path, flags);
+        return {
+            close: () => handle.close(),
+            read: (buffer, offset, length, position) => handle.read(buffer, offset, length, position),
+            stat: () => handle.stat({ bigint: true })
+        };
+    },
+    realpath,
+    stat: (path) => stat(path, { bigint: true })
+};
+function sameSnapshot(left, right) {
+    return (sameIdentity(left, right) &&
+        String(left.size) === String(right.size) &&
+        String(left.mode) === String(right.mode) &&
+        String(left.mtimeMs) === String(right.mtimeMs) &&
+        String(left.ctimeMs) === String(right.ctimeMs));
+}
+function boundedSnapshotSize(snapshot, maxBytes) {
+    if (typeof snapshot.size === "bigint") {
+        return snapshot.size >= 0n && snapshot.size <= BigInt(maxBytes)
+            ? Number(snapshot.size)
+            : undefined;
+    }
+    return Number.isSafeInteger(snapshot.size) && snapshot.size >= 0 && snapshot.size <= maxBytes
+        ? snapshot.size
+        : undefined;
+}
+function readError(error, phase) {
+    if (error instanceof ContainedFileReadError) {
+        return error;
+    }
+    const code = errorCode(error);
+    if (code === "ELOOP") {
+        return new ContainedFileReadError("symlink");
+    }
+    if (code === "ENOENT" || code === "ENOTDIR") {
+        return new ContainedFileReadError(phase === "before-open" ? "missing" : "changed");
+    }
+    if (code === "EISDIR") {
+        return new ContainedFileReadError("invalid");
+    }
+    return new ContainedFileReadError("unavailable");
+}
+function assertByteLimit(maxBytes) {
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 0 || maxBytes >= Number.MAX_SAFE_INTEGER) {
+        throw new ContainedFileReadError("invalid");
+    }
+}
+async function assertNoSymbolicLinks(input) {
+    if (!contained(input.root, input.candidate)) {
+        throw new ContainedFileReadError("escape");
+    }
+    const relation = relative(input.root, input.candidate);
+    let current = input.root;
+    for (const segment of relation.split(sep).filter((value) => value.length > 0)) {
+        current = join(current, segment);
+        let metadata;
+        try {
+            metadata = await input.operations.lstat(current);
+        }
+        catch (error) {
+            throw readError(error, input.phase);
+        }
+        if (metadata.isSymbolicLink()) {
+            throw new ContainedFileReadError("symlink");
+        }
+    }
+}
+async function assertNamedFileMatchesHandle(input) {
+    await assertNoSymbolicLinks({
+        candidate: input.candidate,
+        operations: input.operations,
+        phase: input.phase,
+        root: input.root
+    });
+    let canonical;
+    try {
+        canonical = await input.operations.realpath(input.candidate);
+    }
+    catch (error) {
+        throw readError(error, input.phase);
+    }
+    if (!contained(input.root, canonical)) {
+        throw new ContainedFileReadError("escape");
+    }
+    let namedMetadata;
+    try {
+        namedMetadata = await input.operations.stat(canonical);
+    }
+    catch (error) {
+        throw readError(error, input.phase);
+    }
+    if (!namedMetadata.isFile() || !sameSnapshot(input.opened, namedMetadata)) {
+        throw new ContainedFileReadError("changed");
+    }
+}
+async function readAtMost(input) {
+    const chunks = [];
+    const readBuffer = Buffer.allocUnsafe(Math.min(READ_CHUNK_BYTES, input.expectedBytes));
+    let bytesReadTotal = 0;
+    while (bytesReadTotal < input.expectedBytes) {
+        const remaining = input.expectedBytes - bytesReadTotal;
+        let result;
+        try {
+            result = await input.handle.read(readBuffer, 0, Math.min(readBuffer.length, remaining), bytesReadTotal);
+        }
+        catch (error) {
+            throw readError(error, "after-open");
+        }
+        if (result.bytesRead === 0) {
+            return Buffer.concat(chunks, bytesReadTotal);
+        }
+        bytesReadTotal += result.bytesRead;
+        if (bytesReadTotal > input.expectedBytes) {
+            throw new ContainedFileReadError("changed");
+        }
+        chunks.push(Buffer.from(readBuffer.subarray(0, result.bytesRead)));
+    }
+    return Buffer.concat(chunks, bytesReadTotal);
+}
+export async function readContainedRegularFile(input, operations = nodeContainedFileReadOperations) {
+    assertByteLimit(input.maxBytes);
+    const lexicalRoot = resolve(input.root);
+    const lexicalCandidate = resolve(input.candidate);
+    if (!contained(lexicalRoot, lexicalCandidate)) {
+        throw new ContainedFileReadError("escape");
+    }
+    let root;
+    try {
+        root = await operations.realpath(lexicalRoot);
+        const rootMetadata = await operations.stat(root);
+        if (!rootMetadata.isDirectory()) {
+            throw new ContainedFileReadError("invalid");
+        }
+    }
+    catch (error) {
+        throw readError(error, "before-open");
+    }
+    const candidate = resolve(root, relative(lexicalRoot, lexicalCandidate));
+    await assertNoSymbolicLinks({
+        candidate,
+        operations,
+        phase: "before-open",
+        root
+    });
+    let handle;
+    try {
+        handle = await operations.open(candidate, constants.O_RDONLY | constants.O_NOFOLLOW);
+    }
+    catch (error) {
+        throw readError(error, "before-open");
+    }
+    let bytes;
+    let failure;
+    try {
+        const openedMetadata = await handle.stat();
+        const expectedBytes = boundedSnapshotSize(openedMetadata, input.maxBytes);
+        if (!openedMetadata.isFile() || expectedBytes === undefined) {
+            throw new ContainedFileReadError("invalid");
+        }
+        await assertNamedFileMatchesHandle({
+            candidate,
+            opened: openedMetadata,
+            operations,
+            phase: "after-open",
+            root
+        });
+        bytes = await readAtMost({
+            expectedBytes,
+            handle
+        });
+        const finalMetadata = await handle.stat();
+        if (!sameSnapshot(openedMetadata, finalMetadata) || bytes.length !== expectedBytes) {
+            throw new ContainedFileReadError("changed");
+        }
+        await assertNamedFileMatchesHandle({
+            candidate,
+            opened: openedMetadata,
+            operations,
+            phase: "after-open",
+            root
+        });
+    }
+    catch (error) {
+        failure = readError(error, "after-open");
+    }
+    try {
+        await handle.close();
+    }
+    catch (error) {
+        failure ??= readError(error, "after-open");
+    }
+    if (failure !== undefined) {
+        throw failure;
+    }
+    if (bytes === undefined) {
+        throw new ContainedFileReadError("unavailable");
+    }
+    return bytes;
+}
 export async function pathTraversesSymbolicLink(root, candidate) {
     const relation = relative(root, candidate);
     let current = root;

package/dist/filesystem-path-safety.js.map

@@ -1 +1 @@
-{"version":3,"file":"filesystem-path-safety.js","sourceRoot":"","sources":["../src/filesystem-path-safety.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAEhD,MAAM,CAAC,KAAK,UAAU,yBAAyB,CAC7C,IAAY,EACZ,SAAiB;IAEjB,MAAM,QAAQ,GAAG,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IAC3C,IAAI,OAAO,GAAG,IAAI,CAAC;IACnB,KAAK,MAAM,OAAO,IAAI,QAAQ,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,EAAE,CAAC;QAC9E,OAAO,GAAG,IAAI,CAAC,OAAO,EAAE,OAAO,CAAC,CAAC;QACjC,IAAI,CAAC;YACH,IAAI,CAAC,MAAM,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,cAAc,EAAE,EAAE,CAAC;gBAC5C,OAAO,IAAI,CAAC;YACd,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC"}
+{"version":3,"file":"filesystem-path-safety.js","sourceRoot":"","sources":["../src/filesystem-path-safety.ts"],"names":[],"mappings":"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"}

package/dist/foundation-config.d.ts

@@ -1,4 +1,4 @@
-declare const SUPPORTED_CAPABILITY_IDS: readonly ["package.public-api-compatibility", "repository.security-baseline", "quality.suppression-governance", "architecture.source-dependencies", "workspace.dependency-declarations"];
+declare const SUPPORTED_CAPABILITY_IDS: readonly ["contract.json-schema-releases", "contract.protobuf-evolution", "documentation.local-references", "governance.architecture-decisions", "package.public-api-compatibility", "repository.agent-workflow", "repository.security-baseline", "quality.suppression-governance", "architecture.source-dependencies", "workspace.dependency-declarations"];
 type SupportedCapabilityId = (typeof SUPPORTED_CAPABILITY_IDS)[number];
 interface DeclaredCapability {
     readonly id: SupportedCapabilityId;

package/dist/foundation-config.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"foundation-config.d.ts","sourceRoot":"","sources":["../src/foundation-config.ts"],"names":[],"mappings":"AAeA,QAAA,MAAM,wBAAwB,0LAMpB,CAAC;AAEX,KAAK,qBAAqB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvE,UAAU,kBAAkB;IAC1B,QAAQ,CAAC,EAAE,EAAE,qBAAqB,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,oBAAoB,EAAE,SAAS,kBAAkB,EAAE,CAAC;CAC9D;AAiCD,wBAAsB,oBAAoB,CACxC,YAAY,EAAE,MAAM,EACpB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,kBAAkB,CAAC,CA6B7B"}
+{"version":3,"file":"foundation-config.d.ts","sourceRoot":"","sources":["../src/foundation-config.ts"],"names":[],"mappings":"AA0BA,QAAA,MAAM,wBAAwB,8VAWpB,CAAC;AAEX,KAAK,qBAAqB,GAAG,CAAC,OAAO,wBAAwB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEvE,UAAU,kBAAkB;IAC1B,QAAQ,CAAC,EAAE,EAAE,qBAAqB,CAAC;IACnC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,oBAAoB,EAAE,SAAS,kBAAkB,EAAE,CAAC;CAC9D;AAiCD,wBAAsB,oBAAoB,CACxC,YAAY,EAAE,MAAM,EACpB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,kBAAkB,CAAC,CA6B7B"}

package/dist/foundation-config.js

@@ -1,14 +1,25 @@
+import { compareBinaryStrings } from "./binary-string-comparator.js";
 import { CapabilityInputError } from "./capability-runtime.js";
 import { assertSchema } from "./schema-catalog.js";
 import { loadStrictYamlFile } from "./strict-yaml.js";
 const FOUNDATION_CONFIG_PATH = "foundation.config.yaml";
 const PUBLIC_API_COMPATIBILITY_CAPABILITY = "package.public-api-compatibility";
+const JSON_SCHEMA_RELEASES_CAPABILITY = "contract.json-schema-releases";
+const PROTOBUF_EVOLUTION_CAPABILITY = "contract.protobuf-evolution";
+const DOCUMENTATION_LOCAL_REFERENCES_CAPABILITY = "documentation.local-references";
+const ARCHITECTURE_DECISIONS_CAPABILITY = "governance.architecture-decisions";
+const REPOSITORY_AGENT_WORKFLOW_CAPABILITY = "repository.agent-workflow";
 const SUPPRESSION_GOVERNANCE_CAPABILITY = "quality.suppression-governance";
 const REPOSITORY_SECURITY_BASELINE_CAPABILITY = "repository.security-baseline";
 const SOURCE_DEPENDENCIES_CAPABILITY = "architecture.source-dependencies";
 const WORKSPACE_DEPENDENCY_DECLARATIONS_CAPABILITY = "workspace.dependency-declarations";
 const SUPPORTED_CAPABILITY_IDS = [
+    JSON_SCHEMA_RELEASES_CAPABILITY,
+    PROTOBUF_EVOLUTION_CAPABILITY,
+    DOCUMENTATION_LOCAL_REFERENCES_CAPABILITY,
+    ARCHITECTURE_DECISIONS_CAPABILITY,
     PUBLIC_API_COMPATIBILITY_CAPABILITY,
+    REPOSITORY_AGENT_WORKFLOW_CAPABILITY,
     REPOSITORY_SECURITY_BASELINE_CAPABILITY,
     SUPPRESSION_GOVERNANCE_CAPABILITY,
     SOURCE_DEPENDENCIES_CAPABILITY,
@@ -59,7 +70,7 @@ export async function loadFoundationConfig(consumerRoot, signal) {
     }
     return Object.freeze({
         projectId: string(project["id"], "project.id"),
-        declaredCapabilities: Object.freeze(declaredCapabilities.toSorted((left, right) => left.id.localeCompare(right.id)))
+        declaredCapabilities: Object.freeze(declaredCapabilities.toSorted((left, right) => compareBinaryStrings(left.id, right.id)))
     });
 }
 //# sourceMappingURL=foundation-config.js.map

package/dist/foundation-config.js.map

@@ -1 +1 @@
-{"version":3,"file":"foundation-config.js","sourceRoot":"","sources":["../src/foundation-config.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"foundation-config.js","sourceRoot":"","sources":["../src/foundation-config.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -2,4 +2,7 @@ export { FOUNDATION_METADATA_SCHEMA_VERSION, inspectFoundationPackage, parseFoun
 export type { FoundationPackageSelfCheck } from "./package-self-check.js";
 export { FoundationError } from "./errors.js";
 export type { FoundationErrorCode } from "./errors.js";
+export * as localMode from "./local-mode/index.js";
+export { createFastCheckParameters, normalizeDeterministicSeedBank, normalizePropertyReplayEvidence, PropertyTestingEvidenceError } from "./capabilities/property-testing-standard/contract/deterministic-seed-bank.js";
+export type { DeterministicSeedBank, FastCheckParameters, PropertyReplayEvidence } from "./capabilities/property-testing-standard/contract/deterministic-seed-bank.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kCAAkC,EAClC,wBAAwB,EACxB,+BAA+B,EAChC,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kCAAkC,EAClC,wBAAwB,EACxB,+BAA+B,EAChC,MAAM,yBAAyB,CAAC;AACjC,YAAY,EAAE,0BAA0B,EAAE,MAAM,yBAAyB,CAAC;AAC1E,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,YAAY,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACvD,OAAO,KAAK,SAAS,MAAM,uBAAuB,CAAC;AACnD,OAAO,EACL,yBAAyB,EACzB,8BAA8B,EAC9B,+BAA+B,EAC/B,4BAA4B,EAC7B,MAAM,8EAA8E,CAAC;AACtF,YAAY,EACV,qBAAqB,EACrB,mBAAmB,EACnB,sBAAsB,EACvB,MAAM,8EAA8E,CAAC"}

package/dist/index.js

@@ -1,3 +1,5 @@
 export { FOUNDATION_METADATA_SCHEMA_VERSION, inspectFoundationPackage, parseFoundationPackageSelfCheck } from "./package-self-check.js";
 export { FoundationError } from "./errors.js";
+export * as localMode from "./local-mode/index.js";
+export { createFastCheckParameters, normalizeDeterministicSeedBank, normalizePropertyReplayEvidence, PropertyTestingEvidenceError } from "./capabilities/property-testing-standard/contract/deterministic-seed-bank.js";
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kCAAkC,EAClC,wBAAwB,EACxB,+BAA+B,EAChC,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,kCAAkC,EAClC,wBAAwB,EACxB,+BAA+B,EAChC,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,KAAK,SAAS,MAAM,uBAAuB,CAAC;AACnD,OAAO,EACL,yBAAyB,EACzB,8BAA8B,EAC9B,+BAA+B,EAC/B,4BAA4B,EAC7B,MAAM,8EAA8E,CAAC"}

package/dist/local-mode/attach-transaction.d.ts

@@ -0,0 +1,11 @@
+import type { AttachResult, FoundationStatus, ProcessRunner } from "./types.js";
+interface AttachTransactionInput {
+    readonly consumerPath: string;
+    readonly targetPath: string;
+    readonly runner: ProcessRunner;
+    readonly now: () => Date;
+    readonly readStatus: (consumerPath: string, ignoreOperationLock: boolean) => Promise<FoundationStatus>;
+}
+export declare function attachFoundation(input: AttachTransactionInput): Promise<AttachResult>;
+export {};
+//# sourceMappingURL=attach-transaction.d.ts.map

package/dist/local-mode/attach-transaction.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attach-transaction.d.ts","sourceRoot":"","sources":["../../src/local-mode/attach-transaction.ts"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EACV,YAAY,EAEZ,gBAAgB,EAChB,aAAa,EACd,MAAM,YAAY,CAAC;AAOpB,UAAU,sBAAsB;IAC9B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,GAAG,EAAE,MAAM,IAAI,CAAC;IACzB,QAAQ,CAAC,UAAU,EAAE,CACnB,YAAY,EAAE,MAAM,EACpB,mBAAmB,EAAE,OAAO,KACzB,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAChC;AA4SD,wBAAsB,gBAAgB,CACpC,KAAK,EAAE,sBAAsB,GAC5B,OAAO,CAAC,YAAY,CAAC,CAGvB"}