@intentius/chant 0.100.0 → 0.102.0

package/dist/workspace/write-scope.d.ts

@@ -0,0 +1,259 @@
+/**
+ * Write scope per member and record kind, for each principal class, and the
+ * agent sessions bound to one member (#2524 D5, D20; #2548; ws-067).
+ *
+ * The declaration's `writeScope` block gives a restricted class the members
+ * whose files it may write and the record kinds it may write, with which
+ * verbs (`new`, `amend`, `review`, `close`). A class with no entry is not
+ * restricted. The declaration's `agents` list names agent sessions, each
+ * bound to one member: a session writes that member's files, and the records
+ * of kinds that member or the workspace declares, as `writeScope.agent`
+ * allows. An agent's members can't be widened.
+ *
+ * Two places apply it, both reading the scope from the base revision so a
+ * change can't widen its own scope (#2524 threat model):
+ *
+ * - The write paths: `chant workspace records new|amend|review|close` and the
+ *   MCP record tools refuse a write outside the writer's scope with
+ *   `write-scope-member` or `write-scope-kind`, and an unknown session with
+ *   `agent-unknown`. The session comes from `CHANT_AGENT`.
+ * - The enforcement boundary: `chant workspace check --changes <range>`
+ *   judges every commit in the range, by its `Chant-Agent` trailer, its
+ *   attested principal, or its author, and reports each path written outside
+ *   that writer's scope. Run in CI with an attestation policy, the principal
+ *   is the signer the policy at base trusts; on a developer machine it is
+ *   detection only (ws-002).
+ *
+ * A principal's class comes from the role grants in the trust policy at base,
+ * through {@link principalClass} alone (the agent, runner and service roles,
+ * then the role each domain class a pinned package supplies names, #3080),
+ * or from naming an agent session. Claiming a session only ever narrows what
+ * a writer may do, so an unverified `CHANT_AGENT` or trailer is safe to honour.
+ *
+ * A writeScope key no pinned package supplies fails closed: a writer judged
+ * `human` might be in that class, so it is refused with
+ * `write-scope-class-unknown` until the plugin is installed at the pinned
+ * version or the entry is removed.
+ */
+import { type AgentDeclaration, type ClassScope, type Declaration, type PrincipalClass, type ProtectedPath, type WriteVerb } from "./declaration.js";
+import { classesOf, roleGrants, type ClassRegistry } from "./principal-classes.js";
+import { type TrustPolicy } from "./trust/policy.js";
+import { AGENT_TRAILER } from "./trailers.js";
+/** The environment variable naming the agent session a write is made in. */
+export declare const AGENT_ENV = "CHANT_AGENT";
+/** The commit trailer naming the agent session a commit was made in, one of chant's trailers (`trailers.ts`). */
+export { AGENT_TRAILER };
+/** Why a write is outside its writer's scope. Closed. */
+export declare const WRITE_SCOPE_CODES: readonly ["write-scope-member", "write-scope-kind", "write-scope-class-unknown", "agent-unknown"];
+export type WriteScopeCode = (typeof WRITE_SCOPE_CODES)[number];
+/**
+ * What `check --changes` reports a path with: the record-write codes, and a
+ * write to a protected path (#3146), which a record write never is. Closed.
+ */
+export declare const SCOPE_FINDING_CODES: readonly ["write-scope-member", "write-scope-kind", "write-scope-class-unknown", "agent-unknown", "write-scope-protected"];
+export type ScopeFindingCode = (typeof SCOPE_FINDING_CODES)[number];
+export { classesOf, roleGrants };
+/**
+ * The class a principal is in: the first of agent, runner and service whose
+ * role it holds at base, then the first domain class in `classes` whose role
+ * it holds (#3080), or human.
+ */
+export declare function principalClass(policy: TrustPolicy, principal: string | null, classes?: ClassRegistry): PrincipalClass;
+/** Who is writing, as the scope judges it. */
+export interface Writer {
+    /** The principal named, or null when none is. */
+    principal: string | null;
+    class: PrincipalClass;
+    /** The agent session the writer is bound to, or null. */
+    agent: AgentDeclaration | null;
+}
+export declare class WriteScopeError extends Error {
+    readonly code: WriteScopeCode;
+    constructor(code: WriteScopeCode, message: string);
+}
+/**
+ * The writer: in the session `agent` names (refused with agent-unknown when
+ * the declaration declares none by that name), in the session that lists
+ * `principal`, or else in the class `principal`'s roles give it.
+ */
+export declare function resolveWriter(declaration: Declaration | null, policy: TrustPolicy, given: {
+    agent?: string | null;
+    principal?: string | null;
+}, classes?: ClassRegistry): Writer;
+/**
+ * Refuse `writer` when the declaration's writeScope names a class `classes`
+ * doesn't know and the writer is judged human (#3080): nothing says which
+ * role puts a principal in the unknown class, so this writer may be in it.
+ * A writer in another class is judged by that class, which comes first.
+ */
+export declare function unknownClassVerdict(declaration: Declaration | null, writer: Writer, classes: ClassRegistry): {
+    ok: true;
+} | {
+    ok: false;
+    code: "write-scope-class-unknown";
+    message: string;
+};
+/** The scope that applies to `writer`, or null when its class is not restricted. An agent is always restricted to its member. */
+export declare function scopeOf(declaration: Declaration | null, writer: Writer): ClassScope | null;
+export type ScopeVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    code: Exclude<ScopeFindingCode, "agent-unknown">;
+    message: string;
+};
+/** A record write's verdict: never write-scope-protected, since protected paths judge files that aren't records. */
+export type RecordVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    code: Exclude<WriteScopeCode, "agent-unknown">;
+    message: string;
+};
+/** The record kind a write goes to, as the scope reads it. */
+export interface ScopedKind {
+    /** The kind file's `recordKind.name`. */
+    name: string;
+    /** The name the declaration gives it, or null. */
+    declaredName: string | null;
+    /** The member that declares the kind, or null for the workspace's own kinds. */
+    member: string | null;
+    /** True when the declaration names the kind; an undeclared kind belongs to the member holding its records. */
+    declared: boolean;
+}
+/** Whether `writer` may write a record of `kind` with `verb`. A delete is never in a restricted scope. */
+export declare function judgeRecord(declaration: Declaration | null, writer: Writer, kind: ScopedKind, verb: WriteVerb | "delete"): RecordVerdict;
+/**
+ * The protected entry of `entries` that covers `path` (#3146, ws-077): one
+ * whose glob matches the path or a directory above it. Null when none does.
+ */
+export declare function protectedEntry(entries: readonly ProtectedPath[], path: string): ProtectedPath | null;
+/**
+ * Whether JSON text `before` and `after` differ only in the top-level keys
+ * `except` names. False when either is missing or isn't a JSON object.
+ */
+export declare function onlyKeysChanged(before: string | null, after: string | null, except: readonly string[]): boolean;
+/** A file's text before and after a write, read only when a protected entry with `except` needs it. */
+export interface PathChange {
+    before(): string | null;
+    after(): string | null;
+}
+/**
+ * Whether `writer` may write the file at `path`, from the workspace root:
+ * the path is in a member the writer may write, and no protected entry of
+ * its scope covers it, unless the entry's `except` allows the change (#3146).
+ * Without `change`, a write to a path an `except` entry covers is judged as a
+ * change outside the allowed keys.
+ */
+export declare function judgePath(declaration: Declaration | null, writer: Writer, path: string, change?: PathChange): ScopeVerdict;
+/** The declaration and policy a write on this machine is judged by. */
+export interface ScopeSource {
+    declaration: Declaration | null;
+    /** Where the declaration was read: the base revision, or the working tree when there is no base or no declaration at it. */
+    from: "base" | "working-tree" | null;
+    /** The workspace root on disk, or null without a declaration. */
+    rootOnDisk: string | null;
+    /** The workspace root from the git root, "." for the git root, or null without a declaration. */
+    root: string | null;
+    policy: TrustPolicy;
+    /** The principal classes: the core four and those the declaration's pins supply, path pins read where the declaration was (#3080). */
+    classes: ClassRegistry;
+}
+/**
+ * The scope for a write from `cwd`: the declaration and the trust policy at
+ * the base revision (`origin/HEAD`, `main` or `master`), so a write can't
+ * widen its own scope by editing its copy of the declaration. Without a base,
+ * or without a declaration at it, the working tree's declaration.
+ */
+export declare function scopeSource(cwd: string): ScopeSource;
+/**
+ * The kind a write goes to, as {@link judgeRecord} reads it: the declared
+ * entry whose file is `kindFile`, or, for a kind the declaration does not
+ * name, the member holding `recordsDir`.
+ */
+export declare function scopedKind(source: ScopeSource, kindName: string, kindFile: string, recordsDir: string): ScopedKind;
+/**
+ * Refuse a record write outside the writer's scope (#2548): throws a
+ * {@link WriteScopeError}. `agent` is the session the write names
+ * (`CHANT_AGENT`), and `principal` who the write names as its author.
+ * Returns what it read at base, for the identity rule (#3163).
+ */
+export declare function refuseRecordWrite(cwd: string, write: {
+    kindName: string;
+    kindFile: string;
+    recordsDir: string;
+    verb: WriteVerb;
+    agent?: string | null;
+    principal?: string | null;
+}): ScopeSource;
+/** A commit as the scope check judged it. */
+export interface ScopeCommit {
+    commit: string;
+    subject: string;
+    /** The attested principal, or the author's email when the commit is not attested. */
+    principal: string;
+    /** Whether the principal is a signer the policy at base attests, or only the author the commit claims. */
+    attested: boolean;
+    class: PrincipalClass;
+    /** The agent session, from the Chant-Agent trailer or the principal, or null. */
+    agent: string | null;
+    /** Paths in the workspace the commit writes. */
+    paths: number;
+}
+export interface ScopeFinding {
+    /** `finding:<code>:<commit>:<path>`, or `finding:<code>:<commit>` for agent-unknown and write-scope-class-unknown, which judge the whole commit. */
+    id: string;
+    code: ScopeFindingCode;
+    commit: string;
+    /** From the workspace root, or null for a finding on the whole commit. */
+    path: string | null;
+    principal: string;
+    class: PrincipalClass;
+    agent: string | null;
+    /** For a record file: how it was written, as the records commands name it, or delete. */
+    verb: WriteVerb | "delete" | null;
+    message: string;
+}
+export interface ScopeReport {
+    /** The commit the declaration and the trust policy were read at. */
+    base: string;
+    /** The classes with a writeScope entry, and agent when any session is declared: core first, then domain classes in pin order, then any no pinned package supplies. */
+    restricted: PrincipalClass[];
+    agents: string[];
+    commits: ScopeCommit[];
+    findings: ScopeFinding[];
+}
+/** A record kind the check knows, to tell a record file from another path. */
+export interface CheckKind {
+    scoped: ScopedKind;
+    /** The records directory, from the repository root. */
+    dir: string;
+    match: RegExp;
+    /** The reviews field, when the kind has one; the verdicts field of a session kind. */
+    reviewFields: string[];
+    /** The state field and closed states of a session kind, for telling a close. */
+    session: {
+        stateField: string;
+        closed: string[];
+        fills: string[];
+    } | null;
+    format: string;
+}
+/**
+ * Judge every commit in `base..head` against the write scope the declaration
+ * at `base` gives (#2548). Returns null when that declaration restricts no
+ * one: no writeScope block and no agent session. Merges are skipped; the
+ * commits they bring are judged instead.
+ */
+export declare function checkWriteScope(q: {
+    top: string;
+    base: string;
+    head: string;
+    /** The workspace root from the repository root, "" for the top. */
+    prefix: string;
+    declaration: Declaration;
+    kinds: CheckKind[];
+    /** The principal classes the declaration's pins supply at base (#3080). Without it, the core four. */
+    classes?: ClassRegistry;
+}): Promise<ScopeReport | null>;
+//# sourceMappingURL=write-scope.d.ts.map

