@ybotok/loam 0.1.0-beta.3 → 0.2.0-alpha.1

package/dist/core/gate/checks.js

@@ -0,0 +1,201 @@
+/**
+ * The four checks behind `loam gate` — a can-i-deploy-shaped PURE QUERY over
+ * evidence other commands already recorded. Nothing here executes anything,
+ * writes anything, takes the docs lock, or re-derives a coherence plan: every
+ * answer is either already on disk (verification.yaml, vouch stamps, the
+ * commit journal) or a presence/landscape fact the enumeration carries.
+ *
+ *   partners      the landscape's direct joins, both ends graded on the ladder
+ *   freshness     content.stale / sources.stale over the target and partners,
+ *                 plus the one integrity error that makes freshness
+ *                 unjudgeable (frontmatter.malformed) and a refusing decode
+ *                 of the spec bytes themselves
+ *   verification  verificationState per active feature touching the service
+ *                 (its own module, `./verification.ts`)
+ *   interrupted   the `.loam-commit` journal — the one repo state that poisons
+ *                 every other answer above
+ *
+ * Every `gate.*` code is spelled as a literal `code:` property at its emit
+ * site, never through a code-taking factory parameter — verifyStep
+ * (core/status/verification.ts) records that test/codes-drift.test.ts's
+ * collector is blind to the parameter form, and a refactor toward a factory
+ * would silently undocument the family.
+ */
+import { existsSync } from "node:fs";
+import { inOrder } from "../kernel/concurrency.js";
+import { serviceProvenance } from "../provenance/findings.js";
+import { interruptedCommitFinding } from "../staging/recovery/finding.js";
+import { servicePathsAt, SPEC_AXES } from "../repo/paths.js";
+import { serviceTreePath } from "../kernel/ids/dirs.js";
+import { locateServicePaths } from "../repo/service-target.js";
+import { atLeastDocumented, partnerScan } from "./partners.js";
+import { verificationCheck } from "./verification.js";
+import { unreadableSubject } from "./report.js";
+export async function gateReport(req) {
+    // The scan first, alone: freshness walks the partner set it derives. The
+    // three remaining checks are independent of each other — different files,
+    // memoized reads — so they run concurrently; only the scan must be ordered.
+    const scan = await partnerScan({ docsDir: req.docsDir, service: req.service, fleet: req.fleet });
+    const [freshness, verification, interrupted] = await Promise.all([
+        freshnessFindings(req, scan),
+        verificationCheck({ docsDir: req.docsDir, service: req.service, fleet: req.fleet }),
+        interruptedCommitFinding(req.docsDir),
+    ]);
+    const checks = [
+        { check: "partners", findings: partnersFindings(scan, req.service) },
+        { check: "freshness", findings: freshness },
+        { check: "verification", findings: verification.findings },
+        { check: "interrupted", findings: interrupted === null ? [] : [interrupted] },
+    ];
+    return {
+        service: req.service,
+        landscape: scan.landscape,
+        partners: scan.partners,
+        features: verification.features,
+        checks,
+    };
+}
+/* ------------------------------------------------------------------ */
+/* Check 1: partners                                                   */
+/* ------------------------------------------------------------------ */
+function partnersFindings(scan, service) {
+    const findings = [];
+    // "Could not look" must never read as "no partners" — the docsRepoReady
+    // doctrine one level down. `validate --all` owns the diagnosis of the
+    // landscape itself; this code only refuses the false silence. The two ways
+    // of not looking are graded apart, the way `landscape.missing` and
+    // `landscape.invalid` are: ABSENT is a warning — a repo before its first
+    // adopt legitimately has no map yet — but a map that EXISTS and cannot be
+    // parsed or read is an ERROR, because `validate --all` fails that repo
+    // (`landscape.invalid`) and a deploy gate that passed where the fleet gate
+    // fails would be the quieter of two contradictory verdicts.
+    if (scan.landscape === "absent") {
+        findings.push({
+            severity: "warn",
+            code: "gate.partners-unknown",
+            message: `architecture/landscape.likec4 does not exist, so the partner set for '${service}' could not be derived — an absent map means nobody could look, not that nothing joins this service. \`loam validate --all\` diagnoses the landscape itself.`,
+        });
+    }
+    else if (scan.landscape === "invalid") {
+        findings.push({
+            severity: "error",
+            code: "gate.partners-unknown",
+            message: `architecture/landscape.likec4 exists but cannot be used — ${scan.landscapeProblem ?? "it did not parse"} — so the partner set for '${service}' could not be derived. ` +
+                `A broken map means nobody could look, not that nothing joins this service, and \`loam validate --all\` fails this repo for the same file. Fix the landscape, then re-run.`,
+        });
+    }
+    // The rung depends on the landscape only through the api question (does
+    // anything call this service?). With no readable map that question is
+    // unanswerable, and the fail-closed grading — `landscapeEvidence`: no proof
+    // means an API is expected — would convict a worker or UI for a contract
+    // nobody may be owed. One unanswerable fact yields ONE finding (the
+    // landscape's own, above), so under an unreadable map this error fires only
+    // when the service is below `documented` REGARDLESS of the api question.
+    const target = scan.landscape === "read" ? scan.target : scan.targetWithoutApi;
+    if (!atLeastDocumented(target.maturity)) {
+        findings.push({
+            severity: "error",
+            code: "gate.service-undocumented",
+            subject: service,
+            message: `${serviceTreePath(scan.targetEntry)}/ sits at '${target.maturity}' on the adoption ladder — below 'documented', the docs cannot say what its joins even are, so no recorded evidence can answer the deploy question. ` +
+                `Author the baseline (\`loam adopt --service ${service}\` briefs it); this check passes once the required artifact set exists.`,
+            details: target.gaps,
+            text: { detailPrefix: "- " },
+        });
+    }
+    // The partners that HAVE a directory, by id: their findings name it, and it
+    // is `services/<subsystem>/<id>/` for a filed one. The no-directory branch
+    // below keeps the bare `services/<id>/` spelling deliberately — there is no
+    // directory to name, and the unfiled form is what the fix would create.
+    const partnerPath = new Map(scan.partnerEntries.map((e) => [e.id, serviceTreePath(e)]));
+    for (const p of scan.partners) {
+        // An `#external` partner is somebody else's system: its side of the join
+        // is unrecorded ON PURPOSE, the same exemption the landscape census grants
+        // (`landscape.service-undocumented` skips #external too).
+        if (p.external)
+            continue;
+        if (p.maturity === null) {
+            findings.push({
+                severity: "warn",
+                code: "gate.partner-undocumented",
+                subject: p.service,
+                message: `'${p.service}' joins '${service}' (${p.via.join(", ")}) but has no services/${p.service}/ directory — its side of the join is unrecorded. ` +
+                    `Adopt it, bind its landscape element to the right service with metadata { service '<id>' }, or tag it #external if it is not ours.`,
+                details: p.via,
+            });
+        }
+        else if (!atLeastDocumented(p.maturity)) {
+            findings.push({
+                severity: "warn",
+                code: "gate.partner-undocumented",
+                subject: p.service,
+                message: `${partnerPath.get(p.service) ?? `services/${p.service}`}/ sits at '${p.maturity}' — below 'documented' — while it joins '${service}' (${p.via.join(", ")}): its side of the join is not fully recorded. \`loam adopt --service ${p.service}\` briefs what is missing.`,
+                details: p.via,
+            });
+        }
+    }
+    return findings;
+}
+/* ------------------------------------------------------------------ */
+/* Check 2: freshness                                                  */
+/* ------------------------------------------------------------------ */
+/**
+ * `serviceProvenance` filtered to the two staleness codes plus the ONE
+ * integrity error that makes freshness unjudgeable: `frontmatter.malformed`.
+ * A header YAML refuses to parse cannot certify a `content_digest`, and
+ * dropping that error read "cannot judge" as "nothing stale" — the exact
+ * fail-open a deploy gate must not have. Everything else provenance grades
+ * (missing owners, unstamped sources, absent frontmatter) is `validate`'s
+ * report to make — a deploy gate that repeated it would drown the findings a
+ * pipeline can actually act on at deploy time.
+ */
+async function freshnessFindings(req, scan) {
+    const subjects = [
+        {
+            id: req.service,
+            repoDir: req.repoDir,
+            paths: await locateServicePaths(req.docsDir, req.service, req.fleet),
+        },
+        // Only the DOCUMENTED partners: a partner with no directory has nothing to
+        // grade, and already carries gate.partner-undocumented from check 1.
+        ...scan.partnerEntries.map((e) => ({
+            id: e.id,
+            repoDir: undefined,
+            paths: servicePathsAt(e.dir),
+        })),
+    ];
+    // Independent per-subject reads through the shared memo; inOrder keeps the
+    // findings in subject order (target first, partners sorted) so identical
+    // state yields identical bytes.
+    const graded = await inOrder(subjects, async (s) => {
+        try {
+            // The integrity gate serviceProvenance cannot give: its own reads decode
+            // with 'utf8', which silently turns UTF-16 bytes into replacement
+            // characters — the file then grades as having no frontmatter at all (a
+            // warning this check does not retain), and mangled bytes read as
+            // "nothing stale". So both spec axes are decoded FIRST through the
+            // invocation's read index, whose decoder refuses non-UTF-8 naming the
+            // file (NotUtf8DocumentError spells `path` the way Node does, so the
+            // containment below names it without knowing the type).
+            for (const axis of SPEC_AXES) {
+                const path = s.paths[axis.key];
+                if (existsSync(path))
+                    await req.fleet.readText(path);
+            }
+            const all = await serviceProvenance(req.docsDir, s.id, { repoDir: s.repoDir, fleet: req.fleet });
+            return all
+                .filter((f) => f.code === "content.stale" ||
+                f.code === "sources.stale" ||
+                f.code === "frontmatter.malformed")
+                // The staleness emitters name the file in the message but set no
+                // subject; the payload's per-service attribution should not make a
+                // caller parse it back out of prose.
+                .map((f) => (f.subject === undefined ? { ...f, subject: s.id } : f));
+        }
+        catch (err) {
+            return [unreadableSubject("service", s.id, err)];
+        }
+    });
+    return graded.flat();
+}
+//# sourceMappingURL=checks.js.map

