@sdd-method/author-cli 0.17.0 → 0.17.2

package/dist/lib/behaviour-store/archive.js

@@ -172,36 +172,53 @@ export function observedInProblems(evidence) {
  * `**Surfaces:** none` on one line is the typed claim that the baseline lists no surface, which only a baseline that
  * admits no behaviour may make (the caller decides; `none` is true and the list is empty).
  */
+/** What drives a service that serves no contract (sdm-xfln): the triggers `**Surfaces:** none served (...)` may name. */
+export const NONE_SERVED_TRIGGERS = ["scheduled", "queue-triggered", "stream-triggered"];
 export function parseSurfaces(evidence) {
     const lines = evidence.split("\n");
     // The LAST standalone line: an evidence file may carry an earlier prose section under the same label, and
     // the list is what the file ends up asserting.
     let at = -1;
-    let none = false;
-    let generated = false;
+    let claim = "list";
     lines.forEach((l, i) => {
         if (/^\s*\*\*Surfaces:\*\*\s*$/.test(l)) {
             at = i;
-            none = false;
-            generated = false;
+            claim = "list";
+        }
+        else if (/^\s*\*\*Surfaces:\*\*\s*none\s+served\b/i.test(l)) {
+            at = i;
+            claim = "none served";
         }
         else if (/^\s*\*\*Surfaces:\*\*\s*none\b/i.test(l)) {
             at = i;
-            none = true;
-            generated = false;
+            claim = "none";
         }
         else if (/^\s*\*\*Surfaces:\*\*\s*generated\b/i.test(l)) {
             at = i;
-            none = false;
-            generated = true;
+            claim = "generated";
         }
     });
+    const base = { present: true, none: false, generated: false, noneServed: null, entries: [], problems: [] };
     if (at < 0)
-        return { present: false, none: false, generated: false, entries: [], problems: [] };
-    if (none)
-        return { present: true, none: true, generated: false, entries: [], problems: [] };
-    if (generated)
-        return { present: true, none: false, generated: true, entries: [], problems: [] };
+        return { ...base, present: false };
+    if (claim === "none")
+        return { ...base, none: true };
+    if (claim === "generated")
+        return { ...base, generated: true };
+    if (claim === "none served") {
+        // `**Surfaces:** none served (scheduled)`: the service serves no contract; what drives it is named, from a
+        // closed vocabulary, so the claim says why and cannot be left vague.
+        const m = /none\s+served\s*\(([^)]*)\)\s*\.?\s*$/i.exec(lines[at]);
+        const triggers = m ? m[1].split(",").map((t) => t.trim()).filter((t) => t !== "") : [];
+        const problems = [];
+        if (!m || triggers.length === 0)
+            problems.push(`"none served" names what drives the service: "**Surfaces:** none served (${NONE_SERVED_TRIGGERS.join(" | ")})"`);
+        for (const t of triggers) {
+            if (!NONE_SERVED_TRIGGERS.includes(t))
+                problems.push(`"none served (${t})": "${t}" is not one of ${NONE_SERVED_TRIGGERS.join(", ")}`);
+        }
+        return { ...base, noneServed: triggers, problems };
+    }
     const entries = [];
     const problems = [];
     for (const line of lines.slice(at + 1)) {
@@ -236,7 +253,7 @@ export function parseSurfaces(evidence) {
     }
     if (entries.length + problems.length === 0)
         problems.push('the **Surfaces:** line lists no contract; a baseline that admits no behaviour writes "**Surfaces:** none"');
-    return { present: true, none: false, generated: false, entries, problems };
+    return { present: true, none: false, generated: false, noneServed: null, entries, problems };
 }
 /**
  * A generator's baseline (agreement-record-schema.yaml, Baselines: generated behaviour) serves no contract; its

package/dist/lib/catalogue/builders/repositories.js

@@ -33,17 +33,20 @@ const LOC_REPORT_REL = join("docs", "platform", "reference", "loc-report.csv");
 const REPOS_DIR_REL = "repos";
 const REVERSE_METADATA_BASENAME = "reverse-metadata.yaml";
 // The contract kinds a repo-config `contracts:` block keys, under `contracts/<kind>/`. The sdd-index reader
-// accepts the same six; `spicedb` (an `authz` contract) was once missing here, and zod strips an unknown key,
+// accepts the same seven; `spicedb` (an `authz` contract) was once missing here, and zod strips an unknown key,
 // so a declared `.zed` schema vanished without a finding. `cli` (schema 4.1.0) declares the command manifest a
 // command-line repository serves, and `ui` (schema 7.2.0) the manifest of an embeddable UI surface a UI-only
-// repository serves. GraphQL is not keyed in repo-config: that is its own question, on this schema.
-export const REPO_CONFIG_CONTRACT_KINDS = ["openapi", "proto", "avro", "spicedb", "cli", "ui"];
+// repository serves. `graphql` declares a GraphQL SDL a repository serves: the contracts builder discovered it,
+// and the kind enum held it, while repo-config could not key it, so a repository serving only GraphQL had no
+// served contract and its baselines' Surfaces could never be cross-checked (sdm-pvy8).
+export const REPO_CONFIG_CONTRACT_KINDS = ["openapi", "proto", "avro", "spicedb", "graphql", "cli", "ui"];
 const ContractsBlockSchema = z
     .object({
     openapi: z.array(z.string()).optional(),
     proto: z.array(z.string()).optional(),
     avro: z.array(z.string()).optional(),
     spicedb: z.array(z.string()).optional(),
+    graphql: z.array(z.string()).optional(),
     cli: z.array(z.string()).optional(),
     ui: z.array(z.string()).optional(),
 })

package/dist/lib/plan/read-sdd.js

@@ -62,6 +62,7 @@ function legacyShape(node, sourcePath) {
         proto: [],
         avro: [],
         spicedb: [],
+        graphql: [],
         cli: [],
         ui: [],
     };

package/dist/lib/sdd-index/repo-config.js

@@ -16,6 +16,7 @@ const CONTRACT_KINDS = [
     "proto",
     "avro",
     "spicedb",
+    "graphql",
     "cli",
     "ui",
 ];

package/dist/lib/structure/archive.js

@@ -65,9 +65,9 @@ async function defaultBehaviourFindings(sddPath, archiveDir) {
     const r = await checkBehaviourStore(sddPath);
     return r.stdout.split("\n").filter((l) => l.startsWith("[FAIL]") && l.includes(archiveDir));
 }
-function viewProblems(schema, view) {
+function viewProblems(schema, view, profile) {
     const out = [];
-    validateView(schema, view, () => null, out, new Set());
+    validateView(schema, view, () => null, out, new Set(), () => undefined, profile);
     return new Set(out);
 }
 /** Does the effect record hold at `commit`? Each added or modified element at its target, each removed one absent. */
@@ -98,6 +98,11 @@ async function verifyAt(root, relSdd, commit, effects) {
         await rm(scratch, { recursive: true, force: true });
     }
 }
