@intentius/chant 0.101.0 → 0.104.0

package/src/workspace/records.ts

@@ -381,9 +381,11 @@ export const recordKindSchema = z
      * A review-session kind (#2673, #2650 C10): the front-matter list of the
      * verdicts a session produced, the field that seals a closed session, and
      * the records its verdicts name, as the kind file that locates them
-     * (relative to this kind file's directory). The entries of that kind's
-     * reviews list (its `reviews.field`, or `reviews`) name a session in
-     * `session`. Optional.
+     * (relative to this kind file's directory), or as `kinds`, several kind
+     * files, when a session judges records of more than one kind, such as
+     * decisions and contracts (#3148, ws-082). The entries of each such
+     * kind's reviews list (its `reviews.field`, or `reviews`) name a session
+     * in `session`. Optional.
      *
      * `openedRev`, `closedRev` and `closedOn` (#2693) name the fields that
      * hold the commit a session opened at, the commit it closed at, and when
@@ -395,7 +397,13 @@ export const recordKindSchema = z
       .object({
         verdicts: z.string().min(1),
         seal: z.string().min(1),
-        subjects: z.object({ kind: z.string().min(1) }).strict(),
+        subjects: z.union([
+          z.object({ kind: z.string().min(1) }).strict(),
+          z
+            .object({ kinds: z.array(z.string().min(1)).min(1) })
+            .strict()
+            .refine((x) => new Set(x.kinds).size === x.kinds.length, { message: "session.subjects.kinds lists each kind file once", path: ["kinds"] }),
+        ]),
         openedRev: z.string().min(1).optional(),
         closedRev: z.string().min(1).optional(),
         closedOn: z.string().min(1).optional(),
@@ -419,6 +427,23 @@ export const recordKindSchema = z
      * done record with a criterion that no passing evidence meets is warned
      * `work-acceptance-unmet`, which `check` fails on (WSP117). Optional, and
      * a record without the list is read as before.
+     *
+     * #3147 adds four, each optional:
+     *
+     * - `contract`: the front-matter field naming the contract record the
+     *   item builds, and the kind file of those records (relative to this
+     *   kind file). Each record gets `contract` with that record's state,
+     *   warned `work-contract-unknown` or `work-contract-undecided`.
+     * - `tier`: the field holding the item's builder tier, and the tiers the
+     *   workspace allows, declared once here. A tier outside them is warned
+     *   `work-tier-unknown`.
+     * - `attempts`: the field holding an item's own attempt limit, and the
+     *   default `max` for items without one. `work history` counts attempts
+     *   against it.
+     * - `answers`: the answer kind file (relative to this kind file) whose
+     *   records answer decision points about an item. Each record gets
+     *   `answers`, the answers whose `constrains` names its id, joined by id
+     *   rather than copied onto the item.
      */
     work: z
       .object({
@@ -429,6 +454,19 @@ export const recordKindSchema = z
         done: z.string().min(1),
         closedOn: z.string().min(1),
         acceptance: z.object({ field: z.string().min(1), implementer: z.string().min(1) }).strict().optional(),
+        contract: z.object({ field: z.string().min(1), kind: z.string().min(1) }).strict().optional(),
+        tier: z
+          .object({
+            field: z.string().min(1),
+            tiers: z.array(z.string().min(1)).min(1),
+            // What each tier may hold, for the slice-tier point's fits_<tier> inputs (#3150, work-size.ts).
+            limits: z.record(z.string().min(1), z.object({ criteria: z.number().int().min(0).optional(), files: z.number().int().min(0).optional(), words: z.number().int().min(0).optional() }).strict()).optional(),
+          })
+          .strict()
+          .refine((t) => new Set(t.tiers).size === t.tiers.length, { message: "work.tier.tiers lists each tier once", path: ["tiers"] })
+          .optional(),
+        attempts: z.object({ field: z.string().min(1), max: z.number().int().min(1) }).strict().optional(),
+        answers: z.string().min(1).optional(),
       })
       .strict()
       .optional(),
@@ -536,6 +574,34 @@ export const ANSWER_STATES = ["escalated", "proposed", "answered"] as const;
 
 export type RecordKind = z.infer<typeof recordKindSchema>;
 
+/** The kind files a session kind's verdicts name records of, relative to the session kind file: `subjects.kind`, or each of `subjects.kinds` (ws-082). */
+export function sessionSubjectKinds(session: NonNullable<RecordKind["session"]>): string[] {
+  return "kinds" in session.subjects ? session.subjects.kinds : [session.subjects.kind];
+}
+
+/** The records of one of a session kind's subject kinds, and the name of their reviews list. */
+export interface SessionSubjects {
+  /** The subject kind file, as the session kind names it. */
+  kind: string;
+  records: RecordEntry[];
+  reviews: string;
+}
+
+/**
+ * A session kind's subject records, each subject kind read from `source`
+ * (#2673, ws-082), for {@link readRecords}' `subjects`. Undefined for a kind
+ * that is not a session kind.
+ */
+export async function readSessionSubjects(loaded: LoadedRecordKind, root: string, source: RecordSource): Promise<SessionSubjects[] | undefined> {
+  if (!loaded.kind.session) return undefined;
+  const out: SessionSubjects[] = [];
+  for (const file of sessionSubjectKinds(loaded.kind.session)) {
+    const subjectKind = await loadRecordKind(resolve(dirname(loaded.file), file), root);
+    out.push({ kind: file, records: (await readRecords(subjectKind, { root, source })).records, reviews: subjectKind.kind.reviews?.field ?? "reviews" });
+  }
+  return out;
+}
+
 /** A kind as loaded: its data, where it came from, and its schema. */
 export interface LoadedRecordKind {
   kind: RecordKind;
@@ -1148,6 +1214,8 @@ export interface RecordEntry {
   implements?: WorkLink[];
   /** For a work kind with acceptance criteria (#2772): how many of the record's criteria passing evidence meets, or null when it lists none. */
   acceptance?: WorkAcceptance | null;
+  /** For a work kind with a contract link (#3147): the contract record the item builds, with its state, or null when it names none. */
+  contract?: WorkLink | null;
 }
 
 export interface ReadRecordsOptions {
@@ -1168,11 +1236,11 @@ export interface ReadRecordsOptions {
    */
   history?: RecordHistory;
   /**
-   * For a session kind: the records its `session.subjects.kind` locates, read
-   * from the same tree (#2673). Without them no verdict is checked and no
-   * session is cited.
+   * For a session kind: the records each of its subject kinds locates, read
+   * from the same tree (#2673, ws-082). Without them no verdict is checked
+   * and no session is cited.
    */
-  subjects?: { records: RecordEntry[]; reviews: string };
+  subjects?: SessionSubjects[];
   /**
    * The workspace root, from `root` with / separators ("." for `root`
    * itself): where a content-addressed record's own path is reported from

package/src/workspace/reference-kinds/app/package.json

@@ -0,0 +1,10 @@
+{
+  "name": "chant-reference-app-kind",
+  "version": "1.0.0",
+  "private": true,
+  "description": "The app member kind (INTENTIUS/chant#3151): a data-only kinds file a workspace pins by path. chant reads it as data and never runs it.",
+  "files": ["workspace-kinds.json"],
+  "exports": {
+    "./workspace-kinds": "./workspace-kinds.json"
+  }
+}

package/src/workspace/reference-kinds/app/workspace-kinds.json

@@ -0,0 +1,45 @@
+{
+  "$comment": "The app member kind (#3151, ws-093). A workspace pins a copy of this directory by path, as the reference workspace does at kinds/app, and chant reads it as data. The fields are the conventions an orchestrator relies on to run, migrate, test and check an app: the scripts in its package.json, the environment variables it reads, and the path it answers health on. The canonical copy ships in @intentius/chant at src/workspace/reference-kinds/app.",
+  "schema": 1,
+  "kinds": [
+    {
+      "name": "app",
+      "description": "an app: a Node package with a start script in the package.json directly in its directory",
+      "precedence": 100,
+      "probe": {
+        "anyJsonKey": {
+          "in": ["package.json"],
+          "pointers": ["/scripts/start"]
+        }
+      },
+      "outputs": ["source", "url"],
+      "fields": {
+        "scripts": {
+          "type": "object",
+          "description": "Which package.json script plays each part, run with npm run from the member's directory",
+          "properties": {
+            "start": { "type": "string", "description": "Runs a release of the app; it listens on the port env.port names", "default": "start" },
+            "dev": { "type": "string", "description": "Runs the app in development", "default": "dev" },
+            "test": { "type": "string", "description": "The app's own tests, run before a release", "default": "test" },
+            "migrate": { "type": "string", "description": "Applies the app's migrations to the data directory env.data names; a missing script means there are none", "default": "migrate" }
+          }
+        },
+        "env": {
+          "type": "object",
+          "description": "The environment variables the app reads, by name",
+          "properties": {
+            "port": { "type": "string", "description": "The port the app listens on", "default": "PORT", "pattern": "^[A-Z_][A-Z0-9_]*$" },
+            "data": { "type": "string", "description": "The directory the app keeps its data in", "default": "APP_DATA", "pattern": "^[A-Z_][A-Z0-9_]*$" },
+            "revision": { "type": "string", "description": "The revision the running app reports, such as the release's commit", "default": "APP_REVISION", "pattern": "^[A-Z_][A-Z0-9_]*$" }
+          }
+        },
+        "health": {
+          "type": "string",
+          "description": "The path the running app answers on with a status below 500 once it is up",
+          "default": "/health",
+          "pattern": "^/"
+        }
+      }
+    }
+  ]
+}