package/dist/core/gate/checks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"checks.js","sourceRoot":"","sources":["../../../src/core/gate/checks.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The four checks behind `loam gate` — a can-i-deploy-shaped PURE QUERY over\n * evidence other commands already recorded. Nothing here executes anything,\n * writes anything, takes the docs lock, or re-derives a coherence plan: every\n * answer is either already on disk (verification.yaml, vouch stamps, the\n * commit journal) or a presence/landscape fact the enumeration carries.\n *\n *   partners      the landscape's direct joins, both ends graded on the ladder\n *   freshness     content.stale / sources.stale over the target and partners,\n *                 plus the one integrity error that makes freshness\n *                 unjudgeable (frontmatter.malformed) and a refusing decode\n *                 of the spec bytes themselves\n *   verification  verificationState per active feature touching the service\n *                 (its own module, `./verification.ts`)\n *   interrupted   the `.loam-commit` journal — the one repo state that poisons\n *                 every other answer above\n *\n * Every `gate.*` code is spelled as a literal `code:` property at its emit\n * site, never through a code-taking factory parameter — verifyStep\n * (core/status/verification.ts) records that test/codes-drift.test.ts's\n * collector is blind to the parameter form, and a refactor toward a factory\n * would silently undocument the family.\n */\nimport { existsSync } from \"node:fs\";\nimport { inOrder } from \"../kernel/concurrency.js\";\nimport { serviceProvenance } from \"../provenance/findings.js\";\nimport { interruptedCommitFinding } from \"../staging/recovery/finding.js\";\nimport { servicePathsAt, SPEC_AXES, type ServicePaths } from \"../repo/paths.js\";\nimport { serviceTreePath } from \"../kernel/ids/dirs.js\";\nimport { locateServicePaths } from \"../repo/service-target.js\";\nimport type { Finding } from \"../vocabulary/report.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\nimport type { RawServiceId } from \"../kernel/ids/service.js\";\nimport { atLeastDocumented, partnerScan, type PartnerScan } from \"./partners.js\";\nimport { verificationCheck } from \"./verification.js\";\nimport { unreadableSubject, type GateCheck, type GateReport } from \"./report.js\";\n\nexport interface GateRequest {\n  docsDir: DocsDir;\n  /** The service being deployed — a name the enumeration approved. */\n  service: RawServiceId;\n  /**\n   * The repository loam is standing in, passed ONLY when the gated service is\n   * this repo's own binding — validate's `repoOf` rule: `sources` are paths\n   * into a service's own repository, so `sources.stale` is honestly checkable\n   * only there, while `content.stale` needs nothing but the document.\n   */\n  repoDir?: string;\n  fleet: FleetContext;\n}\n\nexport async function gateReport(req: GateRequest): Promise<GateReport> {\n  // The scan first, alone: freshness walks the partner set it derives. The\n  // three remaining checks are independent of each other — different files,\n  // memoized reads — so they run concurrently; only the scan must be ordered.\n  const scan = await partnerScan({ docsDir: req.docsDir, service: req.service, fleet: req.fleet });\n  const [freshness, verification, interrupted] = await Promise.all([\n    freshnessFindings(req, scan),\n    verificationCheck({ docsDir: req.docsDir, service: req.service, fleet: req.fleet }),\n    interruptedCommitFinding(req.docsDir),\n  ]);\n  const checks: GateCheck[] = [\n    { check: \"partners\", findings: partnersFindings(scan, req.service) },\n    { check: \"freshness\", findings: freshness },\n    { check: \"verification\", findings: verification.findings },\n    { check: \"interrupted\", findings: interrupted === null ? [] : [interrupted] },\n  ];\n  return {\n    service: req.service,\n    landscape: scan.landscape,\n    partners: scan.partners,\n    features: verification.features,\n    checks,\n  };\n}\n\n/* ------------------------------------------------------------------ */\n/* Check 1: partners                                                   */\n/* ------------------------------------------------------------------ */\n\nfunction partnersFindings(scan: PartnerScan, service: string): Finding[] {\n  const findings: Finding[] = [];\n  // \"Could not look\" must never read as \"no partners\" — the docsRepoReady\n  // doctrine one level down. `validate --all` owns the diagnosis of the\n  // landscape itself; this code only refuses the false silence. The two ways\n  // of not looking are graded apart, the way `landscape.missing` and\n  // `landscape.invalid` are: ABSENT is a warning — a repo before its first\n  // adopt legitimately has no map yet — but a map that EXISTS and cannot be\n  // parsed or read is an ERROR, because `validate --all` fails that repo\n  // (`landscape.invalid`) and a deploy gate that passed where the fleet gate\n  // fails would be the quieter of two contradictory verdicts.\n  if (scan.landscape === \"absent\") {\n    findings.push({\n      severity: \"warn\",\n      code: \"gate.partners-unknown\",\n      message: `architecture/landscape.likec4 does not exist, so the partner set for '${service}' could not be derived — an absent map means nobody could look, not that nothing joins this service. \\`loam validate --all\\` diagnoses the landscape itself.`,\n    });\n  } else if (scan.landscape === \"invalid\") {\n    findings.push({\n      severity: \"error\",\n      code: \"gate.partners-unknown\",\n      message:\n        `architecture/landscape.likec4 exists but cannot be used — ${scan.landscapeProblem ?? \"it did not parse\"} — so the partner set for '${service}' could not be derived. ` +\n        `A broken map means nobody could look, not that nothing joins this service, and \\`loam validate --all\\` fails this repo for the same file. Fix the landscape, then re-run.`,\n    });\n  }\n  // The rung depends on the landscape only through the api question (does\n  // anything call this service?). With no readable map that question is\n  // unanswerable, and the fail-closed grading — `landscapeEvidence`: no proof\n  // means an API is expected — would convict a worker or UI for a contract\n  // nobody may be owed. One unanswerable fact yields ONE finding (the\n  // landscape's own, above), so under an unreadable map this error fires only\n  // when the service is below `documented` REGARDLESS of the api question.\n  const target = scan.landscape === \"read\" ? scan.target : scan.targetWithoutApi;\n  if (!atLeastDocumented(target.maturity)) {\n    findings.push({\n      severity: \"error\",\n      code: \"gate.service-undocumented\",\n      subject: service,\n      message:\n        `${serviceTreePath(scan.targetEntry)}/ sits at '${target.maturity}' on the adoption ladder — below 'documented', the docs cannot say what its joins even are, so no recorded evidence can answer the deploy question. ` +\n        `Author the baseline (\\`loam adopt --service ${service}\\` briefs it); this check passes once the required artifact set exists.`,\n      details: target.gaps,\n      text: { detailPrefix: \"- \" },\n    });\n  }\n  // The partners that HAVE a directory, by id: their findings name it, and it\n  // is `services/<subsystem>/<id>/` for a filed one. The no-directory branch\n  // below keeps the bare `services/<id>/` spelling deliberately — there is no\n  // directory to name, and the unfiled form is what the fix would create.\n  const partnerPath = new Map(scan.partnerEntries.map((e) => [e.id as string, serviceTreePath(e)]));\n  for (const p of scan.partners) {\n    // An `#external` partner is somebody else's system: its side of the join\n    // is unrecorded ON PURPOSE, the same exemption the landscape census grants\n    // (`landscape.service-undocumented` skips #external too).\n    if (p.external) continue;\n    if (p.maturity === null) {\n      findings.push({\n        severity: \"warn\",\n        code: \"gate.partner-undocumented\",\n        subject: p.service,\n        message:\n          `'${p.service}' joins '${service}' (${p.via.join(\", \")}) but has no services/${p.service}/ directory — its side of the join is unrecorded. ` +\n          `Adopt it, bind its landscape element to the right service with metadata { service '<id>' }, or tag it #external if it is not ours.`,\n        details: p.via,\n      });\n    } else if (!atLeastDocumented(p.maturity)) {\n      findings.push({\n        severity: \"warn\",\n        code: \"gate.partner-undocumented\",\n        subject: p.service,\n        message:\n          `${partnerPath.get(p.service) ?? `services/${p.service}`}/ sits at '${p.maturity}' — below 'documented' — while it joins '${service}' (${p.via.join(\", \")}): its side of the join is not fully recorded. \\`loam adopt --service ${p.service}\\` briefs what is missing.`,\n        details: p.via,\n      });\n    }\n  }\n  return findings;\n}\n\n/* ------------------------------------------------------------------ */\n/* Check 2: freshness                                                  */\n/* ------------------------------------------------------------------ */\n\n/**\n * `serviceProvenance` filtered to the two staleness codes plus the ONE\n * integrity error that makes freshness unjudgeable: `frontmatter.malformed`.\n * A header YAML refuses to parse cannot certify a `content_digest`, and\n * dropping that error read \"cannot judge\" as \"nothing stale\" — the exact\n * fail-open a deploy gate must not have. Everything else provenance grades\n * (missing owners, unstamped sources, absent frontmatter) is `validate`'s\n * report to make — a deploy gate that repeated it would drown the findings a\n * pipeline can actually act on at deploy time.\n */\nasync function freshnessFindings(req: GateRequest, scan: PartnerScan): Promise<Finding[]> {\n  const subjects: { id: RawServiceId; repoDir: string | undefined; paths: ServicePaths }[] = [\n    {\n      id: req.service,\n      repoDir: req.repoDir,\n      paths: await locateServicePaths(req.docsDir, req.service, req.fleet),\n    },\n    // Only the DOCUMENTED partners: a partner with no directory has nothing to\n    // grade, and already carries gate.partner-undocumented from check 1.\n    ...scan.partnerEntries.map((e) => ({\n      id: e.id,\n      repoDir: undefined,\n      paths: servicePathsAt(e.dir),\n    })),\n  ];\n  // Independent per-subject reads through the shared memo; inOrder keeps the\n  // findings in subject order (target first, partners sorted) so identical\n  // state yields identical bytes.\n  const graded = await inOrder(subjects, async (s) => {\n    try {\n      // The integrity gate serviceProvenance cannot give: its own reads decode\n      // with 'utf8', which silently turns UTF-16 bytes into replacement\n      // characters — the file then grades as having no frontmatter at all (a\n      // warning this check does not retain), and mangled bytes read as\n      // \"nothing stale\". So both spec axes are decoded FIRST through the\n      // invocation's read index, whose decoder refuses non-UTF-8 naming the\n      // file (NotUtf8DocumentError spells `path` the way Node does, so the\n      // containment below names it without knowing the type).\n      for (const axis of SPEC_AXES) {\n        const path = s.paths[axis.key];\n        if (existsSync(path)) await req.fleet.readText(path);\n      }\n      const all = await serviceProvenance(req.docsDir, s.id, { repoDir: s.repoDir, fleet: req.fleet });\n      return all\n        .filter(\n          (f) =>\n            f.code === \"content.stale\" ||\n            f.code === \"sources.stale\" ||\n            f.code === \"frontmatter.malformed\",\n        )\n        // The staleness emitters name the file in the message but set no\n        // subject; the payload's per-service attribution should not make a\n        // caller parse it back out of prose.\n        .map((f) => (f.subject === undefined ? { ...f, subject: s.id } : f));\n    } catch (err) {\n      return [unreadableSubject(\"service\", s.id, err)];\n    }\n  });\n  return graded.flat();\n}\n"]}

