@intellectual-frontiers/libraries 0.1.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -13,6 +13,8 @@ export declare const IFCCM: OntologyPublication;
13
13
  export declare const IFQS: OntologyPublication;
14
14
  /** The ontology of Intellectual Frontiers Releases (commons 0026-works-versioning), as it is published. */
15
15
  export declare const IFR: OntologyPublication;
16
+ /** The ontology of Kanon (commons 0033-kanon), as it is published. */
17
+ export declare const KANON: OntologyPublication;
16
18
  /** The ontologies of commons that are published, each from its own typed modules: Mizan's, then the ones its specifications define. */
17
19
  export declare const publications: readonly OntologyPublication[];
18
20
  /** The exports of the ontology (0019-mizan-integrations FR-010): everything but its Turtle, by its path from commons' folder. */
@@ -19,6 +19,7 @@ import { Authority, bases, classes, Decision, files, integrationDirections, rung
19
19
  import * as ifccmOntology from "@intellectual-frontiers/ontology/ifccm";
20
20
  import * as ifrOntology from "@intellectual-frontiers/ontology/ifr";
21
21
  import * as ifqsOntology from "@intellectual-frontiers/ontology/ifqs";
22
+ import * as kanonOntology from "@intellectual-frontiers/ontology/kanon";
22
23
  import { formatRdfFinding, validate } from "@intellectual-frontiers/rdf";
23
24
  import { stdio } from "@intellectual-frontiers/system";
24
25
  import { exportDcat } from "@intellectual-frontiers/mizan/integrations/pure/export-dcat";
@@ -204,8 +205,39 @@ export const IFR = {
204
205
  viewTitle: "Intellectual Frontiers Releases: the ontology",
205
206
  license: CC0,
206
207
  };
208
+ /** The ontology of Kanon (commons 0033-kanon), as it is published. */
209
+ export const KANON = {
210
+ name: "kanon",
211
+ ns: { prefix: "kanon", iri: kanonOntology.KANON.iri },
212
+ idNs: { prefix: "mzid", iri: MZID.iri },
213
+ curies: [
214
+ ["kanon", kanonOntology.KANON.iri],
215
+ ["mz", MZ.iri],
216
+ ["xsd", "http://www.w3.org/2001/XMLSchema#"],
217
+ ["rdfs", "http://www.w3.org/2000/01/rdf-schema#"],
218
+ ["skos", "http://www.w3.org/2004/02/skos/core#"],
219
+ ["dcterms", "http://purl.org/dc/terms/"],
220
+ ["prov", "http://www.w3.org/ns/prov#"],
221
+ ["sh", "http://www.w3.org/ns/shacl#"],
222
+ ],
223
+ files: kanonOntology.files,
224
+ ontology: kanonOntology.kanonOntology,
225
+ classes: kanonOntology.classes,
226
+ properties: kanonOntology.properties,
227
+ terms: kanonOntology.terms,
228
+ schemas: [kanonOntology.Layer],
229
+ lists: listsOf("kanon", [["Layer", kanonOntology.layers]]),
230
+ source: "commons/ontology/src/kanon/*.ts",
231
+ run: RUN,
232
+ shapes: { prefix: "kanonsh", iri: "https://www.intellectualfrontiers.com/ontology/kanon-shapes#" },
233
+ schemasIri: "https://www.intellectualfrontiers.com/ontology/kanon-schemas",
234
+ sssomSetId: "https://www.intellectualfrontiers.com/ontology/kanon-mappings",
235
+ sssomCuries: { dcterms: "http://purl.org/dc/terms/", prov: "http://www.w3.org/ns/prov#", sh: "http://www.w3.org/ns/shacl#" },
236
+ viewTitle: "Kanon: the ontology",
237
+ license: CC0,
238
+ };
207
239
  /** The ontologies of commons that are published, each from its own typed modules: Mizan's, then the ones its specifications define. */
208
- export const publications = [MIZAN, IFCCM, IFQS, IFR];
240
+ export const publications = [MIZAN, IFCCM, IFQS, IFR, KANON];
209
241
  /** Where the generated files are downloaded from: this repository's `commons/` folder on its default branch. */
210
242
  const DOWNLOAD_BASE = "https://raw.githubusercontent.com/intellectual-frontiers/.github/main/commons/";
211
243
  /** The exports of the ontology (0019-mizan-integrations FR-010): everything but its Turtle, by its path from commons' folder. */
@@ -1,4 +1,5 @@
1
1
  import { type Result } from "@intellectual-frontiers/core";
2
+ import { type Table } from "@intellectual-frontiers/kanon";
2
3
  import { type LevelKey } from "@intellectual-frontiers/mizan/levels";
3
4
  /** The name of a library's manifest in its folder. */
4
5
  export declare const LIBRARY_FILE = "library.ts";
@@ -27,7 +28,11 @@ export type Library = {
27
28
  readonly summary?: string;
28
29
  /** Where it is published: always `github` (the GitHub package registry of the organization), and `npm` as well where a decision about that package has made it so (FR-015 and FR-016). */
29
30
  readonly distribution: readonly Registry[];
31
+ /** The table of its layers where it is built to Kanon (commons 0033-kanon FR-010); none where it is not. */
32
+ readonly kanon?: Table;
30
33
  };
34
+ /** The lowest conformance level that requires a library to declare `kanon`; none yet (0033-kanon FR-014, OQ-1): a level asks for it by naming itself here. */
35
+ export declare const KANON_REQUIRED_FROM: LevelKey | undefined;
31
36
  /** The registries a library may be published to: the kinds only, never a host or a credential (0027-commons-libraries FR-018). */
32
37
  export declare const REGISTRIES: readonly ["github", "npm"];
33
38
  export type Registry = (typeof REGISTRIES)[number];
package/dist/libraries.js CHANGED
@@ -80,8 +80,9 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
80
80
  * @module
81
81
  */
82
82
  import process from "node:process";
83
- import { array, describe, formatDecodeError, literal, object, string, err, ok, } from "@intellectual-frontiers/core";
83
+ import { array, describe, formatDecodeError, literal, object, unknownValue, string, err, ok, } from "@intellectual-frontiers/core";
84
84
  import { exportedLiteral } from "@intellectual-frontiers/formats/ts-literal";
85
+ import { decodeTable } from "@intellectual-frontiers/kanon";
85
86
  import { existsSync, readDirSync, readTextFileSync, writeTextFileSync } from "@intellectual-frontiers/system/fs";
86
87
  import { stdio } from "@intellectual-frontiers/system";
87
88
  import { spawn } from "@intellectual-frontiers/system/proc";
@@ -101,6 +102,8 @@ function bounds(spec) {
101
102
  const to = spec.indexOf(`\n${END}\n`, from);
102
103
  return from < 0 || to < 0 ? undefined : { from: from + 1, to: to + 1 };
103
104
  }
105
+ /** The lowest conformance level that requires a library to declare `kanon`; none yet (0033-kanon FR-014, OQ-1): a level asks for it by naming itself here. */
106
+ export const KANON_REQUIRED_FROM = undefined;
104
107
  /** The registries a library may be published to: the kinds only, never a host or a credential (0027-commons-libraries FR-018). */
105
108
  export const REGISTRIES = ["github", "npm"];
106
109
  /** Where a manifest that declares no distribution is published. */
@@ -119,8 +122,8 @@ const nameDecoder = (input, path = "$") => {
119
122
  ? r
120
123
  : err({ kind: "decode", path, expected: "a name of lower-case letters, digits and hyphens", found: describe(input) });
121
124
  };
122
- const body = object({ name: nameDecoder, verify: nonEmpty, version: nonEmpty, exports: array(nonEmpty) }, { level: literal(...LEVELS), specKit: nonEmpty, summary: nonEmpty, distribution: array(literal(...REGISTRIES)) });
123
- const FIELDS = ["name", "level", "specKit", "verify", "version", "exports", "summary", "distribution"];
125
+ const body = object({ name: nameDecoder, verify: nonEmpty, version: nonEmpty, exports: array(nonEmpty) }, { level: literal(...LEVELS), specKit: nonEmpty, summary: nonEmpty, distribution: array(literal(...REGISTRIES)), kanon: unknownValue });
126
+ const FIELDS = ["name", "level", "specKit", "verify", "version", "exports", "summary", "distribution", "kanon"];
124
127
  /** The manifest read from the text of its file: `export const library = { ... }` and no other export, read as data and never run (0027-commons-libraries FR-012). */
125
128
  export function decodeLibrarySource(source) {
126
129
  const exports = source.split("\n").filter((l) => /^export\s/.test(l));
@@ -145,6 +148,13 @@ export function decodeLibrarySource(source) {
145
148
  return err("library.distribution lists each registry once and at least one (FR-015)");
146
149
  if (!distribution.includes("github"))
147
150
  return err("library.distribution includes github: a library is published to the GitHub package registry whatever else it is published to (FR-015, FR-016)");
151
+ let kanon;
152
+ if (v.kanon !== undefined) {
153
+ const t = decodeTable(v.kanon);
154
+ if (t.kind === "err")
155
+ return err(`library.${t.error} (0033-kanon FR-010)`);
156
+ kanon = t.value;
157
+ }
148
158
  return ok({
149
159
  name: v.name,
150
160
  level: v.level ?? DEFAULT_LIBRARY_LEVEL,
@@ -154,6 +164,7 @@ export function decodeLibrarySource(source) {
154
164
  exports: v.exports,
155
165
  ...(v.summary === undefined ? {} : { summary: v.summary }),
156
166
  distribution,
167
+ ...(kanon === undefined ? {} : { kanon }),
157
168
  });
158
169
  }
159
170
  /** The manifests of `commons/*`, in the order of the folders' names: every folder that holds a `library.ts`. */
@@ -232,6 +243,10 @@ export function manifestFindings(repo) {
232
243
  const verifyText = script === undefined ? "" : scriptText(`${dir}/package.json`, script);
233
244
  if (rankOf(l.level) >= 1 && rankOf(l.level) < rankOf("L3") && !verifyText.includes(`--level ${l.level}`))
234
245
  found.push(`commons/${f.dir}: the manifest declares ${l.level} and the verify script does not run the Mizan check with --level ${l.level} (0028-conformance-levels FR-013)`);
246
+ if (l.kanon !== undefined && !verifyText.includes("kanon/src/check.ts"))
247
+ found.push(`commons/${f.dir}: the manifest declares kanon and the verify script does not run the check of the table (bun ../kanon/src/check.ts) (0033-kanon FR-014)`);
248
+ if (KANON_REQUIRED_FROM !== undefined && rankOf(l.level) >= rankOf(KANON_REQUIRED_FROM) && l.kanon === undefined)
249
+ found.push(`commons/${f.dir}: the manifest declares ${l.level}, which requires kanon, and declares none (0033-kanon FR-014)`);
235
250
  }
236
251
  return found;
237
252
  }
@@ -48,7 +48,8 @@ export type RegisterDocuments = {
48
48
  };
49
49
  /**
50
50
  * The register as OSCAL 1.2.3: the component definition and the assessment results, rendered (0003-mizan FR-021, FR-022). Where `register.enforcement` names a file, its text is the register
51
- * and `input.enforcement` is not read (FR-043); the same bytes come for the same register wherever its file is.
51
+ * and `input.enforcement` is not read (FR-043); the same bytes come for the same register wherever its file is. Both are written here, from the rows, and not by a library of exchange formats:
52
+ * the register's own vocabulary (a mechanism, a proof, a waiver) is Mizan's.
52
53
  */
53
54
  export declare function registerDocuments(input: RegisterInput, register?: RegisterOptions): Promise<RegisterDocuments>;
54
55
  /** What the register may be told besides its folder (0003-mizan FR-043): where its `enforcement.tsv` is, where it is not `enforcement.tsv` of the folder. */
@@ -11,7 +11,7 @@
11
11
  * --label TEXT the name the documents give the folder (default `Intellectual Frontiers commons`)
12
12
  *
13
13
  * @remarks
14
- * The two documents are written by the kernel's OSCAL writers (`kernel/oscal.ts`, OSCAL 1.2.3), so that the same bytes come for the same folder: every `uuid` is a version 5 UUID of a
14
+ * The two documents are written here, as OSCAL 1.2.3, so that the same bytes come for the same folder: every `uuid` is a version 5 UUID of a
15
15
  * stable name, every list is in an order of its own, and no clock is read (`last-modified` is `1970-01-01T00:00:00Z`; the `version` is the first 12 characters of the SHA-256 of the
16
16
  * register's rows). A requirement's control id is `spec-<slug>.<fr>` in lower case. A requirement a test proves has one passing observation for each test file, with the SHA-256 of
17
17
  * the file as evidence; one that is only reviewed is `accepted` (it has no test); one that has no proof, whatever its row says, is a `gap`. What OSCAL does not say, the command that
@@ -39,11 +39,9 @@
39
39
  */
40
40
  import process from "node:process";
41
41
  import { fileURLToPath } from "node:url";
42
- import { assessmentResults, componentDefinition, renderOscal, } from "@intellectual-frontiers/grc/oscal";
43
- import { instantOf, } from "@intellectual-frontiers/grc/grc";
44
42
  import { sha256 } from "@intellectual-frontiers/crypto/sha256";
45
43
  import { parseSpec, proofsOf } from "@intellectual-frontiers/mizan/trace";
46
- import { NAMESPACE_URL, uuidV5 } from "@intellectual-frontiers/crypto/uuid";
44
+ import { NAMESPACE_URL, uuidV5, uuidV5Of } from "@intellectual-frontiers/crypto/uuid";
47
45
  import { existsSync, mkdirSync, readDirSync, readTextFileSync, writeTextFileSync } from "@intellectual-frontiers/system/fs";
48
46
  import { stdio } from "@intellectual-frontiers/system";
49
47
  import { readSources } from "@intellectual-frontiers/mizan/host/trace";
@@ -55,11 +53,9 @@ export const RESULTS_FILE = "mizan-register-results.auto.oscal.json";
55
53
  /** The command that writes the files again. */
56
54
  export const RUN = "bun commons/libraries/src/oscal-register.ts";
57
55
  /** The instant the documents give as their `last-modified`: the register reads no clock (0003-mizan FR-022). */
58
- const NO_CLOCK = instantOf("1970-01-01T00:00:00Z") ?? absurdInstant();
59
- /** Never returns: the epoch is an instant, so `instantOf` has no reason to refuse it. */
60
- function absurdInstant() {
61
- throw new Error("1970-01-01T00:00:00Z is an instant");
62
- }
56
+ const NO_CLOCK = "1970-01-01T00:00:00.000Z";
57
+ /** The version of OSCAL the documents are written as. */
58
+ const OSCAL_VERSION = "1.2.3";
63
59
  const REGISTER_IRI = "https://www.intellectualfrontiers.com/ontology/mizan-register";
64
60
  const isMechanism = (x) => x === "check" || x === "gate" || x === "review" || x === "none";
65
61
  const byText = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
@@ -157,117 +153,145 @@ export function registerRows(input) {
157
153
  });
158
154
  });