+/** The SDD's profile from its manifest, "" when absent or unreadable. */
+async function sddProfile(sddPath) {
+    const text = await readFile(join(sddPath, ".sdd", "sdd-manifest.yaml"), "utf8").catch(() => "");
+    return /^profile:\s*["']?([A-Za-z0-9-]+)["']?\s*$/m.exec(text)?.[1] ?? "";
+}
 export async function archiveChange(o) {
     const say = (s) => o.write(`${s}\n`);
     const refuse = (s) => {
@@ -241,6 +246,7 @@ async function publish(o, root, relSdd, schema, s, changeRel, mode) {
         say(`[FAIL] change archive ${o.change}: ${x}`);
         return 1;
     };
+    const profile = await sddProfile(o.sddPath);
     const storeRel = join(relSdd, "openspec");
     const viewsRel = join(relSdd, "docs", "structure");
     const dirty = await git(root, "status", "--porcelain", "--", storeRel, viewsRel);
@@ -250,9 +256,9 @@ async function publish(o, root, relSdd, schema, s, changeRel, mode) {
     // §4.5 again, against the model as it now is.
     const problems = [];
     const current = viewOf((await loadModel(o.sddPath, problems)) ?? [], problems);
-    const before = viewProblems(schema, current);
+    const before = viewProblems(schema, current, profile);
     const deltaProblems = [];
-    validateDeltas(schema, current, s.deltas, new Map(), deltaProblems);
+    validateDeltas(schema, current, s.deltas, new Map(), deltaProblems, profile);
     if (deltaProblems.length > 0)
         return refuse(`its structural deltas no longer apply to the model as it stands:\n  ${deltaProblems.join("\n  ")}`);
     const effects = effectsOf(s, current);
@@ -280,7 +286,7 @@ async function publish(o, root, relSdd, schema, s, changeRel, mode) {
         // 2. Validate the candidate as a whole.
         const cp = [];
         const candidate = viewOf((await loadModel(scratchSdd, cp)) ?? [], cp);
-        const after = viewProblems(schema, candidate);
+        const after = viewProblems(schema, candidate, profile);
         const worse = [...cp, ...[...after].filter((p) => !before.has(p))];
         if (worse.length > 0)
             return refuse(`the model as it would stand fails where it did not:\n  ${worse.join("\n  ")}`);

package/dist/lib/structure/view.js

@@ -90,13 +90,15 @@ function find(view, catalogue, column, value) {
     return undefined;
 }
 /** The element's references: each non-external foreign key with a value. */
-export function referencesOf(schema, e) {
+export function referencesOf(schema, e, profile = "") {
     const cat = catalogueOf(schema, e.catalogue);
     if (!cat)
         return [];
     const out = [];
     for (const fk of cat.foreignKeys) {
-        if (fk.external)
+        // An external key names another SDD's element; so does one external for this SDD's profile (an application or
+        // integration model naming a data item the platform model owns), as the FK validator and the graph projection read it.
+        if (fk.external || (profile !== "" && (fk.externalForProfiles ?? []).includes(profile)))
             continue;
         const v = e.columns[fk.column];
         if (v === undefined || v === "")
@@ -121,7 +123,7 @@ function naturalKey(cat, e) {
  * catalogue of another class, against its built rows), no cycle through a self-reference, natural keys unique, and
  * domain invariants naming their entity's own attributes and relationships.
  */
-export function validateView(schema, view, built, problems, unresolved, addedBy = () => undefined) {
+export function validateView(schema, view, built, problems, unresolved, addedBy = () => undefined, profile = "") {
     // A reference to an open change's addition, from outside that change and its dependants (§4.11 proof 3).
     const outside = (catalogue, id) => {
         const by = addedBy(catalogue, id);
@@ -135,7 +137,7 @@ export function validateView(schema, view, built, problems, unresolved, addedBy
             problems.push(...shape);
             if (!cat || cat.sourceOfTruth !== STRUCTURE)
                 continue;
-            for (const r of referencesOf(schema, e)) {
+            for (const r of referencesOf(schema, e, profile)) {
                 if (r.structural) {
                     if (!find(view, r.catalogue, r.targetColumn, r.value))
                         problems.push(`${e.file}: ${elementKey(catalogue, e.id)}: ${r.column} ${JSON.stringify(r.value)} names no ${r.catalogue} element in this view (${elementKey(r.catalogue, r.value)})${r.targetColumn === "id" ? outside(r.catalogue, r.value) : ""}`);
@@ -218,7 +220,7 @@ export function validateView(schema, view, built, problems, unresolved, addedBy
  * A base revision that no longer matches the current element is reported as moved: the change is revalidated.
  * `addedElsewhere` holds the elements other open changes add, for a reference into one of them.
  */
-export function validateDeltas(schema, current, deltas, addedElsewhere, problems) {
+export function validateDeltas(schema, current, deltas, addedElsewhere, problems, profile = "") {
     const ownAdded = new Set();
     const dependsOn = new Set();
     for (const d of deltas) {
@@ -281,7 +283,7 @@ export function validateDeltas(schema, current, deltas, addedElsewhere, problems
         }
         // Reads: every element an added or modified element references.
         for (const e of [...d.added, ...d.modified]) {
-            for (const r of referencesOf(schema, e)) {
+            for (const r of referencesOf(schema, e, profile)) {
                 if (!r.structural)
                     continue;
                 const target = r.targetColumn === "id" ? r.value : find(current, r.catalogue, r.targetColumn, r.value)?.id;

package/dist/lib/validate/behaviour-store.js

@@ -848,6 +848,7 @@ export async function checkBehaviourStore(repo, options = {}) {
     let surfacesChecked = 0;
     let structureOnly = 0;
     let generatedBaselines = 0;
+    let noneServedBaselines = 0;
     // The contract moves each archived change records, in archive order. A contract's id derives from its path, so a
     // move changes it; an archived baseline's list names the contract as it was, and is resolved through the moves
     // archived after it rather than edited (M-ADR 0222 §4.4). A surface that vanished with no move still fails.
@@ -935,6 +936,8 @@ export async function checkBehaviourStore(repo, options = {}) {
         if (!admits) {
             if (parsed.generated)
                 return [`${dir}/baseline-evidence.md: **Surfaces:** generated, but the baseline admits no behaviour (no requirement in its spec deltas): write "**Surfaces:** none"`];
+            if (parsed.noneServed !== null)
+                return [`${dir}/baseline-evidence.md: **Surfaces:** none served, but the baseline admits no behaviour (no requirement in its spec deltas): write "**Surfaces:** none"`];
             if (parsed.none) {
                 structureOnly++;
                 return out;
@@ -946,6 +949,30 @@ export async function checkBehaviourStore(repo, options = {}) {
         else if (parsed.none) {
             return [`${dir}/baseline-evidence.md: **Surfaces:** none, but the baseline admits behaviour (requirements in ${dir}/specs/); name every contract the observed repositories serve, covered at transport or excluded with a reason`];
         }
+        if (parsed.noneServed !== null) {
+            // A service driven only by a schedule, a queue or a stream serves no contract: the Surfaces rule names what the
+            // observed repositories SERVE, and a contract a repository only consumes is not a surface. The claim holds only
+            // where the catalogue confirms that no observed repository serves a contract (sdm-xfln); anything else fails, so
+            // it is never a way past the list.
+            for (const p of parsed.problems)
+                out.push(`${dir}/baseline-evidence.md: Surfaces: ${p}`);
+            if (servedBy === null) {
+                out.push(`${dir}/baseline-evidence.md: **Surfaces:** none served cannot be cross-checked: catalogues/repo_contract.csv or catalogues/contracts.csv is missing; build the catalogue`);
+                return out;
+            }
+            const repos = observedIn(evidence);
+            if (repos.length === 0)
+                out.push(`${dir}/baseline-evidence.md: **Surfaces:** none served cannot be cross-checked: no **Observed in:** line names a repository`);
+            for (const r of repos) {
+                const served = servedBy.get(r)?.served ?? [];
+                if (served.length > 0) {
+                    out.push(`${dir}/baseline-evidence.md: **Surfaces:** none served, but ${r} serves ${served.length} contract(s) (catalogues/repo_contract.csv: ${served.slice(0, 3).map((c) => c.id).join(", ")}${served.length > 3 ? ", ..." : ""}); a repository that serves contracts lists each, covered at transport or excluded with a reason`);
+                }
+            }
+            if (out.length === 0)
+                noneServedBaselines++;
+            return out;
+        }
         if (parsed.generated) {
             // A generator serves nothing: its transport is the generated tree (agreement-record-schema.yaml, Baselines). The
             // claim holds only where the catalogue confirms that no observed repository serves a contract, and where the run
@@ -1088,7 +1115,7 @@ export async function checkBehaviourStore(repo, options = {}) {
     if (openBaselines.length > 0)
         lines.push(`open baselines: ${openBaselines.length}, asked the archive's questions as warnings`);
     const unseen = servedBy === null ? "" : `; repositories with no catalogue contracts: ${[...new Set(await observedInAll(repo, archiveRel, order))].filter((r) => (servedBy.get(r)?.served ?? []).length === 0).join(", ") || "none"}`;
-    lines.push(baselines === 0 ? "surfaces: vacuous (no baseline)" : `surfaces: ${baselines} baseline(s), ${surfacesChecked} served contract(s) checked against catalogues/repo_contract.csv less what service_contract records only consumed${unseen}${structureOnly ? `; ${structureOnly} structure-only baseline(s) admitting no behaviour, Surfaces: none` : ""}${generatedBaselines ? `; ${generatedBaselines} generator baseline(s) serving no contract, Surfaces: generated` : ""}${historical.size ? `; ${historical.size} historical baseline(s) not checked (every requirement they baselined has left the living specs)` : ""}`);
+    lines.push(baselines === 0 ? "surfaces: vacuous (no baseline)" : `surfaces: ${baselines} baseline(s), ${surfacesChecked} served contract(s) checked against catalogues/repo_contract.csv less what service_contract records only consumed${unseen}${structureOnly ? `; ${structureOnly} structure-only baseline(s) admitting no behaviour, Surfaces: none` : ""}${generatedBaselines ? `; ${generatedBaselines} generator baseline(s) serving no contract, Surfaces: generated` : ""}${noneServedBaselines ? `; ${noneServedBaselines} baseline(s) of services serving no contract, Surfaces: none served` : ""}${historical.size ? `; ${historical.size} historical baseline(s) not checked (every requirement they baselined has left the living specs)` : ""}`);
     lines.push(scopeChecked === 0 ? "scope: vacuous (no baseline removes, modifies or renames a requirement)" : `scope: ${scopeChecked} requirement(s) a baseline removes, modifies or renames, checked against their lineage`);
     if (!history && archived.length > 0)
         lines.push("order: no git history (not a git work tree, or git log failed), so same-day archives cannot be ordered");

package/dist/lib/validate/structural-model.js

@@ -162,7 +162,7 @@ export async function checkStructuralModel(repo, options = {}) {
     // The current view.
     const unresolved = new Set();
     const currentProblems = [];
-    validateView(schema, view, builtIn(built, allNew, new Set()), currentProblems, unresolved, addedBy);
+    validateView(schema, view, builtIn(built, allNew, new Set()), currentProblems, unresolved, addedBy, profile);
     problems.push(...currentProblems);
     const elementCount = [...view.values()].reduce((n, m) => n + m.size, 0);
     lines.push(files === null ? `model: none (${STRUCTURE_DIR}/ absent)` : `model: ${files.length} partition file(s), ${elementCount} element(s) in ${view.size} catalogue(s)`);
@@ -211,7 +211,7 @@ export async function checkStructuralModel(repo, options = {}) {
         if (s.noOp && s.deltas.length > 0)
             problems.push(`${s.noOp.file}: a no-op claim beside ${s.deltas.length} partition delta(s); state one or the other`);
         const elsewhere = new Map([...addedByChange].filter(([, c]) => c !== s.change));
-        validateDeltas(schema, view, s.deltas, elsewhere, problems);
+        validateDeltas(schema, view, s.deltas, elsewhere, problems, profile);
         // A behaviour delta for a feature the model does not hold needs that feature added here.
         const adds = new Set(s.deltas.flatMap((d) => d.added.filter((e) => e.catalogue === "features").map((e) => e.id)));
         for (const feature of await subdirs(join(repo, dir, "specs"))) {
@@ -238,7 +238,7 @@ export async function checkStructuralModel(repo, options = {}) {
         if (oc.structure.deltas.length === 0)
             continue;
         const at = [];
-        validateView(schema, viewAt(view, name, open), builtIn(built, allNew, additions.contracts(closure(name, open))), at, new Set(), addedBy);
+        validateView(schema, viewAt(view, name, open), builtIn(built, allNew, additions.contracts(closure(name, open))), at, new Set(), addedBy, profile);
         for (const p of at) {
             if (known.has(p))
                 continue;
@@ -250,7 +250,7 @@ export async function checkStructuralModel(repo, options = {}) {
     const agreed = agreedOrder(open);
     if (agreed.length > 0) {
         const inIntended = [];
-        validateView(schema, intended(view, open), builtIn(built, allNew, additions.contracts(agreed)), inIntended, new Set(), addedBy);
+        validateView(schema, intended(view, open), builtIn(built, allNew, additions.contracts(agreed)), inIntended, new Set(), addedBy, profile);
         for (const p of inIntended) {
             if (known.has(p) || atAgreed.has(p))
                 continue;

package/dist/maintain-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "0.18.0",
-  "built_against_sdd_cli": "5.4.0"
+  "version": "0.18.2",
+  "built_against_sdd_cli": "5.4.2"
 }

package/dist/verify-version.json

@@ -1,4 +1,4 @@
 {
-  "version": "5.4.0",
-  "built_against_sdd_cli": "5.4.0"
+  "version": "5.4.2",
+  "built_against_sdd_cli": "5.4.2"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sdd-method/author-cli",
-  "version": "0.17.0",
-  "sddCliVersion": "5.4.0",
+  "version": "0.17.2",
+  "sddCliVersion": "5.4.2",
   "description": "Re-author one SDD's content — scaffold, plan, contracts, conformance, api-surface, snapshots, briefings, catalogue check — plus every read-only verify verb. Ships only the code those verbs reach; it cannot sync the baseline or rebuild the catalogues. Maintenance is in @sdd-method/maintain-cli, administration in @sdd-method/sdd-cli.",
   "license": "UNLICENSED",
   "type": "module",

package/scripts/validate-app-docs.sh

@@ -149,6 +149,10 @@ check_feature_specs() {
     local specs_failed=0
     local specs_passed=0
     local specs_flat=0
+    local sdd_id=""
+    if [[ -f "$APP_ROOT/.sdd/sdd-manifest.yaml" ]]; then
+        sdd_id="$(sed -nE 's/^sdd_id:[[:space:]]*["'"'"']?([^"'"'"' ]+)["'"'"']?[[:space:]]*$/\1/p' "$APP_ROOT/.sdd/sdd-manifest.yaml" | head -1)"
+    fi
 
     # Discover feature specs under features/*/
     local feature_spec
@@ -166,7 +170,11 @@ check_feature_specs() {
 
         if [[ "$(dirname "$feature_spec")" == "$APP_ROOT/features" ]]; then
             local name; name="$(basename "$feature_spec" .md)"
-            log_warn "$rel: stored flat under features/; a feature spec's path is features/${name}/${name}.md, one directory per feature with its story files beside it (app-feature-spec skill). Advisory: reported, not failed"
+            # The directory and file take the feature's slug, the one feature-tree.md uses: a stem repeating the
+            # product id (the manifest's sdd_id) is not the slug, and the catalogue build refuses it.
+            local slug="$name"
+            if [[ -n "$sdd_id" && "$name" == "${sdd_id}-"* ]]; then slug="${name#"${sdd_id}-"}"; fi
+            log_warn "$rel: stored flat under features/; a feature spec's path is features/${slug}/${slug}.md, one directory per feature named by its feature-tree slug (app-feature-spec skill). Advisory: reported, not failed"
             specs_flat=$((specs_flat + 1))
         fi