package/dist/core/gate/partners.js

@@ -0,0 +1,205 @@
+/**
+ * The direct join partners of one service, derived from the LIVING landscape,
+ * and the maturity grading of everything on either end of a join.
+ *
+ * The landscape is the only place the fleet's joins are drawn, so the partner
+ * set is exactly the edges whose resolved source or target is the gated
+ * service — resolved through `serviceResolver` with the ENUMERATED fleet
+ * riding in, the same ride that keeps container-modelling landscapes attached
+ * everywhere else (an edge into `paymentService.api` is an edge into the
+ * service that owns it). A landscape that is absent or does not parse yields
+ * NO partner set, never an empty one: `landscape` says which, and the check
+ * layer turns "could not look" into `gate.partners-unknown` rather than
+ * letting it read as "no partners".
+ */
+import { existsSync } from "node:fs";
+import {} from "../c4/likec4.js";
+import { serviceResolver } from "../c4/resolve/service.js";
+import { ACTOR_KINDS, EXTERNAL_TAG, landscapeEvidence, maturityGaps, serviceMaturity, MATURITY_LADDER, } from "../vocabulary/maturity.js";
+import { compareIds } from "../repo/entries.js";
+import { landscapePath, servicePathsAt } from "../repo/paths.js";
+import { enumeratedServices } from "../repo/service-target.js";
+/** Is this rung at or above `documented` — the fixed threshold check 1 grades against? */
+export function atLeastDocumented(m) {
+    return MATURITY_LADDER.indexOf(m) >= MATURITY_LADDER.indexOf("documented");
+}
+/** The id itself, then each dotted ancestor — the same walk `serviceResolver` resolves through. */
+function selfAndAncestors(id) {
+    const out = [id];
+    for (let dot = id.lastIndexOf("."); dot !== -1; dot = id.lastIndexOf(".", dot - 1)) {
+        out.push(id.slice(0, dot));
+    }
+    return out;
+}
+/**
+ * What the map says about one edge END: does it stand for a person, and is it
+ * tagged `#external`? Walked up the ancestor chain because both facts are
+ * usually written on the containing system while the edge is drawn from a
+ * nested element — but the walk STOPS at the first element that stands for a
+ * service (an explicit binding or a title naming a real directory,
+ * `serviceResolver`'s own first two rungs, checked after that element's own
+ * facts are read). What sits above the service boundary is a grouping, and a
+ * grouping's `#external` is the grouping's claim, not the service's: without
+ * the stop, an adopted service drawn inside an `#external` zone was exempted
+ * from `gate.partner-undocumented` and its real rung hidden.
+ */
+function endFacts(byId, known, id) {
+    let actor = false;
+    let external = false;
+    for (const candidate of selfAndAncestors(id)) {
+        const e = byId.get(candidate);
+        if (e === undefined)
+            continue;
+        if (ACTOR_KINDS.has(e.kind.toLowerCase()))
+            actor = true;
+        if (e.tags.includes(EXTERNAL_TAG))
+            external = true;
+        if (e.service !== undefined || known.has(e.title))
+            break;
+    }
+    return { actor, external };
+}
+/** How one edge joins the two ends, in the words the finding and the payload both use. */
+function viaOf(r) {
+    const typed = [
+        ...(r.op === undefined ? [] : [`operation ${r.op}`]),
+        ...(r.publishes === undefined ? [] : [`message ${r.publishes}`]),
+        ...(r.consumes === undefined ? [] : [`message ${r.consumes}`]),
+    ];
+    if (typed.length > 0)
+        return typed;
+    return [r.title === undefined ? "untyped edge" : `edge '${r.title}'`];
+}
+export async function partnerScan(req) {
+    const { docsDir, service, fleet } = req;
+    // The same memoized enumeration the command's resolveServiceTarget already
+    // performed on this FleetContext — one walk answers both questions.
+    const entries = await enumeratedServices(docsDir, fleet);
+    // Keyed as plain strings on purpose: the lookups below arrive from the
+    // resolver, whose names are document-asserted, and only a hit proves a
+    // directory. The VALUES keep the enumeration's provenance.
+    const entryById = new Map(entries.map((e) => [e.id, e]));
+    const known = new Set(entries.map((e) => e.id));
+    const lp = landscapePath(docsDir);
+    let landscape = "absent";
+    let landscapeProblem = null;
+    let elements = [];
+    let relationships = [];
+    if (existsSync(lp)) {
+        try {
+            const doc = await fleet.loadLikeC4(lp);
+            if (doc.errors.length > 0) {
+                landscape = "invalid";
+                const first = doc.errors[0];
+                landscapeProblem =
+                    `${doc.errors.length} parse error(s)` +
+                        (first === undefined ? "" : ` — first: ${first.message}`);
+            }
+            else {
+                landscape = "read";
+                elements = doc.elements;
+                relationships = doc.relationships;
+            }
+        }
+        catch (err) {
+            // A landscape that could not be READ, graded as one that did not PARSE —
+            // commands/validate/fleet/load.ts's containment doctrine, spelled here
+            // because core cannot import it: "could not be read" and "did not parse"
+            // have the same consequence (nothing may be concluded from this file).
+            // The reason travels into the finding, message-preserving as
+            // `unreadableLandscape` is; the read error must not kill the run — the
+            // other three checks still have answers.
+            landscape = "invalid";
+            landscapeProblem = err instanceof Error ? err.message : String(err);
+        }
+    }
+    const parses = landscape === "read";
+    const svcOf = parses
+        ? serviceResolver(elements, known)
+        : (id) => id;
+    const elementIds = elements.map((e) => e.id);
+    // One service's ladder rung. `landscapeEvidence` is the ONE shared spelling
+    // of the positive-evidence apiExpected rule (core/vocabulary/maturity.ts);
+    // its own docblock warns against calling it per service inside a FLEET loop,
+    // and this loop is not one — it runs over the gated service and its direct
+    // partners, a handful, never the enumeration.
+    const gradeWith = (entry, apiExpected) => {
+        const input = {
+            entry,
+            archSpec: existsSync(servicePathsAt(entry.dir).archSpec),
+            apiExpected,
+        };
+        return { maturity: serviceMaturity(input), gaps: maturityGaps(input) };
+    };
+    const grade = (entry) => gradeWith(entry, landscapeEvidence({ id: entry.id, parses, relationships, elementIds, svcOf }).apiExpected);
+    // Unreachable by construction: the command layer resolved `service` against
+    // the same memoized enumeration this scan just read, and refused
+    // `unknown-service` when no directory answered. Failing closed here beats
+    // grading a service nobody enumerated as if its absence were a rung.
+    const targetEntry = entryById.get(service);
+    if (targetEntry === undefined) {
+        throw new Error(`gate: '${service}' vanished from the enumeration between resolve and scan`);
+    }
+    const byId = new Map(elements.map((e) => [e.id, e]));
+    const acc = new Map();
+    const join = (name, role, r, external) => {
+        const slot = acc.get(name) ?? { consumer: false, provider: false, external: false, via: new Set() };
+        if (role === "consumer")
+            slot.consumer = true;
+        else
+            slot.provider = true;
+        slot.external = slot.external || external;
+        for (const v of viaOf(r))
+            slot.via.add(v);
+        acc.set(name, slot);
+    };
+    for (const r of relationships) {
+        const source = svcOf(r.source);
+        const target = svcOf(r.target);
+        // A self-edge (both ends resolve to the gated service — its own containers
+        // talking to each other) names no partner.
+        if (source === target)
+            continue;
+        if (target === service) {
+            const facts = endFacts(byId, known, r.source);
+            // A person is never a deploy participant: the actor exemption every
+            // landscape census applies (drawnSystems, commands/validate/fleet/census.ts).
+            if (!facts.actor)
+                join(source, "consumer", r, facts.external);
+        }
+        else if (source === service) {
+            const facts = endFacts(byId, known, r.target);
+            if (!facts.actor)
+                join(target, "provider", r, facts.external);
+        }
+    }
+    // Sorted by id so identical state yields identical bytes — the accumulator's
+    // order is the landscape's edge order, which a reformat may shuffle.
+    const joined = [...acc.entries()].sort((a, b) => compareIds(a[0], b[0]));
+    const partners = joined.map(([name, slot]) => {
+        const entry = entryById.get(name);
+        return {
+            service: name,
+            maturity: entry === undefined ? null : grade(entry).maturity,
+            role: slot.consumer && slot.provider ? "both" : slot.consumer ? "consumer" : "provider",
+            via: [...slot.via].sort(),
+            // An adopted service is OURS whatever a zone's tag says: `external` and
+            // a maturity rung together must be unrepresentable, or the rung the
+            // payload carries is one the exemption hides and the human view drops.
+            external: entry === undefined && slot.external,
+        };
+    });
+    return {
+        landscape,
+        landscapeProblem,
+        targetEntry,
+        target: grade(targetEntry),
+        targetWithoutApi: gradeWith(targetEntry, false),
+        partners,
+        partnerEntries: joined.flatMap(([name]) => {
+            const entry = entryById.get(name);
+            return entry === undefined ? [] : [entry];
+        }),
+    };
+}
+//# sourceMappingURL=partners.js.map