159
155
  }
160
- function summaryOf(row, catalog) {
161
- return {
162
- id: row.requirement,
163
- title: row.title,
164
- implements: [{ catalog, id: row.controlId }],
165
- severity: "info",
166
- cadence: "on every commit",
167
- };
168
- }
169
- /** What a requirement's finding says: a passing observation for each test file that proves it, else `accepted` where a person reviewed it, else a `gap`. */
170
- async function findingsOf(row, control, tests) {
171
- const subject = { kind: "specification", id: row.spec };
172
- const base = { control, subject, severity: "info", at: NO_CLOCK };
156
+ /** What a requirement's observations say: a passing observation for each test file that proves it, else `accepted` where a person reviewed it, else a `gap`. */
157
+ async function observationsOf(row, tests) {
173
158
  if (row.files.length > 0)
174
159
  return Promise.all(row.files.map(async (file) => ({
175
- ...base,
160
+ row,
176
161
  status: "pass",
177
162
  outcome: "pass",
178
163
  title: `proved by ${file}`,
179
164
  detail: `${row.requirement} is named by a proof in ${file}.`,
180
- evidence: [await sha256(tests.get(file) ?? "")],
165
+ evidence: await sha256(tests.get(file) ?? ""),
181
166
  })));
182
167
  if (row.mechanism === "review")
183
168
  return [
184
- {
185
- ...base,
186
- status: "warn",
187
- outcome: "accepted",
188
- waiver: row.by,
189
- title: "reviewed by a person",
190
- detail: `${row.requirement} has no test; a person reviews it (${row.by}): ${row.note}`,
191
- evidence: [],
192
- },
169
+ { row, status: "warn", outcome: "accepted", waiver: row.by, title: "reviewed by a person", detail: `${row.requirement} has no test; a person reviews it (${row.by}): ${row.note}` },
193
170
  ];
194
- const status = "gap";
195
171
  return [
196
172
  {
197
- ...base,
198
- status,
199
- outcome: status,
173
+ row,
174
+ status: "gap",
175
+ outcome: "gap",
200
176
  title: "no test proves it",
201
177
  detail: `${row.requirement} is ${row.mechanism === "none" ? "not enforced" : `enforced by ${row.mechanism} (${row.by})`}, and no proof in the tests names it: ${row.note}`,
202
- evidence: [],
203
178
  },
204
179
  ];
205
180
  }
206
181
  /**
207
182
  * The register as OSCAL 1.2.3: the component definition and the assessment results, rendered (0003-mizan FR-021, FR-022). Where `register.enforcement` names a file, its text is the register
208
- * and `input.enforcement` is not read (FR-043); the same bytes come for the same register wherever its file is.
183
+ * and `input.enforcement` is not read (FR-043); the same bytes come for the same register wherever its file is. Both are written here, from the rows, and not by a library of exchange formats:
184
+ * the register's own vocabulary (a mechanism, a proof, a waiver) is Mizan's.
209
185
  */
210
186
  export async function registerDocuments(input, register = {}) {
211
187
  const rows = registerRows(register.enforcement === undefined ? input : { ...input, enforcement: enforcementAt(register.enforcement) });
212
188
  const catalog = "the specifications of its Mizan folder";
213
- const pairs = rows.map((row) => ({ row, control: summaryOf(row, catalog) }));
214
- const controls = pairs.map((p) => p.control);
215
189
  const tests = new Map(input.tests.map((t) => [t.path, t.text]));
216
190
  const version = (await sha256(JSON.stringify(rows.map((r) => [r.requirement, r.mechanism, r.by, r.note, r.title, r.files])))).slice(0, 12);
217
191
  const namespace = await uuidV5(NAMESPACE_URL, REGISTER_IRI);
218
- const options = (what) => ({
219
- namespace,
220
- lastModified: NO_CLOCK,
221
- version,
222
- propNamespace: `${REGISTER_IRI}#`,
192
+ const id = (...parts) => uuidV5Of(namespace, parts);
193
+ const ns = `${REGISTER_IRI}#`;
194
+ const prop = (name, value) => ({ name, ns, value });
195
+ const metadata = (what) => ({
223
196
  title: `Mizan register of ${input.label}: ${what} (generated by ${RUN}; do not edit)`,
224
- controlId: (ref) => ref.id,
197
+ "last-modified": NO_CLOCK,
198
+ version,
199
+ "oscal-version": OSCAL_VERSION,
225
200
  });
226
- const definition = await componentDefinition(controls, {
227
- id: input.label,
228
- title: input.label,
229
- description: `${input.label}, whose requirements are written in the specifications of its Mizan folder.`,
230
- type: "software",
231
- }, options("component definition"));
232
- const byControl = new Map(rows.map((r) => [r.controlId, r]));
233
- const inner = definition["component-definition"];
234
- const withMechanism = {
201
+ const catalogId = await id("catalog", input.label);
202
+ const implemented = await Promise.all(rows.map(async (row) => ({
203
+ uuid: await id("implemented-requirement", input.label, row.controlId),
204
+ "control-id": row.controlId,
205
+ description: `${row.requirement} (${row.title})`,
206
+ props: [prop("control", row.requirement), prop("mechanism", row.mechanism), prop("proofs", String(row.files.length))],
207
+ })));
208
+ const componentDefinition = {
235
209
  "component-definition": {
236
- ...inner,
237
- components: inner.components.map((c) => ({
238
- ...c,
239
- ...(c["control-implementations"] === undefined
240
- ? {}
241
- : {
242
- "control-implementations": c["control-implementations"].map((ci) => ({
243
- ...ci,
244
- "implemented-requirements": ci["implemented-requirements"].map((ir) => {
245
- const row = byControl.get(ir["control-id"]);
246
- return row === undefined
247
- ? ir
248
- : {
249
- ...ir,
250
- props: [
251
- ...ir.props,
252
- { name: "mechanism", ns: `${REGISTER_IRI}#`, value: row.mechanism },
253
- { name: "proofs", ns: `${REGISTER_IRI}#`, value: String(row.files.length) },
254
- ],
255
- };
256
- }),
257
- })),
258
- }),
259
- })),
210
+ uuid: await id("component-definition", input.label),
211
+ metadata: metadata("component definition"),
212
+ components: [
213
+ {
214
+ uuid: await id("component", input.label),
215
+ type: "software",
216
+ title: input.label,
217
+ description: `${input.label}, whose requirements are written in ${catalog}.`,
218
+ "control-implementations": [
219
+ {
220
+ uuid: await id("control-implementation", input.label),
221
+ source: `#${catalogId}`,
222
+ description: `The controls of ${catalog} that ${input.label} implements.`,
223
+ "implemented-requirements": implemented,
224
+ },
225
+ ],
226
+ },
227
+ ],
228
+ "back-matter": { resources: [{ uuid: catalogId, title: `The controls of ${catalog}` }] },
260
229
  },
261
230
  };
262
- const assessment = {
263
- pack: { id: input.label, title: `Mizan register of ${input.label}` },
264
- at: NO_CLOCK,
265
- controls,
266
- subjects: [...new Set(rows.map((r) => r.spec))].sort(byText).map((id) => ({ kind: "specification", id })),
267
- findings: (await Promise.all(pairs.map((p) => findingsOf(p.row, p.control, tests)))).flat(),
231
+ const specs = [...new Set(rows.map((r) => r.spec))].sort(byText);
232
+ const inventory = await Promise.all(specs.map(async (spec) => ({
233
+ uuid: await id("inventory-item", input.label, spec),
234
+ description: `specification ${spec}`,
235
+ props: [{ name: "asset-id", value: spec }, prop("subject-kind", "specification")],
236
+ })));
237
+ const inventoryOf = new Map(specs.map((spec, i) => [spec, inventory[i]?.uuid ?? ""]));
238
+ const observed = (await Promise.all(rows.map((row) => observationsOf(row, tests)))).flat();
239
+ const observations = await Promise.all(observed.map(async (o, i) => {
240
+ const title = `${o.row.requirement} on specification ${o.row.spec}: ${o.title}`;
241
+ return {
242
+ uuid: await id("observation", input.label, String(i), title),
243
+ title,
244
+ description: o.detail,
245
+ props: [
246
+ prop("control", o.row.requirement),
247
+ prop("outcome", o.outcome),
248
+ prop("status", o.status),
249
+ prop("severity", "info"),
250
+ ...(o.waiver === undefined ? [] : [prop("waiver", o.waiver)]),
251
+ ],
252
+ methods: ["TEST"],
253
+ types: ["finding"],
254
+ subjects: [{ "subject-uuid": inventoryOf.get(o.row.spec) ?? "", type: "inventory-item", title: `specification ${o.row.spec}` }],
255
+ ...(o.evidence === undefined
256
+ ? {}
257
+ : { "relevant-evidence": [{ description: `evidence of SHA-256 ${o.evidence}`, props: [prop("sha256", o.evidence)] }] }),
258
+ collected: NO_CLOCK,
259
+ };
260
+ }));
261
+ const findings = await Promise.all(rows.map(async (row) => {
262
+ const own = observed.flatMap((o, i) => (o.row === row ? [{ o, uuid: observations[i]?.uuid ?? "" }] : []));
263
+ const outcome = own.some((x) => x.o.outcome === "gap") ? "gap" : own.some((x) => x.o.outcome === "accepted") ? "accepted" : "pass";
264
+ return {
265
+ uuid: await id("finding", input.label, row.controlId),
266
+ title: row.controlId,
267
+ description: `${row.controlId}: ${outcome}, by ${row.requirement}.`,
268
+ props: [prop("outcome", outcome), prop("control", row.requirement)],
269
+ target: { type: "objective-id", "target-id": row.controlId, status: { state: outcome === "gap" ? "not-satisfied" : "satisfied" } },
270
+ "related-observations": own.map((x) => ({ "observation-uuid": x.uuid })),
271
+ };
272
+ }));
273
+ const plan = await id("assessment-plan", input.label);
274
+ const assessmentResults = {
275
+ "assessment-results": {
276
+ uuid: await id("assessment-results", input.label),
277
+ metadata: metadata("assessment results"),
278
+ "import-ap": { href: `#${plan}` },
279
+ results: [
280
+ {
281
+ uuid: await id("result", input.label),
282
+ title: `Mizan register of ${input.label} as of ${NO_CLOCK}`,
283
+ description: `The findings of Mizan register of ${input.label}, assessed at ${NO_CLOCK}.`,
284
+ start: NO_CLOCK,
285
+ "local-definitions": { "inventory-items": inventory },
286
+ "reviewed-controls": { "control-selections": [{ "include-controls": rows.map((r) => ({ "control-id": r.controlId })) }] },
287
+ observations,
288
+ findings,
289
+ },
290
+ ],
291
+ "back-matter": { resources: [{ uuid: plan, title: `The assessment plan of Mizan register of ${input.label}` }] },
292
+ },
268
293
  };
269
- const results = await assessmentResults(assessment, options("assessment results"));
270
- return { componentDefinition: renderOscal(withMechanism), assessmentResults: renderOscal(results) };
294
+ return { componentDefinition: `${JSON.stringify(componentDefinition, null, 2)}\n`, assessmentResults: `${JSON.stringify(assessmentResults, null, 2)}\n` };
271
295
  }
272
296
  /** The text of the register at an explicit path, with LF line ends; an error that names the file where it is not there. */
273
297
  function enforcementAt(path) {
@@ -116,6 +116,16 @@ export const LIBRARY_CI = {
116
116
  nodeTests: 'node --test "suite/**/*.test.ts"',
117
117
  systems: ["windows-latest", "macos-latest", "ubuntu-latest"],
118
118
  },
119
+ headless: {
120
+ comment: lines("Headless, the contract of a program with no window in layers (governance, logical, the command-line surface), a library lifted out of `commons/ts` (commons 0032-lifting-libraries): its own `verify` (the compiler, the specification checker, the layers and trace checks, its tests and the", "packing of its package with the inspection of its declarations) on Bun and its tests on Node 26, on Windows, macOS and Linux, because the package runs on all three.").trimEnd(),
121
+ nodeTests: 'node --test "suite/**/*.test.ts"',
122
+ systems: ["windows-latest", "macos-latest", "ubuntu-latest"],
123
+ },
124
+ kanon: {
125
+ comment: lines("Kanon, the pattern of a library built in three layers (commons 0033-kanon): its own `verify` (the compiler, the specification checker, the trace check, its tests and the", "packing of its package with the inspection of its declarations) on Bun and its tests on Node 26, on Windows, macOS and Linux, because the package runs on all three.").trimEnd(),
126
+ nodeTests: 'node --test "suite/**/*.test.ts"',
127
+ systems: ["windows-latest", "macos-latest", "ubuntu-latest"],
128
+ },
119
129
  telemetry: {
120
130
  comment: lines("Telemetry, OpenTelemetry-native signals as one typed library, a library lifted out of `commons/ts` (commons 0032-lifting-libraries): its own `verify` (the compiler, the specification checker, the trace, its tests and the", "packing of its package with the inspection of its declarations) on Bun and its tests on Node 26, on Windows, macOS and Linux, because the package runs on all three.").trimEnd(),
121
131
  nodeTests: 'node --test "suite/**/*.test.ts"',
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@intellectual-frontiers/libraries",
3
- "version": "0.1.0",
3
+ "version": "0.2.1",
4
4
  "description": "The libraries of a repository of commons as code: the manifest of a library and the check that it and its folder agree, which libraries a change affects, the typed workflows of GitHub Actions and their generator, the pinned Bun, the packer that builds, inspects and packs a library for npm with its declarations, and the commands that hold a whole repository to Mizan (check, change control, versions, the register and the ontologies).",
5
5
  "license": "MIT",
6
6
  "type": "module",
@@ -101,14 +101,14 @@
101
101
  "@intellectual-frontiers/crypto": "0.1.4",
102
102
  "@intellectual-frontiers/formats": "0.1.4",
103
103
  "@intellectual-frontiers/githost": "0.1.2",
104
- "@intellectual-frontiers/grc": "0.1.2",
104
+ "@intellectual-frontiers/kanon": "0.1.0",
105
105
  "@intellectual-frontiers/mizan": "0.1.1",
106
- "@intellectual-frontiers/net": "0.1.3",
107
- "@intellectual-frontiers/ontology": "0.1.4",
108
- "@intellectual-frontiers/quality": "0.1.3",
106
+ "@intellectual-frontiers/net": "0.1.5",
107
+ "@intellectual-frontiers/ontology": "0.2.0",
108
+ "@intellectual-frontiers/quality": "0.2.0",
109
109
  "@intellectual-frontiers/rdf": "0.1.4",
110
- "@intellectual-frontiers/system": "0.1.4",
111
- "@intellectual-frontiers/terminal": "0.1.4"
110
+ "@intellectual-frontiers/system": "0.1.6",
111
+ "@intellectual-frontiers/terminal": "0.1.6"
112
112
  },
113
113
  "files": [
114
114
  "dist",
@@ -37,6 +37,7 @@ import {
37
37
  import * as ifccmOntology from "@intellectual-frontiers/ontology/ifccm";
38
38
  import * as ifrOntology from "@intellectual-frontiers/ontology/ifr";
39
39
  import * as ifqsOntology from "@intellectual-frontiers/ontology/ifqs";
40
+ import * as kanonOntology from "@intellectual-frontiers/ontology/kanon";
40
41
  import { formatRdfFinding, type OntologyFile, validate } from "@intellectual-frontiers/rdf";
41
42
  import { stdio } from "@intellectual-frontiers/system";
42
43
  import { exportDcat } from "@intellectual-frontiers/mizan/integrations/pure/export-dcat";
@@ -241,8 +242,40 @@ export const IFR: OntologyPublication = {
241
242
  license: CC0,
242
243
  };
243
244
 
245
+ /** The ontology of Kanon (commons 0033-kanon), as it is published. */
246
+ export const KANON: OntologyPublication = {
247
+ name: "kanon",
248
+ ns: { prefix: "kanon", iri: kanonOntology.KANON.iri },
249
+ idNs: { prefix: "mzid", iri: MZID.iri },
250
+ curies: [
251
+ ["kanon", kanonOntology.KANON.iri],
252
+ ["mz", MZ.iri],
253
+ ["xsd", "http://www.w3.org/2001/XMLSchema#"],
254
+ ["rdfs", "http://www.w3.org/2000/01/rdf-schema#"],
255
+ ["skos", "http://www.w3.org/2004/02/skos/core#"],
256
+ ["dcterms", "http://purl.org/dc/terms/"],
257
+ ["prov", "http://www.w3.org/ns/prov#"],
258
+ ["sh", "http://www.w3.org/ns/shacl#"],
259
+ ],
260
+ files: kanonOntology.files,
261
+ ontology: kanonOntology.kanonOntology,
262
+ classes: kanonOntology.classes,
263
+ properties: kanonOntology.properties,
264
+ terms: kanonOntology.terms,
265
+ schemas: [kanonOntology.Layer],
266
+ lists: listsOf("kanon", [["Layer", kanonOntology.layers]]),
267
+ source: "commons/ontology/src/kanon/*.ts",
268
+ run: RUN,
269
+ shapes: { prefix: "kanonsh", iri: "https://www.intellectualfrontiers.com/ontology/kanon-shapes#" },
270
+ schemasIri: "https://www.intellectualfrontiers.com/ontology/kanon-schemas",
271
+ sssomSetId: "https://www.intellectualfrontiers.com/ontology/kanon-mappings",
272
+ sssomCuries: { dcterms: "http://purl.org/dc/terms/", prov: "http://www.w3.org/ns/prov#", sh: "http://www.w3.org/ns/shacl#" },
273
+ viewTitle: "Kanon: the ontology",
274
+ license: CC0,
275
+ };
276
+
244
277
  /** The ontologies of commons that are published, each from its own typed modules: Mizan's, then the ones its specifications define. */
245
- export const publications: readonly OntologyPublication[] = [MIZAN, IFCCM, IFQS, IFR];
278
+ export const publications: readonly OntologyPublication[] = [MIZAN, IFCCM, IFQS, IFR, KANON];
246
279
 
247
280
  /** Where the generated files are downloaded from: this repository's `commons/` folder on its default branch. */
248
281
  const DOWNLOAD_BASE = "https://raw.githubusercontent.com/intellectual-frontiers/.github/main/commons/";
package/src/libraries.ts CHANGED
@@ -35,12 +35,14 @@ import {
35
35
  formatDecodeError,
36
36
  literal,
37
37
  object,
38
+ unknownValue,
38
39
  string,
39
40
  err,
40
41
  ok,
41
42
  type Result,
42
43
  } from "@intellectual-frontiers/core";
43
44
  import { exportedLiteral } from "@intellectual-frontiers/formats/ts-literal";
45
+ import { decodeTable, type Table } from "@intellectual-frontiers/kanon";
44
46
  import { existsSync, readDirSync, readTextFileSync, writeTextFileSync } from "@intellectual-frontiers/system/fs";
45
47
  import { stdio } from "@intellectual-frontiers/system";
46
48
  import { spawn } from "@intellectual-frontiers/system/proc";
@@ -82,8 +84,13 @@ export type Library = {
82
84
  readonly summary?: string;
83
85
  /** Where it is published: always `github` (the GitHub package registry of the organization), and `npm` as well where a decision about that package has made it so (FR-015 and FR-016). */
84
86
  readonly distribution: readonly Registry[];
87
+ /** The table of its layers where it is built to Kanon (commons 0033-kanon FR-010); none where it is not. */
88
+ readonly kanon?: Table;
85
89
  };
86
90
 
91
+ /** The lowest conformance level that requires a library to declare `kanon`; none yet (0033-kanon FR-014, OQ-1): a level asks for it by naming itself here. */
92
+ export const KANON_REQUIRED_FROM: LevelKey | undefined = undefined;
93
+
87
94
  /** The registries a library may be published to: the kinds only, never a host or a credential (0027-commons-libraries FR-018). */
88
95
  export const REGISTRIES = ["github", "npm"] as const;
89
96
  export type Registry = (typeof REGISTRIES)[number];
@@ -104,9 +111,9 @@ const nameDecoder: Decoder<string> = (input, path = "$") => {
104
111
  };
105
112
  const body = object(
106
113
  { name: nameDecoder, verify: nonEmpty, version: nonEmpty, exports: array(nonEmpty) },
107
- { level: literal(...LEVELS), specKit: nonEmpty, summary: nonEmpty, distribution: array(literal(...REGISTRIES)) },
114
+ { level: literal(...LEVELS), specKit: nonEmpty, summary: nonEmpty, distribution: array(literal(...REGISTRIES)), kanon: unknownValue },
108
115
  );
109
- const FIELDS = ["name", "level", "specKit", "verify", "version", "exports", "summary", "distribution"] as const;
116
+ const FIELDS = ["name", "level", "specKit", "verify", "version", "exports", "summary", "distribution", "kanon"] as const;
110
117
 
111
118
  /** The manifest read from the text of its file: `export const library = { ... }` and no other export, read as data and never run (0027-commons-libraries FR-012). */
112
119
  export function decodeLibrarySource(source: string): Result<Library, string> {
@@ -130,6 +137,12 @@ export function decodeLibrarySource(source: string): Result<Library, string> {
130
137
  return err(
131
138
  "library.distribution includes github: a library is published to the GitHub package registry whatever else it is published to (FR-015, FR-016)",
132
139
  );
140
+ let kanon: Table | undefined;
141
+ if (v.kanon !== undefined) {
142
+ const t = decodeTable(v.kanon);
143
+ if (t.kind === "err") return err(`library.${t.error} (0033-kanon FR-010)`);
144
+ kanon = t.value;
145
+ }
133
146
  return ok({
134
147
  name: v.name,
135
148
  level: v.level ?? DEFAULT_LIBRARY_LEVEL,
@@ -139,6 +152,7 @@ export function decodeLibrarySource(source: string): Result<Library, string> {
139
152
  exports: v.exports,
140
153
  ...(v.summary === undefined ? {} : { summary: v.summary }),
141
154
  distribution,
155
+ ...(kanon === undefined ? {} : { kanon }),
142
156
  });
143
157
  }
144
158
 
@@ -231,6 +245,12 @@ export function manifestFindings(repo: string): readonly string[] {
231
245
  found.push(
232
246
  `commons/${f.dir}: the manifest declares ${l.level} and the verify script does not run the Mizan check with --level ${l.level} (0028-conformance-levels FR-013)`,
233
247
  );
248
+ if (l.kanon !== undefined && !verifyText.includes("kanon/src/check.ts"))
249
+ found.push(
250
+ `commons/${f.dir}: the manifest declares kanon and the verify script does not run the check of the table (bun ../kanon/src/check.ts) (0033-kanon FR-014)`,
251
+ );
252
+ if (KANON_REQUIRED_FROM !== undefined && rankOf(l.level) >= rankOf(KANON_REQUIRED_FROM) && l.kanon === undefined)
253
+ found.push(`commons/${f.dir}: the manifest declares ${l.level}, which requires kanon, and declares none (0033-kanon FR-014)`);
234
254
  }
235
255
  return found;
236
256
  }
@@ -11,7 +11,7 @@
11
11
  * --label TEXT the name the documents give the folder (default `Intellectual Frontiers commons`)
12
12
  *
13
13
  * @remarks
14
- * The two documents are written by the kernel's OSCAL writers (`kernel/oscal.ts`, OSCAL 1.2.3), so that the same bytes come for the same folder: every `uuid` is a version 5 UUID of a
14
+ * The two documents are written here, as OSCAL 1.2.3, so that the same bytes come for the same folder: every `uuid` is a version 5 UUID of a
15
15
  * stable name, every list is in an order of its own, and no clock is read (`last-modified` is `1970-01-01T00:00:00Z`; the `version` is the first 12 characters of the SHA-256 of the
16
16
  * register's rows). A requirement's control id is `spec-<slug>.<fr>` in lower case. A requirement a test proves has one passing observation for each test file, with the SHA-256 of
17
17
  * the file as evidence; one that is only reviewed is `accepted` (it has no test); one that has no proof, whatever its row says, is a `gap`. What OSCAL does not say, the command that
@@ -39,26 +39,9 @@
39
39
  */
40
40
  import process from "node:process";
41
41
  import { fileURLToPath } from "node:url";
42
- import {
43
- assessmentResults,
44
- componentDefinition,
45
- type OscalAssessmentResults,
46
- type OscalComponentDefinition,
47
- type OscalOptions,
48
- renderOscal,
49
- } from "@intellectual-frontiers/grc/oscal";
50
- import {
51
- type Assessment,
52
- type ControlSummary,
53
- type Finding,
54
- type Instant,
55
- instantOf,
56
- type Status,
57
- type SubjectRef,
58
- } from "@intellectual-frontiers/grc/grc";
59
42
  import { sha256 } from "@intellectual-frontiers/crypto/sha256";
60
43
  import { type Cited, parseSpec, proofsOf, type SourceFile } from "@intellectual-frontiers/mizan/trace";
61
- import { NAMESPACE_URL, uuidV5 } from "@intellectual-frontiers/crypto/uuid";
44
+ import { NAMESPACE_URL, type Uuid, uuidV5, uuidV5Of } from "@intellectual-frontiers/crypto/uuid";
62
45
  import { existsSync, mkdirSync, readDirSync, readTextFileSync, writeTextFileSync } from "@intellectual-frontiers/system/fs";
63
46
  import { stdio } from "@intellectual-frontiers/system";
64
47
  import { readSources } from "@intellectual-frontiers/mizan/host/trace";
@@ -108,12 +91,10 @@ export const RESULTS_FILE = "mizan-register-results.auto.oscal.json";
108
91
  export const RUN = "bun commons/libraries/src/oscal-register.ts";
109
92
 
110
93
  /** The instant the documents give as their `last-modified`: the register reads no clock (0003-mizan FR-022). */
111
- const NO_CLOCK: Instant = instantOf("1970-01-01T00:00:00Z") ?? absurdInstant();
94
+ const NO_CLOCK = "1970-01-01T00:00:00.000Z";
112
95
 
113
- /** Never returns: the epoch is an instant, so `instantOf` has no reason to refuse it. */
114
- function absurdInstant(): never {
115
- throw new Error("1970-01-01T00:00:00Z is an instant");
116
- }
96
+ /** The version of OSCAL the documents are written as. */
97
+ const OSCAL_VERSION = "1.2.3";
117
98
 
118
99
  const REGISTER_IRI = "https://www.intellectualfrontiers.com/ontology/mizan-register";
119
100
  const isMechanism = (x: string): x is Mechanism => x === "check" || x === "gate" || x === "review" || x === "none";
@@ -214,52 +195,43 @@ export function registerRows(input: RegisterInput): readonly RegisterRow[] {
214
195
  });
215
196
  }
216
197
 
217
- function summaryOf(row: RegisterRow, catalog: string): ControlSummary {
218
- return {
219
- id: row.requirement,
220
- title: row.title,
221
- implements: [{ catalog, id: row.controlId }],
222
- severity: "info",
223
- cadence: "on every commit",
224
- };
225
- }
198
+ /** What one observation of the results says. */
199
+ type Observation = {
200
+ readonly row: RegisterRow;
201
+ readonly status: "pass" | "warn" | "gap";
202
+ readonly outcome: "pass" | "accepted" | "gap";
203
+ readonly title: string;
204
+ readonly detail: string;
205
+ readonly evidence?: string;
206
+ readonly waiver?: string;
207
+ };
226
208
 
227
- /** What a requirement's finding says: a passing observation for each test file that proves it, else `accepted` where a person reviewed it, else a `gap`. */
228
- async function findingsOf(row: RegisterRow, control: ControlSummary, tests: ReadonlyMap<string, string>): Promise<readonly Finding[]> {
229
- const subject: SubjectRef = { kind: "specification", id: row.spec };
230
- const base = { control, subject, severity: "info" as const, at: NO_CLOCK };
209
+ /** What a requirement's observations say: a passing observation for each test file that proves it, else `accepted` where a person reviewed it, else a `gap`. */
210
+ async function observationsOf(row: RegisterRow, tests: ReadonlyMap<string, string>): Promise<readonly Observation[]> {
231
211
  if (row.files.length > 0)
232
212
  return Promise.all(
233
- row.files.map(async (file): Promise<Finding> => ({
234
- ...base,
235
- status: "pass",
236
- outcome: "pass",
237
- title: `proved by ${file}`,
238
- detail: `${row.requirement} is named by a proof in ${file}.`,
239
- evidence: [await sha256(tests.get(file) ?? "")],
240
- })),
213
+ row.files.map(
214
+ async (file): Promise<Observation> => ({
215
+ row,
216
+ status: "pass",
217
+ outcome: "pass",
218
+ title: `proved by ${file}`,
219
+ detail: `${row.requirement} is named by a proof in ${file}.`,
220
+ evidence: await sha256(tests.get(file) ?? ""),
221
+ }),
222
+ ),
241
223
  );
242
224
  if (row.mechanism === "review")
243
225
  return [
244
- {
245
- ...base,
246
- status: "warn",
247
- outcome: "accepted",
248
- waiver: row.by,
249
- title: "reviewed by a person",
250
- detail: `${row.requirement} has no test; a person reviews it (${row.by}): ${row.note}`,
251
- evidence: [],
252
- },
226
+ { row, status: "warn", outcome: "accepted", waiver: row.by, title: "reviewed by a person", detail: `${row.requirement} has no test; a person reviews it (${row.by}): ${row.note}` },
253
227
  ];
254
- const status: Status = "gap";
255
228
  return [
256
229
  {
257
- ...base,
258
- status,
259
- outcome: status,
230
+ row,
231
+ status: "gap",
232
+ outcome: "gap",
260
233
  title: "no test proves it",
261
234
  detail: `${row.requirement} is ${row.mechanism === "none" ? "not enforced" : `enforced by ${row.mechanism} (${row.by})`}, and no proof in the tests names it: ${row.note}`,
262
- evidence: [],
263
235
  },
264
236
  ];
265
237
  }
@@ -269,76 +241,126 @@ export type RegisterDocuments = { readonly componentDefinition: string; readonly
269
241
 
270
242
  /**
271
243
  * The register as OSCAL 1.2.3: the component definition and the assessment results, rendered (0003-mizan FR-021, FR-022). Where `register.enforcement` names a file, its text is the register
272
- * and `input.enforcement` is not read (FR-043); the same bytes come for the same register wherever its file is.
244
+ * and `input.enforcement` is not read (FR-043); the same bytes come for the same register wherever its file is. Both are written here, from the rows, and not by a library of exchange formats:
245
+ * the register's own vocabulary (a mechanism, a proof, a waiver) is Mizan's.
273
246
  */
274
247
  export async function registerDocuments(input: RegisterInput, register: RegisterOptions = {}): Promise<RegisterDocuments> {
275
248
  const rows = registerRows(register.enforcement === undefined ? input : { ...input, enforcement: enforcementAt(register.enforcement) });
276
249
  const catalog = "the specifications of its Mizan folder";
277
- const pairs = rows.map((row) => ({ row, control: summaryOf(row, catalog) }));
278
- const controls = pairs.map((p) => p.control);
279
250
  const tests = new Map(input.tests.map((t) => [t.path, t.text]));
280
- const version = (await sha256(JSON.stringify(rows.map((r) => [r.requirement, r.mechanism, r.by, r.note, r.title, r.files])))).slice(
281
- 0,
282
- 12,
283
- );
284
- const namespace = await uuidV5(NAMESPACE_URL, REGISTER_IRI);
285
- const options = (what: string): OscalOptions => ({
286
- namespace,
287
- lastModified: NO_CLOCK,
288
- version,
289
- propNamespace: `${REGISTER_IRI}#`,
251
+ const version = (await sha256(JSON.stringify(rows.map((r) => [r.requirement, r.mechanism, r.by, r.note, r.title, r.files])))).slice(0, 12);
252
+ const namespace: Uuid = await uuidV5(NAMESPACE_URL, REGISTER_IRI);
253
+ const id = (...parts: readonly string[]): Promise<string> => uuidV5Of(namespace, parts);
254
+ const ns = `${REGISTER_IRI}#`;
255
+ const prop = (name: string, value: string): { readonly name: string; readonly ns: string; readonly value: string } => ({ name, ns, value });
256
+ const metadata = (what: string): Record<string, string> => ({
290
257
  title: `Mizan register of ${input.label}: ${what} (generated by ${RUN}; do not edit)`,
291
- controlId: (ref) => ref.id,
258
+ "last-modified": NO_CLOCK,
259
+ version,
260
+ "oscal-version": OSCAL_VERSION,
292
261
  });
293
- const definition = await componentDefinition(
294
- controls,
295
- {
296
- id: input.label,
297
- title: input.label,
298
- description: `${input.label}, whose requirements are written in the specifications of its Mizan folder.`,
299
- type: "software",
300
- },
301
- options("component definition"),
262
+ const catalogId = await id("catalog", input.label);
263
+ const implemented = await Promise.all(
264
+ rows.map(async (row) => ({
265
+ uuid: await id("implemented-requirement", input.label, row.controlId),
266
+ "control-id": row.controlId,
267
+ description: `${row.requirement} (${row.title})`,
268
+ props: [prop("control", row.requirement), prop("mechanism", row.mechanism), prop("proofs", String(row.files.length))],
269
+ })),
302
270
  );
303
- const byControl = new Map(rows.map((r) => [r.controlId, r]));
304
- const inner = definition["component-definition"];
305
- const withMechanism: OscalComponentDefinition = {
271
+ const componentDefinition = {
306
272
  "component-definition": {
307
- ...inner,
308
- components: inner.components.map((c) => ({
309
- ...c,
310
- ...(c["control-implementations"] === undefined
311
- ? {}
312
- : {
313
- "control-implementations": c["control-implementations"].map((ci) => ({
314
- ...ci,
315
- "implemented-requirements": ci["implemented-requirements"].map((ir) => {
316
- const row = byControl.get(ir["control-id"]);
317
- return row === undefined
318
- ? ir
319
- : {
320
- ...ir,
321
- props: [
322
- ...ir.props,
323
- { name: "mechanism", ns: `${REGISTER_IRI}#`, value: row.mechanism },
324
- { name: "proofs", ns: `${REGISTER_IRI}#`, value: String(row.files.length) },
325
- ],
326
- };
327
- }),
328
- })),
329
- }),
330
- })),
273
+ uuid: await id("component-definition", input.label),
274
+ metadata: metadata("component definition"),
275
+ components: [
276
+ {
277
+ uuid: await id("component", input.label),
278
+ type: "software",
279
+ title: input.label,
280
+ description: `${input.label}, whose requirements are written in ${catalog}.`,
281
+ "control-implementations": [
282
+ {
283
+ uuid: await id("control-implementation", input.label),
284
+ source: `#${catalogId}`,
285
+ description: `The controls of ${catalog} that ${input.label} implements.`,
286
+ "implemented-requirements": implemented,
287
+ },
288
+ ],
289
+ },
290
+ ],
291
+ "back-matter": { resources: [{ uuid: catalogId, title: `The controls of ${catalog}` }] },
331
292
  },
332
293
  };
333
- const assessment: Assessment = {
334
- pack: { id: input.label, title: `Mizan register of ${input.label}` },
335
- at: NO_CLOCK,
336
- controls,
337
- subjects: [...new Set(rows.map((r) => r.spec))].sort(byText).map((id) => ({ kind: "specification", id })),
338
- findings: (await Promise.all(pairs.map((p) => findingsOf(p.row, p.control, tests)))).flat(),
294
+ const specs = [...new Set(rows.map((r) => r.spec))].sort(byText);
295
+ const inventory = await Promise.all(
296
+ specs.map(async (spec) => ({
297
+ uuid: await id("inventory-item", input.label, spec),
298
+ description: `specification ${spec}`,
299
+ props: [{ name: "asset-id", value: spec }, prop("subject-kind", "specification")],
300
+ })),
301
+ );
302
+ const inventoryOf = new Map(specs.map((spec, i) => [spec, inventory[i]?.uuid ?? ""]));
303
+ const observed = (await Promise.all(rows.map((row) => observationsOf(row, tests)))).flat();
304
+ const observations = await Promise.all(
305
+ observed.map(async (o, i) => {
306
+ const title = `${o.row.requirement} on specification ${o.row.spec}: ${o.title}`;
307
+ return {
308
+ uuid: await id("observation", input.label, String(i), title),
309
+ title,
310
+ description: o.detail,
311
+ props: [
312
+ prop("control", o.row.requirement),
313
+ prop("outcome", o.outcome),
314
+ prop("status", o.status),
315
+ prop("severity", "info"),
316
+ ...(o.waiver === undefined ? [] : [prop("waiver", o.waiver)]),
317
+ ],
318
+ methods: ["TEST"],
319
+ types: ["finding"],
320
+ subjects: [{ "subject-uuid": inventoryOf.get(o.row.spec) ?? "", type: "inventory-item", title: `specification ${o.row.spec}` }],
321
+ ...(o.evidence === undefined
322
+ ? {}
323
+ : { "relevant-evidence": [{ description: `evidence of SHA-256 ${o.evidence}`, props: [prop("sha256", o.evidence)] }] }),
324
+ collected: NO_CLOCK,
325
+ };
326
+ }),
327
+ );
328
+ const findings = await Promise.all(
329
+ rows.map(async (row) => {
330
+ const own = observed.flatMap((o, i) => (o.row === row ? [{ o, uuid: observations[i]?.uuid ?? "" }] : []));
331
+ const outcome = own.some((x) => x.o.outcome === "gap") ? "gap" : own.some((x) => x.o.outcome === "accepted") ? "accepted" : "pass";
332
+ return {
333
+ uuid: await id("finding", input.label, row.controlId),
334
+ title: row.controlId,
335
+ description: `${row.controlId}: ${outcome}, by ${row.requirement}.`,
336
+ props: [prop("outcome", outcome), prop("control", row.requirement)],
337
+ target: { type: "objective-id", "target-id": row.controlId, status: { state: outcome === "gap" ? "not-satisfied" : "satisfied" } },
338
+ "related-observations": own.map((x) => ({ "observation-uuid": x.uuid })),
339
+ };
340
+ }),
341
+ );
342
+ const plan = await id("assessment-plan", input.label);
343
+ const assessmentResults = {
344
+ "assessment-results": {
345
+ uuid: await id("assessment-results", input.label),
346
+ metadata: metadata("assessment results"),
347
+ "import-ap": { href: `#${plan}` },
348
+ results: [
349
+ {
350
+ uuid: await id("result", input.label),
351
+ title: `Mizan register of ${input.label} as of ${NO_CLOCK}`,
352
+ description: `The findings of Mizan register of ${input.label}, assessed at ${NO_CLOCK}.`,
353
+ start: NO_CLOCK,
354
+ "local-definitions": { "inventory-items": inventory },
355
+ "reviewed-controls": { "control-selections": [{ "include-controls": rows.map((r) => ({ "control-id": r.controlId })) }] },
356
+ observations,
357
+ findings,
358
+ },
359
+ ],
360
+ "back-matter": { resources: [{ uuid: plan, title: `The assessment plan of Mizan register of ${input.label}` }] },
361
+ },
339
362
  };
340
- const results: OscalAssessmentResults = await assessmentResults(assessment, options("assessment results"));
341
- return { componentDefinition: renderOscal(withMechanism), assessmentResults: renderOscal(results) };
363
+ return { componentDefinition: `${JSON.stringify(componentDefinition, null, 2)}\n`, assessmentResults: `${JSON.stringify(assessmentResults, null, 2)}\n` };
342
364
  }
343
365
 
344
366
  /** What the register may be told besides its folder (0003-mizan FR-043): where its `enforcement.tsv` is, where it is not `enforcement.tsv` of the folder. */
@@ -187,6 +187,22 @@ export const LIBRARY_CI: Readonly<Record<string, LibraryCi>> = {
187
187
  nodeTests: 'node --test "suite/**/*.test.ts"',
188
188
  systems: ["windows-latest", "macos-latest", "ubuntu-latest"],
189
189
  },
190
+ headless: {
191
+ comment: lines(
192
+ "Headless, the contract of a program with no window in layers (governance, logical, the command-line surface), a library lifted out of `commons/ts` (commons 0032-lifting-libraries): its own `verify` (the compiler, the specification checker, the layers and trace checks, its tests and the",
193
+ "packing of its package with the inspection of its declarations) on Bun and its tests on Node 26, on Windows, macOS and Linux, because the package runs on all three.",
194
+ ).trimEnd(),
195
+ nodeTests: 'node --test "suite/**/*.test.ts"',
196
+ systems: ["windows-latest", "macos-latest", "ubuntu-latest"],
197
+ },
198
+ kanon: {
199
+ comment: lines(
200
+ "Kanon, the pattern of a library built in three layers (commons 0033-kanon): its own `verify` (the compiler, the specification checker, the trace check, its tests and the",
201
+ "packing of its package with the inspection of its declarations) on Bun and its tests on Node 26, on Windows, macOS and Linux, because the package runs on all three.",
202
+ ).trimEnd(),
203
+ nodeTests: 'node --test "suite/**/*.test.ts"',
204
+ systems: ["windows-latest", "macos-latest", "ubuntu-latest"],
205
+ },
190
206
  telemetry: {
191
207
  comment: lines(
192
208
  "Telemetry, OpenTelemetry-native signals as one typed library, a library lifted out of `commons/ts` (commons 0032-lifting-libraries): its own `verify` (the compiler, the specification checker, the trace, its tests and the",