package/dist/workspace/write-scope.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-scope.d.ts","sourceRoot":"","sources":["../../src/workspace/write-scope.ts"],"names":[],"mappings":"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"}

package/dist/yaml.d.ts

@@ -1,24 +1,23 @@
 /**
- * Lightweight YAML emitter and parser.
+ * YAML emitter and parser.
  *
- * Covers the subset of YAML used by Chant lexicons (scalars, block arrays,
- * nested objects, block scalars, tagged values, anchors, aliases and merge
- * keys). Not a full YAML implementation: flow collections are read only when
- * they are JSON. `splitYAMLDocuments` splits a multi-document stream. The
- * parser throws a `YAMLParseError` on a line it cannot place instead of
- * dropping it (#2991).
+ * The emitter writes the block-style YAML chant's serializers produce. The
+ * parser is js-yaml with chant's schema (#3006): YAML 1.2 core types,
+ * merge keys, `yes`/`no` booleans, and local tags such as `!reference` read
+ * as strings. `splitYAMLDocuments` splits a multi-document stream. Input the
+ * parser cannot read throws a `YAMLParseError` naming the line.
  */
 export declare function emitYAML(value: unknown, indent: number): string;
-/** Result of parsing a YAML block. */
-export interface ParseResult {
-    value: unknown;
-    endIndex: number;
-}
 /**
- * Input the parser cannot place (#2991). The parser used to skip such a line,
- * or read it as a key of whatever mapping was open at the top level, so a
- * mis-indented or unsupported construct came back as a quietly different
- * document. Now it is an error naming the line.
+ * `key: value` at column `indent * 2`, for a serializer that writes a
+ * document key by key. A block value follows the colon on the next line; an
+ * inline one (a scalar, `{}`, `[]`) needs a space after the colon, or
+ * `jobs:{}` is the plain scalar "jobs:{}" rather than a key (#3006).
+ */
+export declare function emitYAMLEntry(key: string, value: unknown, indent?: number): string;
+/**
+ * A document the parser cannot read. Its message and `line` name the line,
+ * so `chant import` can report "YAML line N: ..." instead of a stack trace.
  */
 export declare class YAMLParseError extends Error {
     /** 1-based line number within the text handed to the parser. */
@@ -28,17 +27,16 @@ export declare class YAMLParseError extends Error {
 /**
  * Parse a YAML document (or JSON document) into a plain object.
  *
- * Tries `JSON.parse` first; falls back to a line-based YAML parser that
- * handles the subset of YAML commonly found in CI configuration files. Throws
- * {@link YAMLParseError} on a line it cannot place rather than dropping it.
+ * Tries `JSON.parse` first, then js-yaml (#3006). A top-level sequence reads
+ * as `{}`, since callers rely on getting a mapping back; use
+ * {@link parseYAMLDocument} for the list. Throws {@link YAMLParseError} with
+ * the line number on input it cannot read.
  */
 export declare function parseYAML(content: string): Record<string, unknown>;
 /**
  * Parse one YAML (or JSON) document whose top level may be a sequence
- * (#2965). {@link parseYAML} reads only a top-level mapping and returns `{}`
- * for a file like `- a\n- b`; its callers rely on getting a mapping back, so
- * it keeps doing that. This returns the list instead, and otherwise defers to
- * `parseYAML`.
+ * (#2965). {@link parseYAML} returns `{}` for a file like `- a\n- b`; this
+ * returns the list.
  */
 export declare function parseYAMLDocument(content: string): unknown;
 /**
@@ -49,22 +47,6 @@ export declare function parseYAMLDocument(content: string): unknown;
  * normalized to `\n`.
  */
 export declare function splitYAMLDocuments(content: string): string[];
-/**
- * Parse indentation-based YAML lines into a key-value object: the mapping
- * whose keys sit at column `baseIndent`, starting at `startIndex`.
- *
- * It ends at the first line that is not one of its keys: a line at another
- * column, a sequence entry, or text that is not `key:`. That line goes back
- * to the caller in `endIndex`; if no caller owns it, `parseYAML` reports it
- * (#2991). This function never skips a content line.
- */
-export declare function parseYAMLLines(lines: string[], startIndex: number, baseIndent: number): ParseResult;
-/**
- * Parse a block array: the `- ` entries at column `baseIndent`, starting at
- * `startIndex`. Like {@link parseYAMLLines} it ends at the first line that is
- * not one of its entries and hands that line back in `endIndex`.
- */
-export declare function parseYAMLArray(lines: string[], startIndex: number, baseIndent: number): ParseResult;
 /**
  * Coerce a scalar string to a typed value.
  */

package/dist/yaml.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"yaml.d.ts","sourceRoot":"","sources":["../src/yaml.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AA0BH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAgH/D;AAMD,sCAAsC;AACtC,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,OAAO,CAAC;IACf,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED;;;;;GAKG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;gBAEV,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1C;AAmJD;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAalE;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAW1D;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAc5D;AAiFD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EAAE,EACf,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,WAAW,CAqBb;AA+MD;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,MAAM,EAAE,EACf,UAAU,EAAE,MAAM,EAClB,UAAU,EAAE,MAAM,GACjB,WAAW,CA4Db;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAwBlD"}
+{"version":3,"file":"yaml.d.ts","sourceRoot":"","sources":["../src/yaml.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA4BH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAsH/D;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,SAAI,GAAG,MAAM,CAG7E;AAMD;;;GAGG;AACH,qBAAa,cAAe,SAAQ,KAAK;IACvC,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB,YAAY,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAIxC;CACF;AAkID;;;;;;;GAOG;AACH,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQlE;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAO1D;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAc5D;AAED;;GAEG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAwBlD"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant",
-  "version": "0.100.0",
+  "version": "0.102.0",
   "description": "Declarative infrastructure-as-code toolkit — TypeScript on Node.js",
   "license": "Apache-2.0",
   "homepage": "https://intentius.io/chant",
@@ -97,7 +97,7 @@
     }
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json && find dist -type f \\( -name \"*.js\" -o -name \"*.js.map\" \\) -delete",
+    "build": "../../scripts/tsc7.sh -p tsconfig.build.json && tsc-alias -p tsconfig.build.json && find dist -type f \\( -name \"*.js\" -o -name \"*.js.map\" \\) -delete",
     "prepack": "npm run build"
   },
   "dependencies": {

package/src/audit/prior-art.ts

@@ -117,11 +117,26 @@ export const PRIOR_ART = {
   // docs site. The three `general/secrets` checks chant credits live only here:
   // trivy dropped them when it absorbed tfsec.
   "tfsec": { name: "tfsec", url: "https://github.com/aquasecurity/tfsec", license: "MIT", kind: "scanner" },
+  "trivy-checks": { name: "trivy-checks", url: "https://github.com/aquasecurity/trivy-checks", license: "MIT", kind: "scanner" },
   // Semgrep's engine is LGPL-2.1 but its rules are not: they ship under the
   // proprietary Semgrep Rules License v1.0, which forbids redistribution. So
   // this entry carries no SPDX id, and no semgrep rule text is ever copied into
   // this repository — a credit by name and link is the whole of it (#2107).
   "semgrep": { name: "Semgrep Registry rules", url: "https://github.com/semgrep/semgrep-rules", license: "Semgrep Rules License v1.0 (proprietary, not an SPDX id)", kind: "scanner" },
+  // Prometheus and Grafana observability family (#2916). promtool and amtool
+  // ship in the Prometheus and Alertmanager repositories and have no per-rule
+  // ids: credits to them name the check (`check rules`, `check-config`) in the
+  // lineage file's comments and omit `rule`.
+  "promtool": { name: "promtool check rules", url: "https://prometheus.io/docs/prometheus/latest/command-line/promtool/#promtool-check-rules", license: "Apache-2.0", kind: "vendor-validator" },
+  "amtool": { name: "amtool check-config", url: "https://github.com/prometheus/alertmanager/blob/main/cmd/amtool/check_config.go", license: "Apache-2.0", kind: "vendor-validator" },
+  "pint": { name: "pint (Cloudflare)", url: "https://github.com/cloudflare/pint", license: "Apache-2.0", kind: "scanner" },
+  "dashboard-linter": { name: "Grafana dashboard-linter", url: "https://github.com/grafana/dashboard-linter", license: "Apache-2.0", kind: "scanner" },
+  // Postgres schema and migration checks (#3285). squawk and strong_migrations
+  // are migration linters; their type rules overlap schema-level checks. The
+  // wiki page is documentation, not a tool.
+  "squawk": { name: "squawk", url: "https://github.com/sbdchd/squawk", license: "Apache-2.0", kind: "scanner" },
+  "strong_migrations": { name: "strong_migrations", url: "https://github.com/ankane/strong_migrations", license: "MIT", kind: "scanner" },
+  "postgres-wiki-dont-do-this": { name: "PostgreSQL wiki: Don't Do This", url: "https://wiki.postgresql.org/wiki/Don%27t_Do_This", license: "n/a", kind: "specification" },
 } as const satisfies Record<string, PriorArtEntry>;
 
 export type PriorArtTool = keyof typeof PRIOR_ART;

package/src/build.ts

@@ -1,6 +1,7 @@
 import type { Declarable } from "./declarable";
 import type { Serializer, SerializerResult } from "./serializer";
 import type { OwnershipMarker } from "./ownership";
+import type { TelemetryAttribution } from "./telemetry-attribution";
 import type { BuildError, DiscoveryErrorType } from "./errors";
 import type { IntrinsicDef, BuildRootContribution, BuildRootContributor } from "./lexicon";
 import { getProvenance, type BuildParamProvenance } from "./provenance";
@@ -194,6 +195,12 @@ export interface BuildOptions {
    */
   ownership?: OwnershipMarker;
 
+  /**
+   * Telemetry attribution facts (#2558), passed to each serializer's
+   * {@link SerializeContext}. Resolved by the build command; unset at level 0.
+   */
+  telemetry?: TelemetryAttribution;
+
   /**
    * The resolved project configuration, passed through to each serializer's
    * {@link SerializeContext} so a dialect can read its lexicon-scoped settings.
@@ -876,6 +883,7 @@ async function buildFromDiscoveryResult(
       const serialized = serializer.serialize(applyBound, lexiconLexiconOutputs, {
         ownership: options?.ownership,
         config: options?.config,
+        ...(options?.telemetry ? { telemetry: options.telemetry } : {}),
         ...(receipts.size > 0 ? { receipts } : {}),
       });
       // Collect any non-fatal serializer diagnostics into the build warnings.

package/src/cli/build-options.ts

@@ -64,6 +64,8 @@ export interface ProjectBuildOptionsInput {
   ownership?: OwnershipMarker;
   /** This build's resolved build-time parameters (#1064). */
   buildParams?: BuildParamProvenance[];
+  /** Telemetry attribution facts (#2558), from `resolveTelemetryAttribution`; unset at level 0. */
+  telemetry?: import("../telemetry-attribution").TelemetryAttribution;
 }
 
 /**
@@ -75,7 +77,7 @@ export interface ProjectBuildOptionsInput {
  * in this function, never at a call site.
  */
 export function resolveProjectBuildOptions(input: ProjectBuildOptionsInput): BuildOptions {
-  const { config, configDir, plugins, modes, ownership, buildParams } = input;
+  const { config, configDir, plugins, modes, ownership, buildParams, telemetry } = input;
 
   // #1039 — each loaded plugin's registered intrinsics (e.g. AWS's `Sub`), so
   // a file using a registered intrinsic tagged template folds instead of
@@ -90,6 +92,7 @@ export function resolveProjectBuildOptions(input: ProjectBuildOptionsInput): Bui
 
   return {
     ownership,
+    ...(telemetry ? { telemetry } : {}),
     config: config as unknown as Record<string, unknown>,
     fold: modes.fold,
     sandbox: modes.sandbox,

package/src/cli/commands/__fixtures__/init-lexicon-output/package.json

@@ -33,6 +33,6 @@
   "devDependencies": {
     "@intentius/chant": "*",
     "tsc-alias": "^1.8.17",
-    "typescript": "^5.9.3"
+    "typescript": "^5.9.3 || ^7.0.0"
   }
 }

package/src/cli/commands/build.ts

@@ -8,6 +8,7 @@ import {
   resolveKnowledgeDir,
 } from "../../config";
 import { resolveBuildModes, resolveProjectBuildOptions } from "../build-options";
+import { resolveTelemetryAttribution } from "../../telemetry-attribution";
 import { loadOkfBundle } from "../../okf-read";
 import { unknownEnvError } from "../../env";
 import type { OwnershipMarker } from "../../ownership";
@@ -320,6 +321,7 @@ export async function buildCommand(options: BuildOptions): Promise<BuildResult>
       modes,
       ownership,
       buildParams: paramsResolution.provenance,
+      telemetry: await resolveTelemetryAttribution(configDir, config as unknown as Record<string, unknown>, env),
     }),
   );
 

package/src/cli/commands/carve-emit-state.test.ts

@@ -3,6 +3,7 @@ import { mkdtempSync, writeFileSync, rmSync, readFileSync } from "fs";
 import { tmpdir } from "os";
 import { join } from "path";
 import { carveEmit, formatCarveEmit } from "./carve-emit";
+import { generateTsConfig, SCAFFOLD_DEV_DEPENDENCIES } from "./init";
 import { lintCommand } from "./lint";
 import { loadHcl2json } from "../../terraform/parse";
 import { readCarveManifest } from "../../terraform/manifest";
@@ -136,6 +137,9 @@ describe("carve emit --state (real adoption from tfstate)", () => {
       const pkg = JSON.parse(readFileSync(join(out, "package.json"), "utf-8"));
       expect(pkg.scripts.build).toBe("chant build src --lexicon aws");
       expect(Object.keys(pkg.dependencies)).toEqual(["@intentius/chant", "@intentius/chant-lexicon-aws"]);
+      // What `chant init` writes, which test/example-tsconfigs.e2e.test.ts compiles under TS 5.9 and 7 (#3233).
+      expect(pkg.devDependencies).toEqual(SCAFFOLD_DEV_DEPENDENCIES);
+      expect(JSON.parse(readFileSync(join(out, "tsconfig.json"), "utf-8"))).toEqual(JSON.parse(generateTsConfig()));
       expect(readFileSync(join(out, "chant.config.ts"), "utf-8")).toContain('lexicons: ["aws"]');
 
       // A second emit into the same dir leaves the scaffold (and edits) alone.

package/src/cli/commands/carve-emit.ts

@@ -22,7 +22,7 @@ import { resolveEmitProvider } from "../../terraform/carve-provider";
 import { readStateResource, type StateResource } from "../../terraform/state";
 import { writeCarveManifest, type CarveManifest } from "../../terraform/manifest";
 import { adoptFromState, type DeferredParam, type FoldedContribution } from "../../terraform/adopt-state";
-import { getChantVersion } from "./init";
+import { generateTsConfig, getChantVersion, SCAFFOLD_DEV_DEPENDENCIES } from "./init";
 import type { LexiconPlugin, ResourceSelector } from "../../lexicon";
 import type { ImportResult, LiveImportOptions } from "./import";
 
@@ -242,8 +242,8 @@ function deferredParams(report: CarveReport, attributes: Record<string, unknown>
 
 /**
  * Scaffold the emitted source into a buildable chant project: chant.config.ts,
- * package.json, tsconfig.json — same shape `chant init` produces, so
- * `npm install && npm run build` works in the output dir as-is. Existing files
+ * package.json, tsconfig.json, with the tsconfig and devDependencies `chant init`
+ * writes (#3233), so `npm install && npm run build` works in the output dir as-is. Existing files
  * are never overwritten (re-emits and user edits survive). Deferred inputs are
  * declared as `buildParams` (#998), defaults taken from the state's resolved
  * values, so the first build reproduces what is live while every survivor-fed
@@ -263,26 +263,12 @@ function scaffoldProject(outDir: string, lexicon: string, params: DeferredParam[
       "@intentius/chant": `^${ver}`,
       [`@intentius/chant-lexicon-${lexicon}`]: `^${ver}`,
     },
-    devDependencies: {
-      typescript: "^5.0.0",
-    },
-  };
-  const tsconfig = {
-    compilerOptions: {
-      target: "ES2022",
-      module: "NodeNext",
-      moduleResolution: "NodeNext",
-      strict: true,
-      esModuleInterop: true,
-      skipLibCheck: true,
-    },
-    include: ["src"],
-    exclude: ["node_modules"],
+    devDependencies: { ...SCAFFOLD_DEV_DEPENDENCIES },
   };
   const files: Array<[string, string]> = [
     ["package.json", JSON.stringify(packageJson, null, 2) + "\n"],
     ["chant.config.ts", renderConfig(lexicon, params)],
-    ["tsconfig.json", JSON.stringify(tsconfig, null, 2) + "\n"],
+    ["tsconfig.json", generateTsConfig() + "\n"],
   ];
 
   const written: string[] = [];

package/src/cli/commands/check-lexicon.test.ts

@@ -1,7 +1,9 @@
 import { describe, test, expect } from "vitest";
 import { join, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
-import { checkLexicon, coverageReportCheck } from "./check-lexicon";
+import { mkdtempSync, mkdirSync, writeFileSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { checkLexicon, countComposites, coverageReportCheck } from "./check-lexicon";
 import { loadLexiconFromDir } from "./check-lexicon-plugin";
 import type { LexiconPlugin } from "../../lexicon";
 
@@ -76,3 +78,62 @@ describe("coverageReportCheck", () => {
     expect(item.detail).toBe("all spec kinds accounted for");
   });
 });
+
+// chant #3104 — the composite rows counted every .ts file in src/composites/
+// but index.ts, so otel's one composite (NodeAgent) reported as four: the
+// catalog, its test and composites.test.ts counted too.
+describe("countComposites", () => {
+  const entry = (name: string) => ({ name, lexicon: "x", description: "", bundles: [], params: [] });
+
+  test("asks the plugin's composites() when it has one, not the files", () => {
+    const plugin = { composites: () => [entry("A"), entry("B")] } as unknown as LexiconPlugin;
+    expect(countComposites(plugin, "/nonexistent")).toEqual({
+      count: 2,
+      detail: "2 composite(s) in composites()",
+    });
+  });
+
+  test("counts zero, with the error, when composites() throws", () => {
+    const plugin = {
+      composites: () => {
+        throw new Error("catalog broken");
+      },
+    } as unknown as LexiconPlugin;
+    const result = countComposites(plugin, "/nonexistent");
+    expect(result.count).toBe(0);
+    expect(result.detail).toContain("catalog broken");
+  });
+
+  test("without composites(), counts files but not tests, the catalog, the barrel or helpers", () => {
+    const dir = mkdtempSync(join(tmpdir(), "check-lexicon-3104-"));
+    try {
+      mkdirSync(join(dir, "src/composites"), { recursive: true });
+      for (const f of [
+        "web-app.ts",
+        "worker.ts",
+        "index.ts",
+        "catalog.ts",
+        "catalog.test.ts",
+        "composites.test.ts",
+        "web-app.snapshot.test.ts",
+        "otel-helpers.ts",
+        "helpers.ts",
+        "shared.ts",
+      ]) {
+        writeFileSync(join(dir, "src/composites", f), "");
+      }
+      expect(countComposites({} as LexiconPlugin, dir).count).toBe(2);
+      expect(countComposites(undefined, dir).count).toBe(2);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("otel reports its one composite", async () => {
+    const loaded = await loadLexiconFromDir(join(repoRoot, "lexicons", "otel"));
+    expect(countComposites(loaded.plugin, join(repoRoot, "lexicons", "otel"))).toEqual({
+      count: 1,
+      detail: "1 composite(s) in composites()",
+    });
+  });
+});