package/dist/core/gate/partners.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"partners.js","sourceRoot":"","sources":["../../../src/core/gate/partners.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * The direct join partners of one service, derived from the LIVING landscape,\n * and the maturity grading of everything on either end of a join.\n *\n * The landscape is the only place the fleet's joins are drawn, so the partner\n * set is exactly the edges whose resolved source or target is the gated\n * service — resolved through `serviceResolver` with the ENUMERATED fleet\n * riding in, the same ride that keeps container-modelling landscapes attached\n * everywhere else (an edge into `paymentService.api` is an edge into the\n * service that owns it). A landscape that is absent or does not parse yields\n * NO partner set, never an empty one: `landscape` says which, and the check\n * layer turns \"could not look\" into `gate.partners-unknown` rather than\n * letting it read as \"no partners\".\n */\nimport { existsSync } from \"node:fs\";\nimport { type Elem, type Rel } from \"../c4/likec4.js\";\nimport { serviceResolver } from \"../c4/resolve/service.js\";\nimport {\n  ACTOR_KINDS,\n  EXTERNAL_TAG,\n  landscapeEvidence,\n  maturityGaps,\n  serviceMaturity,\n  MATURITY_LADDER,\n  type Maturity,\n} from \"../vocabulary/maturity.js\";\nimport { compareIds, type ServiceEntry } from \"../repo/entries.js\";\nimport { landscapePath, servicePathsAt } from \"../repo/paths.js\";\nimport { enumeratedServices } from \"../repo/service-target.js\";\nimport type { FleetContext } from \"../fleet-context.js\";\nimport type { DocsDir } from \"../kernel/ids/dirs.js\";\nimport type { RawServiceId } from \"../kernel/ids/service.js\";\nimport type { GatePartner, LandscapeRead, PartnerRole } from \"./report.js\";\n\nexport interface PartnerScanRequest {\n  docsDir: DocsDir;\n  /** The gated service — a name the enumeration approved (`resolveServiceTarget`). */\n  service: RawServiceId;\n  fleet: FleetContext;\n}\n\n/** One service graded on the adoption ladder, with what the next rung wants. */\nexport interface GradedService {\n  maturity: Maturity;\n  gaps: string[];\n}\n\nexport interface PartnerScan {\n  landscape: LandscapeRead;\n  /**\n   * Why the landscape graded `invalid` — the parse-error tally or the read\n   * failure's own words. Null on `read` and `absent`; the finding that fails\n   * the gate must say what broke, not merely that something did.\n   */\n  landscapeProblem: string | null;\n  /**\n   * The gated service's own rung, graded under the landscape's evidence —\n   * `gate.service-undocumented`'s subject. Fail-closed on the api question:\n   * with no readable map, `landscapeEvidence` assumes an API is expected.\n   */\n  target: GradedService;\n  /**\n   * The same service graded with NO api expected of it — the reading that\n   * does not depend on the landscape at all. The check layer answers from\n   * THIS one when the map is absent or broken: the api question is then\n   * unanswerable, and one unanswerable fact must not convict twice (the\n   * landscape already carries its own finding).\n   */\n  targetWithoutApi: GradedService;\n  /**\n   * The gated service's own enumerated entry — carried so a finding can name\n   * the directory it actually occupies. `services/<id>/` is right only for an\n   * unfiled fleet, and a check that sends a reader to a directory they cannot\n   * open has answered worse than not at all.\n   */\n  targetEntry: ServiceEntry;\n  partners: GatePartner[];\n  /**\n   * The enumerated entries behind the partners that HAVE a `services/`\n   * directory, in `partners` order — what the freshness check walks. Kept as\n   * entries rather than names so the ids that travel on carry the\n   * enumeration's provenance (`RawServiceId`), never a document's.\n   */\n  partnerEntries: ServiceEntry[];\n}\n\n/** Is this rung at or above `documented` — the fixed threshold check 1 grades against? */\nexport function atLeastDocumented(m: Maturity): boolean {\n  return MATURITY_LADDER.indexOf(m) >= MATURITY_LADDER.indexOf(\"documented\");\n}\n\n/** The id itself, then each dotted ancestor — the same walk `serviceResolver` resolves through. */\nfunction selfAndAncestors(id: string): string[] {\n  const out = [id];\n  for (let dot = id.lastIndexOf(\".\"); dot !== -1; dot = id.lastIndexOf(\".\", dot - 1)) {\n    out.push(id.slice(0, dot));\n  }\n  return out;\n}\n\n/**\n * What the map says about one edge END: does it stand for a person, and is it\n * tagged `#external`? Walked up the ancestor chain because both facts are\n * usually written on the containing system while the edge is drawn from a\n * nested element — but the walk STOPS at the first element that stands for a\n * service (an explicit binding or a title naming a real directory,\n * `serviceResolver`'s own first two rungs, checked after that element's own\n * facts are read). What sits above the service boundary is a grouping, and a\n * grouping's `#external` is the grouping's claim, not the service's: without\n * the stop, an adopted service drawn inside an `#external` zone was exempted\n * from `gate.partner-undocumented` and its real rung hidden.\n */\nfunction endFacts(\n  byId: Map<string, Elem>,\n  known: ReadonlySet<string>,\n  id: string,\n): { actor: boolean; external: boolean } {\n  let actor = false;\n  let external = false;\n  for (const candidate of selfAndAncestors(id)) {\n    const e = byId.get(candidate);\n    if (e === undefined) continue;\n    if (ACTOR_KINDS.has(e.kind.toLowerCase())) actor = true;\n    if (e.tags.includes(EXTERNAL_TAG)) external = true;\n    if (e.service !== undefined || known.has(e.title)) break;\n  }\n  return { actor, external };\n}\n\n/** How one edge joins the two ends, in the words the finding and the payload both use. */\nfunction viaOf(r: Rel): string[] {\n  const typed = [\n    ...(r.op === undefined ? [] : [`operation ${r.op}`]),\n    ...(r.publishes === undefined ? [] : [`message ${r.publishes}`]),\n    ...(r.consumes === undefined ? [] : [`message ${r.consumes}`]),\n  ];\n  if (typed.length > 0) return typed;\n  return [r.title === undefined ? \"untyped edge\" : `edge '${r.title}'`];\n}\n\ninterface PartnerAccumulator {\n  consumer: boolean;\n  provider: boolean;\n  external: boolean;\n  via: Set<string>;\n}\n\nexport async function partnerScan(req: PartnerScanRequest): Promise<PartnerScan> {\n  const { docsDir, service, fleet } = req;\n  // The same memoized enumeration the command's resolveServiceTarget already\n  // performed on this FleetContext — one walk answers both questions.\n  const entries = await enumeratedServices(docsDir, fleet);\n  // Keyed as plain strings on purpose: the lookups below arrive from the\n  // resolver, whose names are document-asserted, and only a hit proves a\n  // directory. The VALUES keep the enumeration's provenance.\n  const entryById = new Map<string, ServiceEntry>(entries.map((e) => [e.id, e]));\n  const known: ReadonlySet<string> = new Set(entries.map((e) => e.id));\n\n  const lp = landscapePath(docsDir);\n  let landscape: LandscapeRead = \"absent\";\n  let landscapeProblem: string | null = null;\n  let elements: Elem[] = [];\n  let relationships: Rel[] = [];\n  if (existsSync(lp)) {\n    try {\n      const doc = await fleet.loadLikeC4(lp);\n      if (doc.errors.length > 0) {\n        landscape = \"invalid\";\n        const first = doc.errors[0];\n        landscapeProblem =\n          `${doc.errors.length} parse error(s)` +\n          (first === undefined ? \"\" : ` — first: ${first.message}`);\n      } else {\n        landscape = \"read\";\n        elements = doc.elements;\n        relationships = doc.relationships;\n      }\n    } catch (err) {\n      // A landscape that could not be READ, graded as one that did not PARSE —\n      // commands/validate/fleet/load.ts's containment doctrine, spelled here\n      // because core cannot import it: \"could not be read\" and \"did not parse\"\n      // have the same consequence (nothing may be concluded from this file).\n      // The reason travels into the finding, message-preserving as\n      // `unreadableLandscape` is; the read error must not kill the run — the\n      // other three checks still have answers.\n      landscape = \"invalid\";\n      landscapeProblem = err instanceof Error ? err.message : String(err);\n    }\n  }\n  const parses = landscape === \"read\";\n  const svcOf: (id: string) => string = parses\n    ? serviceResolver(elements, known)\n    : (id: string) => id;\n  const elementIds = elements.map((e) => e.id);\n\n  // One service's ladder rung. `landscapeEvidence` is the ONE shared spelling\n  // of the positive-evidence apiExpected rule (core/vocabulary/maturity.ts);\n  // its own docblock warns against calling it per service inside a FLEET loop,\n  // and this loop is not one — it runs over the gated service and its direct\n  // partners, a handful, never the enumeration.\n  const gradeWith = (entry: ServiceEntry, apiExpected: boolean): GradedService => {\n    const input = {\n      entry,\n      archSpec: existsSync(servicePathsAt(entry.dir).archSpec),\n      apiExpected,\n    };\n    return { maturity: serviceMaturity(input), gaps: maturityGaps(input) };\n  };\n  const grade = (entry: ServiceEntry): GradedService =>\n    gradeWith(\n      entry,\n      landscapeEvidence({ id: entry.id, parses, relationships, elementIds, svcOf }).apiExpected,\n    );\n\n  // Unreachable by construction: the command layer resolved `service` against\n  // the same memoized enumeration this scan just read, and refused\n  // `unknown-service` when no directory answered. Failing closed here beats\n  // grading a service nobody enumerated as if its absence were a rung.\n  const targetEntry = entryById.get(service);\n  if (targetEntry === undefined) {\n    throw new Error(`gate: '${service}' vanished from the enumeration between resolve and scan`);\n  }\n\n  const byId = new Map(elements.map((e) => [e.id, e]));\n  const acc = new Map<string, PartnerAccumulator>();\n  const join = (name: string, role: PartnerRole, r: Rel, external: boolean): void => {\n    const slot = acc.get(name) ?? { consumer: false, provider: false, external: false, via: new Set<string>() };\n    if (role === \"consumer\") slot.consumer = true;\n    else slot.provider = true;\n    slot.external = slot.external || external;\n    for (const v of viaOf(r)) slot.via.add(v);\n    acc.set(name, slot);\n  };\n  for (const r of relationships) {\n    const source = svcOf(r.source);\n    const target = svcOf(r.target);\n    // A self-edge (both ends resolve to the gated service — its own containers\n    // talking to each other) names no partner.\n    if (source === target) continue;\n    if (target === service) {\n      const facts = endFacts(byId, known, r.source);\n      // A person is never a deploy participant: the actor exemption every\n      // landscape census applies (drawnSystems, commands/validate/fleet/census.ts).\n      if (!facts.actor) join(source, \"consumer\", r, facts.external);\n    } else if (source === service) {\n      const facts = endFacts(byId, known, r.target);\n      if (!facts.actor) join(target, \"provider\", r, facts.external);\n    }\n  }\n\n  // Sorted by id so identical state yields identical bytes — the accumulator's\n  // order is the landscape's edge order, which a reformat may shuffle.\n  const joined = [...acc.entries()].sort((a, b) => compareIds(a[0], b[0]));\n  const partners: GatePartner[] = joined.map(([name, slot]) => {\n    const entry = entryById.get(name);\n    return {\n      service: name,\n      maturity: entry === undefined ? null : grade(entry).maturity,\n      role: slot.consumer && slot.provider ? \"both\" : slot.consumer ? \"consumer\" : \"provider\",\n      via: [...slot.via].sort(),\n      // An adopted service is OURS whatever a zone's tag says: `external` and\n      // a maturity rung together must be unrepresentable, or the rung the\n      // payload carries is one the exemption hides and the human view drops.\n      external: entry === undefined && slot.external,\n    };\n  });\n\n  return {\n    landscape,\n    landscapeProblem,\n    targetEntry,\n    target: grade(targetEntry),\n    targetWithoutApi: gradeWith(targetEntry, false),\n    partners,\n    partnerEntries: joined.flatMap(([name]) => {\n      const entry = entryById.get(name);\n      return entry === undefined ? [] : [entry];\n    }),\n  };\n}\n"]}

