@agent-teams/docs-protocol 0.0.0

package/dist/application/docs-new-completion.js

@@ -0,0 +1,226 @@
+import { normalizeCodeAnchors, normalizeDocumentIds } from "../domain/document-semantics.js";
+import { DocsProfileError } from "../domain/profile-policy.js";
+import { catalogMatchesExpectedPostimage } from "./authority-handshake.js";
+const BINARY = (left, right) => Buffer.compare(Buffer.from(left), Buffer.from(right));
+const BLOCKER_STATUSES = new Set(["deferred", "open"]);
+const MAX_DIAGNOSTICS = 256;
+const MAX_CORPUS_ANCHOR_PATTERNS = 1_024;
+const MAX_CORPUS_ANCHOR_OCCURRENCES = 4_096;
+export function boundedDiagnostics(diagnostics) {
+    if (diagnostics.length <= MAX_DIAGNOSTICS) {
+        return Object.freeze([...diagnostics]);
+    }
+    return Object.freeze([
+        ...diagnostics.slice(0, MAX_DIAGNOSTICS - 1),
+        {
+            ruleId: "docs.diagnostics.overflow",
+            severity: "error",
+            phase: "authority",
+            subject: "docs.diagnostics",
+            message: `Diagnostics exceeded the deterministic ${MAX_DIAGNOSTICS}-item output budget; additional findings were omitted.`
+        }
+    ]);
+}
+export function inspectRecapturedAnchors(anchors, matchedPatterns) {
+    const matched = new Set(matchedPatterns);
+    const missing = anchors.filter(({ pattern }) => !matched.has(pattern));
+    return Object.freeze({
+        diagnostics: Object.freeze(missing.map(({ enforcement, pattern }) => ({
+            ruleId: enforcement === "required" ? "docs.code-anchor.required-stale" : "docs.code-anchor.advisory-unmatched",
+            severity: enforcement === "required" ? "error" : "warning",
+            phase: "authority",
+            subject: pattern,
+            message: enforcement === "required"
+                ? `Required code anchor ${pattern} no longer matches a current regular file.`
+                : `Advisory code anchor ${pattern} does not match a current regular file.`
+        }))),
+        requiredMissing: missing.some(({ enforcement }) => enforcement === "required")
+    });
+}
+export function mergeDiagnostics(...groups) {
+    const seen = new Set();
+    const merged = [];
+    for (const diagnostic of groups.flat()) {
+        const identity = `${diagnostic.ruleId}\0${diagnostic.severity}\0${diagnostic.phase}\0${diagnostic.subject}\0${diagnostic.message}`;
+        if (!seen.has(identity)) {
+            seen.add(identity);
+            merged.push(diagnostic);
+        }
+    }
+    return Object.freeze(merged);
+}
+function metadataStrings(value, subject) {
+    if (value === undefined) {
+        return Object.freeze([]);
+    }
+    if (!Array.isArray(value) || !value.every((entry) => typeof entry === "string")) {
+        throw new DocsProfileError(`${subject} must be an array of document IDs.`);
+    }
+    return value;
+}
+function semanticDiagnostic(subject, message) {
+    return { ruleId: "docs.metadata.common-semantics", severity: "error", phase: "authority", subject, message };
+}
+function inspectDocumentSemantics(document, byId) {
+    const related = normalizeDocumentIds(metadataStrings(document.metadata["related"], `${document.id}.related`), `${document.id}.related`);
+    const blockedBy = normalizeDocumentIds(metadataStrings(document.metadata["blocked_by"], `${document.id}.blocked_by`), `${document.id}.blocked_by`);
+    if (related.includes(document.id) || blockedBy.includes(document.id)) {
+        throw new DocsProfileError("A document cannot reference itself.");
+    }
+    for (const id of related) {
+        if (!byId.has(id)) {
+            throw new DocsProfileError(`Related document ${id} does not exist.`);
+        }
+    }
+    for (const id of blockedBy) {
+        if (!related.includes(id)) {
+            throw new DocsProfileError(`Blocker ${id} must also appear in related.`);
+        }
+        const blocker = byId.get(id);
+        if (blocker === undefined || blocker.type !== "open-decision" || !BLOCKER_STATUSES.has(blocker.status)) {
+            throw new DocsProfileError(`Blocker ${id} must be an open-decision with open or deferred status.`);
+        }
+    }
+    if ((document.status === "accepted" || document.status === "active") && blockedBy.length > 0) {
+        throw new DocsProfileError(`Document status ${document.status} cannot retain blockers.`);
+    }
+    const anchorsValue = document.metadata["code_anchors"];
+    return anchorsValue === undefined
+        ? []
+        : Array.isArray(anchorsValue)
+            ? normalizeCodeAnchors(anchorsValue)
+            : (() => { throw new DocsProfileError("code_anchors must be an array."); })();
+}
+export async function inspectCorpusSemantics(input) {
+    const diagnostics = [];
+    let diagnosticsOverflowed = false;
+    const pushDiagnostic = (diagnostic) => {
+        if (diagnostics.length < MAX_DIAGNOSTICS - 1) {
+            diagnostics.push(diagnostic);
+        }
+        else if (!diagnosticsOverflowed) {
+            diagnosticsOverflowed = true;
+            diagnostics.push({ ruleId: "docs.diagnostics.overflow", severity: "error", phase: "authority", subject: "docs.check", message: `Diagnostics exceeded the deterministic ${MAX_DIAGNOSTICS}-item output budget; additional findings were omitted.` });
+        }
+    };
+    const byId = new Map(input.catalog.documents.map((document) => [document.id, document]));
+    const anchorOwners = new Map();
+    let anchorOccurrences = 0;
+    let anchorBudgetExceeded = false;
+    for (const document of input.catalog.documents) {
+        try {
+            const anchors = inspectDocumentSemantics(document, byId);
+            for (const { enforcement, pattern } of anchors) {
+                if (anchorOccurrences >= MAX_CORPUS_ANCHOR_OCCURRENCES || (!anchorOwners.has(pattern) && anchorOwners.size >= MAX_CORPUS_ANCHOR_PATTERNS)) {
+                    anchorBudgetExceeded = true;
+                    continue;
+                }
+                anchorOccurrences += 1;
+                const owners = anchorOwners.get(pattern) ?? [];
+                owners.push({ enforcement, id: document.id });
+                anchorOwners.set(pattern, owners);
+            }
+        }
+        catch (error) {
+            pushDiagnostic(semanticDiagnostic(document.repositoryPath, error instanceof Error ? error.message : "Common metadata semantics are invalid."));
+        }
+    }
+    if (anchorBudgetExceeded) {
+        pushDiagnostic({ ruleId: "docs.code-anchor.corpus-budget-exceeded", severity: "error", phase: "authority", subject: "code_anchors", message: `Code anchors exceed the global corpus budget of ${MAX_CORPUS_ANCHOR_PATTERNS} unique patterns or ${MAX_CORPUS_ANCHOR_OCCURRENCES} occurrences.` });
+    }
+    const patterns = [...anchorOwners.keys()].toSorted(BINARY);
+    const matched = await input.anchors.matchedPatterns({ consumerRoot: input.consumerRoot, patterns, ...(input.signal === undefined ? {} : { signal: input.signal }) });
+    for (const pattern of patterns) {
+        if (!matched.includes(pattern)) {
+            for (const { enforcement, id } of anchorOwners.get(pattern) ?? []) {
+                pushDiagnostic({ ...semanticDiagnostic(id, `Code anchor ${pattern} does not match a current regular file.`), ruleId: enforcement === "required" ? "docs.code-anchor.required-unmatched" : "docs.code-anchor.advisory-unmatched", severity: enforcement === "required" ? "error" : "warning" });
+            }
+        }
+    }
+    return Object.freeze(diagnostics);
+}
+export async function completeDocsNewApply(input) {
+    if (input.receipt.outcome !== "applied" && input.receipt.outcome !== "already-applied") {
+        return { diagnostics: input.diagnostics, outcome: input.outcome };
+    }
+    let matchedAfterPublication;
+    try {
+        matchedAfterPublication = await input.anchors.matchedPatterns({
+            consumerRoot: input.consumerRoot,
+            patterns: input.codeAnchors.map(({ pattern }) => pattern),
+            ...(input.signal === undefined ? {} : { signal: input.signal })
+        });
+    }
+    catch (error) {
+        return {
+            diagnostics: [...input.diagnostics, {
+                    ruleId: "docs.code-anchor.post-publication-inspection-failed",
+                    severity: "error",
+                    phase: "authority",
+                    subject: input.plan.destination,
+                    message: `Published document code-anchor authority could not be verified; manual reconciliation is required: ${error instanceof Error ? error.message : "unknown inspection failure"}`
+                }],
+            outcome: "recovery-required",
+            writeState: "published-recovery-required"
+        };
+    }
+    const matched = new Set(matchedAfterPublication);
+    const missing = input.codeAnchors.filter(({ pattern }) => !matched.has(pattern));
+    const diagnostics = [...input.diagnostics];
+    for (const { enforcement, pattern } of missing) {
+        const diagnostic = {
+            ruleId: enforcement === "required" ? "docs.code-anchor.required-stale-after-publication" : "docs.code-anchor.advisory-unmatched",
+            severity: enforcement === "required" ? "error" : "warning",
+            phase: "authority",
+            subject: pattern,
+            message: enforcement === "required"
+                ? `Required code anchor ${pattern} no longer matches after publication; the published document requires manual reconciliation.`
+                : `Advisory code anchor ${pattern} does not match a current regular file.`
+        };
+        if (!diagnostics.some((entry) => entry.ruleId === diagnostic.ruleId && entry.subject === diagnostic.subject && entry.message === diagnostic.message)) {
+            diagnostics.push(diagnostic);
+        }
+    }
+    if (missing.some(({ enforcement }) => enforcement === "required")) {
+        return {
+            diagnostics,
+            outcome: "recovery-required",
+            writeState: "published-recovery-required"
+        };
+    }
+    let catalog;
+    try {
+        catalog = await input.foundation.buildCatalog({
+            consumerRoot: input.consumerRoot,
+            profilePath: input.profilePath,
+            ...(input.signal === undefined ? {} : { signal: input.signal })
+        });
+    }
+    catch (error) {
+        return {
+            diagnostics: [...diagnostics, {
+                    ruleId: "docs.new.catalog-postimage-unavailable",
+                    severity: "error",
+                    phase: "apply",
+                    subject: input.plan.destination,
+                    message: `Published document catalog postimage could not be verified; manual reconciliation is required: ${error instanceof Error ? error.message : "unknown catalog failure"}`
+                }],
+            outcome: "recovery-required",
+            writeState: "published-recovery-required"
+        };
+    }
+    if (!catalogMatchesExpectedPostimage(input.plan, catalog)) {
+        return {
+            diagnostics: [...diagnostics, {
+                    ruleId: "docs.new.catalog-postimage-mismatch",
+                    severity: "error",
+                    phase: "apply",
+                    subject: input.plan.destination,
+                    message: "Published document catalog does not match the Plan expected postimage; no reachability action was issued."
+                }],
+            outcome: "execution-failure"
+        };
+    }
+    return { diagnostics, outcome: "success", reachability: input.reachability };
+}
+//# sourceMappingURL=docs-new-completion.js.map

package/dist/application/docs-new-completion.js.map

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

package/dist/application/docs-protocol.d.ts

@@ -0,0 +1,168 @@
+import { DOCS_PROTOCOL_ID, DOCS_PROTOCOL_VERSION, type DocsExecution, type DocsFindQuery, type DocsNewResult, type DocsNewRequest, type DocsProfileReader, type CodeAnchorMatcher, type DocsAdoptionInspector, type FoundationDocsPort } from "../domain/model.js";
+export declare class DocsProtocol {
+    #private;
+    constructor(input: {
+        readonly adoption: DocsAdoptionInspector;
+        readonly anchors: CodeAnchorMatcher;
+        readonly foundation: FoundationDocsPort;
+        readonly profiles: DocsProfileReader;
+    });
+    info(input: {
+        readonly consumerRoot: string;
+        readonly profilePath: string;
+        readonly signal?: AbortSignal;
+    }): Promise<DocsExecution<Readonly<{
+        kind: "info";
+        projectId: string;
+        protocol: {
+            readonly id: typeof DOCS_PROTOCOL_ID;
+            readonly version: typeof DOCS_PROTOCOL_VERSION;
+        };
+        foundationProfile: {
+            readonly metadataSidecarPolicy: "foundation-profile-v2-strict-merge";
+            readonly path: string;
+            readonly schemaVersion: 2;
+        };
+        agentWorkflow: {
+            readonly skillPath: string;
+        };
+        metadataSchemaPath: string;
+        metadataSidecar: {
+            readonly kind: "none";
+        } | {
+            readonly kind: "path-metadata-map";
+            readonly path: string;
+        };
+        ownerIds: readonly string[];
+        types: readonly import("../domain/model.js").DocsTypeProfile[];
+        semanticValidatorIds: readonly string[];
+    }>>>;
+    find(input: {
+        readonly consumerRoot: string;
+        readonly profilePath: string;
+        readonly query: DocsFindQuery;
+        readonly signal?: AbortSignal;
+    }): Promise<DocsExecution<Readonly<{
+        kind: "find";
+        matches: number;
+        documents: readonly import("../domain/model.js").DocsFindDocument[];
+    }>>>;
+    newDocument(request: DocsNewRequest): Promise<DocsExecution<DocsNewResult>>;
+    doctor(input: {
+        readonly consumerRoot: string;
+        readonly profilePath: string;
+        readonly signal?: AbortSignal;
+    }): Promise<DocsExecution<Readonly<{
+        kind: "doctor";
+        protocol: Readonly<{
+            id: "agent-teams.docs-protocol";
+            version: 1;
+        }>;
+        projectId?: string;
+        environment: {
+            readonly installedFoundationVersion: string;
+            readonly installedFoundationBuildIdentity: string;
+            readonly filesystem: {
+                readonly basis: "platform-contract";
+                readonly strictDirectoryDurability: "platform-supported" | "platform-unsupported";
+            };
+        };
+        transaction: Readonly<{
+            state: "idle";
+        }> | Readonly<{
+            state: "recoverable";
+            transactionKind: "document";
+            recovery: Readonly<{
+                commandId: "docs.recover";
+                args: Readonly<{
+                    exactFoundationBuildIdentity: string;
+                    exactFoundationVersion: string;
+                }>;
+            }>;
+        }> | Readonly<{
+            state: "manual-recovery-required";
+            transactionKind?: "corrupt" | "document" | "local-mode" | "scaffold" | "transition-residue" | "unknown" | "version-mismatch";
+            reason: string;
+            recovery?: {
+                readonly commandId: "detach" | "docs-recover" | "scaffold-recover";
+                readonly args: Readonly<Record<string, string>>;
+            };
+        }>;
+    }>>>;
+    recover(input: {
+        readonly consumerRoot: string;
+        readonly profilePath: string;
+        readonly signal?: AbortSignal;
+    }): Promise<DocsExecution<Readonly<{
+        kind: "recover";
+        transactionState: "no-pending-transaction";
+        writeState: "unchanged";
+    }>> | DocsExecution<Readonly<{
+        kind: "recover";
+        transactionState: "manual-required";
+        writeState: "unknown";
+        transaction: Readonly<{
+            state: "idle";
+        }> | Readonly<{
+            state: "recoverable";
+            transactionKind: "document";
+            recovery: Readonly<{
+                commandId: "docs.recover";
+                args: Readonly<{
+                    exactFoundationBuildIdentity: string;
+                    exactFoundationVersion: string;
+                }>;
+            }>;
+        }> | Readonly<{
+            state: "manual-recovery-required";
+            transactionKind?: "corrupt" | "document" | "local-mode" | "scaffold" | "transition-residue" | "unknown" | "version-mismatch";
+            reason: string;
+            recovery?: {
+                readonly commandId: "detach" | "docs-recover" | "scaffold-recover";
+                readonly args: Readonly<Record<string, string>>;
+            };
+        }>;
+    }>> | DocsExecution<Readonly<{
+        kind: "recover";
+        transactionState: "recovered" | "recovery-required";
+        writeState: "committed" | "published-recovery-required" | "unchanged" | "unknown";
+        receiptDigest: `sha256:${string}`;
+        receipt: Readonly<{
+            outcome: import("@agent-teams/engineering-foundation/document-authoring").DocumentReceiptOutcome;
+            commit: Readonly<{
+                state: "committed" | "manual-recovery-required" | "not-published" | "recovery-required";
+                publication: "none" | "preexisting-exact" | "published" | "unknown";
+                recoverability: "not-required" | "preserved-for-recovery";
+            }>;
+            directoryMaterialization?: {
+                readonly state: "none-created" | "created-and-retained" | "preserved-unknown";
+                readonly plannedDirectories: readonly string[];
+                readonly observedCreatedDirectories: readonly string[];
+            };
+        }>;
+    }>>>;
+    check(input: {
+        readonly consumerRoot: string;
+        readonly profilePath: string;
+        readonly signal?: AbortSignal;
+    }): Promise<DocsExecution<Readonly<{
+        kind: "check";
+        projectId: string;
+        catalogStatus: "complete" | "partial";
+        documents: number;
+        foundationProfile: {
+            readonly metadataSidecarPolicy: "foundation-profile-v2-strict-merge";
+            readonly path: string;
+            readonly schemaVersion: 2;
+        };
+        metadataSidecar: {
+            readonly kind: "none";
+        } | {
+            readonly kind: "path-metadata-map";
+            readonly path: string;
+        };
+        semanticValidatorIds: readonly string[];
+        valid: boolean;
+    }>>>;
+}
+//# sourceMappingURL=docs-protocol.d.ts.map