package/dist/core/gate/report.js

@@ -0,0 +1,47 @@
+/** The four checks, in report order. A closed set — the payload's `checks[].check` values. */
+export const GATE_CHECKS = ["partners", "freshness", "verification", "interrupted"];
+/**
+ * Fail iff any check carries an error-severity finding. `--strict` never moves
+ * this — like validate's `valid`, the verdict means the same thing in text and
+ * JSON whatever the exit code does, so two pipelines reading one repo can
+ * grade the same report differently and both be telling the truth
+ * (commands/validate/validate.ts documents the stance; gate copies it).
+ */
+export function gateVerdict(checks) {
+    return checks.some((c) => c.findings.some((f) => f.severity === "error")) ? "fail" : "pass";
+}
+export function gateSummary(checks) {
+    const of = (severity) => checks.reduce((n, c) => n + c.findings.filter((f) => f.severity === severity).length, 0);
+    return { errors: of("error"), warnings: of("warn") };
+}
+/**
+ * Per-subject containment: one unreadable sibling degrades ONE subject's
+ * answer, with its path recorded, instead of killing the report the other
+ * subjects still have. The code is validate's own containment code
+ * (`guarded`, commands/validate/report.ts), reused so one breach is spelled
+ * one way — and it is an ERROR: an unanswerable check fails closed, because
+ * "nobody could look" must be distinguishable from "nothing is wrong" in the
+ * exit code as well as the payload. Anything carrying no errno and no path is
+ * a real bug, and still escapes untouched (reportRepositoryUnavailable's
+ * recognizer).
+ */
+export function unreadableSubject(kind, id, err) {
+    const e = err;
+    if (e.path === undefined && typeof e.errno !== "number")
+        throw err;
+    const reason = err instanceof Error ? err.message : String(err);
+    const consequence = kind === "service" ? "its freshness is unknown" : "its verification state is unknown";
+    return {
+        severity: "error",
+        code: kind === "service" ? "service.unreadable" : "feature.unreadable",
+        subject: id,
+        message: `${id}: ${e.path ?? "one of its documents"} could not be read, so ${consequence} — nobody could look, which is not the same as nothing being wrong. ${reason}` +
+            // The same sentence reportRepositoryUnavailable carries, for the same
+            // reason: Node reports EISDIR from read() with no path at all, so the
+            // commonest malformed-docs shape arrives here nameless.
+            (e.path === undefined
+                ? " The failure named no path — that is how Node reports a directory sitting where a file belongs."
+                : ""),
+    };
+}
+//# sourceMappingURL=report.js.map