package/dist/application/docs-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"docs-protocol.d.ts","sourceRoot":"","sources":["../../src/application/docs-protocol.ts"],"names":[],"mappings":"AAKA,OAAO,EACL,gBAAgB,EAChB,qBAAqB,EAKrB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,qBAAqB,EAE1B,KAAK,kBAAkB,EACxB,MAAM,oBAAoB,CAAC;AAkL5B,qBAAa,YAAY;;IAMvB,YAAY,KAAK,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,qBAAqB,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;QAAC,QAAQ,CAAC,UAAU,EAAE,kBAAkB,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,iBAAiB,CAAA;KAAE,EAKlL;IAEK,IAAI,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE;cAItG,MAAM;;;;;;;;;;;;;;;;;;;;;;;;SAYf;IAEK,IAAI,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;QAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE;cAsB9E,MAAM;;;SACtE;IAEK,WAAW,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,aAAa,CAAC,aAAa,CAAC,CAAC,CA4IhF;IAEK,MAAM,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE;cAiCxG,QAAQ;;;;;;;;;;;;;;;mBA9Pc,MAAM;;mBAI3B,aAAa;6BACH,UAAU;;2BAEd,cAAc;;;;;;;mBAStB,0BAA0B;;;;;;;;SAoPlC;IAEK,OAAO,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE;cAG7C,SAAS;0BAA6B,wBAAwB;oBAAuB,WAAW;;cAGtF,SAAS;0BAA6B,iBAAiB;oBAAuB,SAAS;;mBA5QvI,MAAM;;mBAI3B,aAAa;6BACH,UAAU;;2BAEd,cAAc;;;;;;;mBAStB,0BAA0B;;;;;;;;;cAgQzB,SAAS;;;;;;;;;;;;;;;;;SAMlB;IAEK,KAAK,CAAC,KAAK,EAAE;QAAE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;KAAE;cAyBzB,OAAO;;;;;;;;;;;;;;;;;SAC9F;CACF"}