package/dist/core/gate/report.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"report.js","sourceRoot":"","sources":["../../../src/core/gate/report.ts"],"names":[],"mappings":"AAeA,8FAA8F;AAC9F,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,UAAU,EAAE,WAAW,EAAE,cAAc,EAAE,aAAa,CAAU,CAAC;AA4D7F;;;;;;GAMG;AACH,MAAM,UAAU,WAAW,CAAC,MAA4B;IACtD,OAAO,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC;AAC9F,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,MAA4B;IACtD,MAAM,EAAE,GAAG,CAAC,QAA0B,EAAU,EAAE,CAChD,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC,CAAC,GAAG,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,KAAK,QAAQ,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IAC3F,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC;AACvD,CAAC;AAED;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAA2B,EAAE,EAAU,EAAE,GAAY;IACrF,MAAM,CAAC,GAAG,GAA4B,CAAC;IACvC,IAAI,CAAC,CAAC,IAAI,KAAK,SAAS,IAAI,OAAO,CAAC,CAAC,KAAK,KAAK,QAAQ;QAAE,MAAM,GAAG,CAAC;IACnE,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;IAChE,MAAM,WAAW,GACf,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,0BAA0B,CAAC,CAAC,CAAC,mCAAmC,CAAC;IACxF,OAAO;QACL,QAAQ,EAAE,OAAO;QACjB,IAAI,EAAE,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,oBAAoB,CAAC,CAAC,CAAC,oBAAoB;QACtE,OAAO,EAAE,EAAE;QACX,OAAO,EACL,GAAG,EAAE,KAAK,CAAC,CAAC,IAAI,IAAI,sBAAsB,0BAA0B,WAAW,uEAAuE,MAAM,EAAE;YAC9J,sEAAsE;YACtE,sEAAsE;YACtE,wDAAwD;YACxD,CAAC,CAAC,CAAC,IAAI,KAAK,SAAS;gBACnB,CAAC,CAAC,iGAAiG;gBACnG,CAAC,CAAC,EAAE,CAAC;KACV,CAAC;AACJ,CAAC","sourcesContent":["/**\n * The gate report — what `loam gate` computes before anything is printed.\n *\n * Shapes, verdict arithmetic and the per-subject containment classifier: no\n * filesystem, no process access, no printing. The four checks build findings\n * (`./checks.ts`, `./verification.ts`), the command layer renders them, and\n * this module is what the two agree through — the same split\n * `core/vocabulary/report.ts` gives `loam validate`, whose `Finding` shape\n * the checks reuse so one breach arrives in one shape whichever command\n * reports it.\n */\nimport type { Finding } from \"../vocabulary/report.js\";\nimport type { Maturity } from \"../vocabulary/maturity.js\";\nimport type { VerificationState } from \"../status/report.js\";\n\n/** The four checks, in report order. A closed set — the payload's `checks[].check` values. */\nexport const GATE_CHECKS = [\"partners\", \"freshness\", \"verification\", \"interrupted\"] as const;\nexport type GateCheckName = (typeof GATE_CHECKS)[number];\n\nexport interface GateCheck {\n  check: GateCheckName;\n  findings: Finding[];\n}\n\n/**\n * How the landscape read came out. `absent` and `invalid` are kept apart from\n * `read` because the partner set derived under either is NOT \"no partners\" —\n * it is \"could not look\", and `gate.partners-unknown` exists to keep a\n * pipeline from reading the empty list as a clean one.\n */\nexport type LandscapeRead = \"read\" | \"absent\" | \"invalid\";\n\n/**\n * What the partner is to the gated service: a `consumer` calls into it, a\n * `provider` is called by it, `both` when the landscape draws edges in both\n * directions.\n */\nexport type PartnerRole = \"consumer\" | \"provider\" | \"both\";\n\nexport interface GatePartner {\n  /** The partner's resolved service name — a directory id when one exists, the drawn name otherwise. */\n  service: string;\n  /**\n   * The partner's rung on the adoption ladder, or null when no `services/`\n   * directory answers to the name at all — the state `gate.partner-undocumented`\n   * names. Null is deliberately not a fifth rung: `empty` means \"exists,\n   * nothing in it\", and a partner nobody adopted is a different fact.\n   */\n  maturity: Maturity | null;\n  role: PartnerRole;\n  /** The joins, sorted: `operation <op>`, `message <name>`, or the untyped edge's title. */\n  via: string[];\n  /** The element is tagged `#external` — somebody else's system, undocumented on purpose. */\n  external: boolean;\n}\n\n/**\n * One active feature touching the gated service, with the verification\n * record's own projection beside it. Every field but `id` is\n * `verificationState`'s (`core/status/verification.ts`) — never a second\n * derivation of \"verified\".\n */\nexport interface GateFeature extends VerificationState {\n  id: string;\n}\n\nexport interface GateReport {\n  service: string;\n  landscape: LandscapeRead;\n  partners: GatePartner[];\n  features: GateFeature[];\n  checks: GateCheck[];\n}\n\nexport type GateVerdict = \"pass\" | \"fail\";\n\n/**\n * Fail iff any check carries an error-severity finding. `--strict` never moves\n * this — like validate's `valid`, the verdict means the same thing in text and\n * JSON whatever the exit code does, so two pipelines reading one repo can\n * grade the same report differently and both be telling the truth\n * (commands/validate/validate.ts documents the stance; gate copies it).\n */\nexport function gateVerdict(checks: readonly GateCheck[]): GateVerdict {\n  return checks.some((c) => c.findings.some((f) => f.severity === \"error\")) ? \"fail\" : \"pass\";\n}\n\nexport function gateSummary(checks: readonly GateCheck[]): { errors: number; warnings: number } {\n  const of = (severity: \"error\" | \"warn\"): number =>\n    checks.reduce((n, c) => n + c.findings.filter((f) => f.severity === severity).length, 0);\n  return { errors: of(\"error\"), warnings: of(\"warn\") };\n}\n\n/**\n * Per-subject containment: one unreadable sibling degrades ONE subject's\n * answer, with its path recorded, instead of killing the report the other\n * subjects still have. The code is validate's own containment code\n * (`guarded`, commands/validate/report.ts), reused so one breach is spelled\n * one way — and it is an ERROR: an unanswerable check fails closed, because\n * \"nobody could look\" must be distinguishable from \"nothing is wrong\" in the\n * exit code as well as the payload. Anything carrying no errno and no path is\n * a real bug, and still escapes untouched (reportRepositoryUnavailable's\n * recognizer).\n */\nexport function unreadableSubject(kind: \"service\" | \"feature\", id: string, err: unknown): Finding {\n  const e = err as NodeJS.ErrnoException;\n  if (e.path === undefined && typeof e.errno !== \"number\") throw err;\n  const reason = err instanceof Error ? err.message : String(err);\n  const consequence =\n    kind === \"service\" ? \"its freshness is unknown\" : \"its verification state is unknown\";\n  return {\n    severity: \"error\",\n    code: kind === \"service\" ? \"service.unreadable\" : \"feature.unreadable\",\n    subject: id,\n    message:\n      `${id}: ${e.path ?? \"one of its documents\"} could not be read, so ${consequence} — nobody could look, which is not the same as nothing being wrong. ${reason}` +\n      // The same sentence reportRepositoryUnavailable carries, for the same\n      // reason: Node reports EISDIR from read() with no path at all, so the\n      // commonest malformed-docs shape arrives here nameless.\n      (e.path === undefined\n        ? \" The failure named no path — that is how Node reports a directory sitting where a file belongs.\"\n        : \"\"),\n  };\n}\n"]}