@intentius/chant-lexicon-k3s 0.46.0 → 0.49.0

package/README.md

@@ -31,6 +31,6 @@ npx vitest run lexicons/k3s
 - `src/serializer.ts` — config.yaml / registries.yaml emitter
 - `src/spec/fetch.ts` — pinned upstream sources (the CLI flag definitions)
 - `src/codegen/parse.ts` — Go flag-definition parser
-- `src/lint/` — K3S001 pre-synth rule, K3S101–K3S105 post-synth checks
+- `src/lint/` — K3S001 pre-synth rule, K3S101–K3S107 post-synth checks
 - `src/lsp/` — completions and hover from the generated registry
 - `src/generated/` — generated artifacts (do not edit)

package/dist/describe-resources.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Live observation for declared k3s Server/Agent entities (#1603).
+ *
+ * Mirrors the #1412 k3d answer for the k3s shape, and reuses the same
+ * `k8s.profiles.<env>.context` binding helm and the k8s lexicon read
+ * (`@intentius/chant/kubectl-context`, #1488): the kubectl context is a
+ * property of the cluster chant talks to, not of any one lexicon, so k3s
+ * does not invent a second binding namespace for the same thing.
+ *
+ * ## What this can honestly say
+ *
+ * A declared `K3s::Server` / `K3s::Agent` is chant's description of one node
+ * joining a cluster. From where chant runs — never the host itself — the
+ * only observables are ones the apiserver answers:
+ *
+ *   - the declared kubectl context exists and answers at all (`kubectl
+ *     version`), which also reports the live k3s build so a caller can see
+ *     it against the pin (`K3S_VERSION`);
+ *   - the node the entity names is registered and its `Ready` condition.
+ *
+ * Everything that would require reaching the host directly — whether the
+ * `k3s` systemd unit is up, what `/etc/rancher/k3s/config.yaml` currently
+ * holds on disk — is out of scope. That is the provisioning boundary #1598
+ * draws, and this reader never crosses it.
+ *
+ * `K3s::Registries` has no live counterpart at all: `registries.yaml` is
+ * consumed once at containerd startup and leaves no object an apiserver
+ * serves, so it reads `unsupported-kind` — honest, not a gap to close here.
+ *
+ * ## Node identity
+ *
+ * The only address chant can back up is a declared `node-name`. Unset, k3s
+ * registers the node under the host's own hostname — which chant, running
+ * off the host, cannot know or guess. An entity with no `node-name` is
+ * `read-failed`, never a guessed address and never `absent`.
+ *
+ * ## Ownership rides node-label (#1603)
+ *
+ * The serializer stamps chant's marker into `node-label` when a build carries
+ * ownership (`./serializer.ts`), which lands on the registered Node as
+ * ordinary Kubernetes labels — the durable channel a host config file has no
+ * other way to carry. Read back here the same way every label-based lexicon
+ * does (`LABEL_OWNERSHIP_KEYS`).
+ *
+ * ## Tri-state (#1089, and the #1488 lesson)
+ *
+ * An unreachable apiserver — context missing, connection refused, no
+ * credentials — is `read-failed`/`no-credentials`/`no-binding` for every
+ * declared entity, naming the context that was actually read, never
+ * `absent`. Only a genuine per-node `NotFound` is absence.
+ */
+import type { DescribeResourcesResult } from "@intentius/chant/lexicon";
+import { type DeclaredEntity } from "@intentius/chant/observation";
+/** Injectable command runner, so tests drive every branch without kubectl or a cluster. */
+export type ExecFn = (command: string) => Promise<{
+    stdout: string;
+}>;
+/**
+ * The environment's kube context (#1488): the declared `k8s.profiles.<env>`
+ * binding when present, ambient otherwise. This is deliberately the SAME
+ * binding the k8s and helm lexicons read — a cluster is one target however
+ * many lexicons observe it — not a `k3s.profiles` of its own.
+ */
+export declare function resolveK3sContext(environment: string): Promise<string | undefined>;
+/** The declared node identity: the `node-name` flag, chant's only honest
+ * source. Absent means k3s will name the node after the host's own hostname
+ * — unknowable from here, so there is nothing to query by. */
+export declare function declaredNodeName(entity: DeclaredEntity): string | undefined;
+export interface DescribeResourcesOptions {
+    environment: string;
+    buildOutput: string;
+    entityNames: string[];
+    entities: Map<string, {
+        entityType: string;
+        props: Record<string, unknown>;
+    }>;
+    /** Restrict to chant-owned nodes (#1348). Withheld foreign nodes are
+     * `filtered`, never a silent drop into `absent`. */
+    owned?: boolean;
+}
+export declare function describeResources(options: DescribeResourcesOptions, execFn?: ExecFn): Promise<DescribeResourcesResult>;
+//# sourceMappingURL=describe-resources.d.ts.map

package/dist/describe-resources.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"describe-resources.d.ts","sourceRoot":"","sources":["../src/describe-resources.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkDG;AAIH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,0BAA0B,CAAC;AACxE,OAAO,EAEL,KAAK,cAAc,EAGpB,MAAM,8BAA8B,CAAC;AAOtC,2FAA2F;AAC3F,MAAM,MAAM,MAAM,GAAG,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IAAE,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC,CAAC;AAStE;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAOxF;AAED;;8DAE8D;AAC9D,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,cAAc,GAAG,MAAM,GAAG,SAAS,CAG3E;AAsHD,MAAM,WAAW,wBAAwB;IACvC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,QAAQ,EAAE,GAAG,CAAC,MAAM,EAAE;QAAE,UAAU,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC,CAAC;IAC9E;wDACoD;IACpD,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,wBAAwB,EACjC,MAAM,GAAE,MAAkB,GACzB,OAAO,CAAC,uBAAuB,CAAC,CA4BlC"}

package/dist/integrity.json

@@ -4,7 +4,7 @@
     "manifest.json": "5208bf3cb7308fcf74bcfae5cd70e1e4c73b0b567e71ac0f593246f1d72eaef2",
     "meta.json": "5988c37e9e93d52828d34fa043b0804fec7eb833153d387a9711333bcdff4bff",
     "types/index.d.ts": "98f3f3175d38aa2979c57577512c554eafed49b9125967c8617c137c01358e26",
-    "skills/chant-k3s.md": "05b322cae62541204bc737ae5e8aacdb689e0ebcc0b551844c907573ea62b945"
+    "skills/chant-k3s.md": "647bd3e1c6f75b1695150b895273edff6e25fe5851ce85dd3a213280fb6a0e75"
   },
-  "composite": "ccdbd6b6b747df56c8d6c9db11cd2ee6ee5ddff042b9e8438a88a1f667a98db6"
+  "composite": "c5aa14712fce0c3baf881168a643b0af27bdd787ad431c959e07ada098c73bbd"
 }

package/dist/lint/audit-catalog.d.ts

@@ -4,7 +4,7 @@
  * post-synth check has an entry, or the check contributes nothing to
  * `chant audit`, silently.
  *
- * All five checks read the chant model (`ctx.entities`) rather than the
+ * All checks read the chant model (`ctx.entities`) rather than the
  * emitted YAML — an emitted config.yaml carries no marker naming its own
  * role — so every entry is constructed directly with `yamlBased: false`.
  */

package/dist/lint/audit-catalog.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"audit-catalog.d.ts","sourceRoot":"","sources":["../../src/lint/audit-catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAW/D,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CA+BpD,CAAC"}
+{"version":3,"file":"audit-catalog.d.ts","sourceRoot":"","sources":["../../src/lint/audit-catalog.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gCAAgC,CAAC;AAW/D,eAAO,MAAM,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,QAAQ,CA2CpD,CAAC"}

package/dist/lint/post-synth/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lint/post-synth/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AAOvE,eAAO,MAAM,eAAe,EAAE,cAAc,EAM3C,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lint/post-synth/index.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kCAAkC,CAAC;AASvE,eAAO,MAAM,eAAe,EAAE,cAAc,EAQ3C,CAAC"}

package/dist/lint/post-synth/k3s106.d.ts

@@ -0,0 +1,14 @@
+/**
+ * K3S106: tls-san missing when the server is reachable at a declared
+ * address beyond the implicit default.
+ *
+ * The kube-apiserver certificate is only valid for the addresses baked
+ * into it. `bind-address` and `advertise-address` both say "clients reach
+ * this server somewhere other than its bare node-ip" — a fixed bind
+ * address, or a front-door address for an HA load balancer / VIP. Either
+ * one without a matching `tls-san` entry means the first connection
+ * through that address hits a certificate mismatch.
+ */
+import type { PostSynthCheck } from "@intentius/chant/lint/post-synth";
+export declare const k3s106: PostSynthCheck;
+//# sourceMappingURL=k3s106.d.ts.map

package/dist/lint/post-synth/k3s106.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"k3s106.d.ts","sourceRoot":"","sources":["../../../src/lint/post-synth/k3s106.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EACV,cAAc,EAGf,MAAM,kCAAkC,CAAC;AAO1C,eAAO,MAAM,MAAM,EAAE,cAiCpB,CAAC"}

package/dist/lint/post-synth/k3s107.d.ts

@@ -0,0 +1,13 @@
+/**
+ * K3S107: a packaged component is disabled but also configured.
+ *
+ * `disable` removes a packaged component entirely — the flags that
+ * configure it (`cluster-dns` for coredns, `servicelb-namespace` for
+ * servicelb, `default-local-storage-path` for local-storage) then land in
+ * config.yaml for a component that never starts. Dead config, and a
+ * signal the `disable` and the config drifted out of sync rather than
+ * being written together.
+ */
+import type { PostSynthCheck } from "@intentius/chant/lint/post-synth";
+export declare const k3s107: PostSynthCheck;
+//# sourceMappingURL=k3s107.d.ts.map

package/dist/lint/post-synth/k3s107.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"k3s107.d.ts","sourceRoot":"","sources":["../../../src/lint/post-synth/k3s107.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EACV,cAAc,EAGf,MAAM,kCAAkC,CAAC;AAgB1C,eAAO,MAAM,MAAM,EAAE,cAkCpB,CAAC"}

package/dist/op/activities/index.d.ts

@@ -0,0 +1,22 @@
+/**
+ * k3s Op activities — resolved by the core activity registry when a project's
+ * `chant.config.ts` lists the `k3s` lexicon. Lifecycle activities for the
+ * reachable-host case (chant#1601, epic #1598):
+ *   - k3sInstall — run the pinned installer (`INSTALL_K3S_VERSION`), idempotent
+ *     on an already-installed matching version.
+ *   - k3sUninstall — the uninstall script, gated the way k3dDown is.
+ *
+ * Bounded exactly as k3dUp/k3dDown were (chant#1410): no SSH orchestration,
+ * no host provisioning. The join token never travels through these activities
+ * as a value — only `tokenFile`, a path — see the token-boundary note on
+ * {@link k3sInstall} in ./k3s.
+ *
+ * The step builders (k3sInstall, k3sUninstall) live in core, re-exported from
+ * the temporal Op-authoring barrel like k3dUp/k3dDown. The activities here are
+ * dependency-light — they shell out to the k3s installer/uninstall scripts and
+ * only pull in the lexicon's version pin, not its declarable surface — so a
+ * Temporal worker loads them cheaply.
+ */
+export { k3sInstall, k3sUninstall, k3sInstallCommand, k3sInstallEnv, k3sUninstallCommand, k3sUninstallScript, k3sVersionCommand, parseK3sVersion, } from "./k3s.js";
+export type { K3sRole, K3sInstallArgs, K3sUninstallArgs, K3sInstallResult } from "./k3s.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/op/activities/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/op/activities/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AACH,OAAO,EACL,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,aAAa,EACb,mBAAmB,EACnB,kBAAkB,EAClB,iBAAiB,EACjB,eAAe,GAChB,MAAM,OAAO,CAAC;AACf,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,OAAO,CAAC"}

package/dist/op/activities/k3s.d.ts

@@ -0,0 +1,98 @@
+/** `k3s server` runs the control plane; `k3s agent` joins one as a worker. */
+export type K3sRole = "server" | "agent";
+export interface K3sInstallArgs {
+    /** Which k3s subcommand the installer configures (`k3s server` / `k3s agent`). */
+    role: K3sRole;
+    /**
+     * Path to the chant-emitted `config.yaml` on the reachable host, passed as
+     * `--config` to the installed binary. chant does not write this file itself
+     * — a build/apply step upstream of this activity is responsible for getting
+     * it onto the host (host provisioning is out of scope, chant#1598).
+     */
+    configFile: string;
+    /**
+     * Installer version pin (`INSTALL_K3S_VERSION`). Default: the lexicon's
+     * {@link K3S_VERSION} pin — bump that constant, not this arg, to track a
+     * new upstream release across the whole lexicon.
+     */
+    version?: string;
+    /**
+     * Path to a file on the host holding the cluster join token, passed to the
+     * installer as `K3S_TOKEN_FILE`. This is the only token-shaped input this
+     * activity accepts — see the "token boundary" note below.
+     */
+    tokenFile?: string;
+}
+export interface K3sUninstallArgs {
+    /** Which uninstall script to run — k3s ships a separate one per role. */
+    role: K3sRole;
+}
+/** What {@link k3sInstall} resolved. */
+export interface K3sInstallResult {
+    /** The k3s version now installed (the target version, whether freshly installed or already present). */
+    version: string;
+    /** `false` when an already-installed matching version made the install a no-op. */
+    installed: boolean;
+}
+/**
+ * `k3s --version` output, first line: `k3s version v1.36.3+k3s1 (hash)`.
+ * Returns `undefined` when k3s is not installed or the output doesn't match.
+ */
+export declare function parseK3sVersion(stdout: string): string | undefined;
+/** Check-install-version command — errors (non-zero exit) when k3s is absent. */
+export declare function k3sVersionCommand(): string;
+/**
+ * Build the get.k3s.io installer command. The version pin and the join-token
+ * reference (if any) travel as environment variables via {@link k3sInstallEnv},
+ * not interpolated into this string — see the token-boundary note on
+ * {@link k3sInstall}.
+ */
+export declare function k3sInstallCommand(args: K3sInstallArgs): string;
+/**
+ * Environment for {@link k3sInstallCommand}: `INSTALL_K3S_VERSION` (the pin)
+ * and, only when a `tokenFile` path is given, `K3S_TOKEN_FILE`.
+ *
+ * ## The token boundary (#1601)
+ *
+ * This is the only token-shaped input the install activity accepts, and it
+ * is a path, not a secret — the join token itself never passes through
+ * activity args, never gets logged, and never lands in an emitted
+ * config.yaml (K3S001 rejects a literal `token`/`agent-token` at lint). A
+ * `K3S_TOKEN` (the literal, env-var form k3s itself supports for agents) is
+ * deliberately not modeled here: the reference form the lexicon carries
+ * end-to-end is a file path, matching `token-file`/`agent-token-file` on the
+ * declared config surface (chant#1365's provenance stance applied at this
+ * surface, not a new mechanism).
+ */
+export declare function k3sInstallEnv(args: K3sInstallArgs): Record<string, string>;
+/** Path k3s installs its uninstall script at — one per role. */
+export declare function k3sUninstallScript(role: K3sRole): string;
+/**
+ * Build the uninstall command. Gated the way `k3dDown` is (chant#1410): no
+ * pre-check activity, no SSH orchestration — just the native idempotent
+ * behavior. Unlike `k3d cluster delete` (idempotent on its own), the k3s
+ * uninstall script does not exist at all on a host where k3s was never
+ * installed, so the command guards on the script's presence itself rather
+ * than assume it errors safely.
+ */
+export declare function k3sUninstallCommand(args: K3sUninstallArgs): string;
+/**
+ * Run the pinned k3s installer against a reachable host. Idempotent on an
+ * already-installed matching version: if `k3s --version` already reports the
+ * target version, the install is skipped. Uses longInfra profile — 20m
+ * timeout, heartbeat every 15s (the installer downloads and starts the
+ * k3s binary).
+ *
+ * Bounded exactly as `k3dUp`/`k3dDown` were (chant#1410, epic #1598): this
+ * drives the case where the host is reachable from where the Op runs. It
+ * does not provision the host, and it is not an SSH orchestrator.
+ */
+export declare function k3sInstall(args: K3sInstallArgs, signal?: AbortSignal): Promise<K3sInstallResult>;
+/**
+ * Uninstall k3s from a reachable host. Uses fastIdempotent profile — 5m
+ * timeout. A host where k3s was never installed (no uninstall script present)
+ * is a no-op success, the same idempotent shape as `k3dDown` against an
+ * already-gone cluster.
+ */
+export declare function k3sUninstall(args: K3sUninstallArgs, signal?: AbortSignal): Promise<void>;
+//# sourceMappingURL=k3s.d.ts.map

package/dist/op/activities/k3s.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"k3s.d.ts","sourceRoot":"","sources":["../../../src/op/activities/k3s.ts"],"names":[],"mappings":"AAOA,8EAA8E;AAC9E,MAAM,MAAM,OAAO,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEzC,MAAM,WAAW,cAAc;IAC7B,kFAAkF;IAClF,IAAI,EAAE,OAAO,CAAC;IACd;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,IAAI,EAAE,OAAO,CAAC;CACf;AAED,wCAAwC;AACxC,MAAM,WAAW,gBAAgB;IAC/B,wGAAwG;IACxG,OAAO,EAAE,MAAM,CAAC;IAChB,mFAAmF;IACnF,SAAS,EAAE,OAAO,CAAC;CACpB;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAElE;AAED,iFAAiF;AACjF,wBAAgB,iBAAiB,IAAI,MAAM,CAE1C;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAE9D;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,cAAc,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAI1E;AAED,gEAAgE;AAChE,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAExD;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAGlE;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,UAAU,CAC9B,IAAI,EAAE,cAAc,EACpB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,gBAAgB,CAAC,CAiC3B;AAED;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,IAAI,EAAE,gBAAgB,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CAI9F"}

package/dist/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAiC,MAAM,0BAA0B,CAAC;AAe7F;;;;GAIG;AACH,eAAO,MAAM,SAAS,EAAE,aA4GvB,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAiC,MAAM,0BAA0B,CAAC;AAgB7F;;;;GAIG;AACH,eAAO,MAAM,SAAS,EAAE,aA4HvB,CAAC"}

package/dist/skills/chant-k3s.md

@@ -70,6 +70,49 @@ export const registries = new Registries({
 Literal `auth.password` / `auth.token` fail K3S102; `insecure_skip_verify`
 warns via K3S105 — pin the CA instead.
 
+## Op lifecycle (reachable-host case)
+
+`k3sInstall` / `k3sUninstall` (chant#1601) drive a k3s installer against a
+host the Op runs on or can reach directly — the same boundary `k3dUp`/
+`k3dDown` draw (chant#1410): no host provisioning, no SSH orchestration.
+Requires `"k3s"` in the project's `chant.config.ts` `lexicons`.
+
+```typescript
+import { Op, phase, k3sInstall, k3sUninstall } from "@intentius/chant-lexicon-temporal";
+
+export default Op({
+  name: "k3s-controlplane",
+  phases: [
+    phase("Install", [
+      k3sInstall("server", { configFile: "/etc/rancher/k3s/config.yaml" }),
+    ]),
+  ],
+});
+```
+
+`k3sInstall` runs the pinned `get.k3s.io` installer (`INSTALL_K3S_VERSION`
+from the lexicon's pin, or an explicit `version` override) with `--config`
+pointing at a config.yaml already on the host — a build/apply step upstream
+puts it there. It is idempotent on an already-installed matching version:
+`k3s --version` is checked first, and a match skips the install entirely.
+`k3sUninstall` runs the matching uninstall script; a host where k3s was
+never installed is a no-op success.
+
+**The token boundary carries through to the Op surface.** There is no
+`token` option on `k3sInstall` — only `tokenFile`, a path passed to the
+installer as `K3S_TOKEN_FILE`. The join secret's value never appears in
+Op-authored TypeScript (which is committed source, same as a config.yaml
+declaration), is never logged, and is never interpolated into the installer
+command string — it travels only as an environment variable set on the
+child process at install time.
+
+```typescript
+k3sInstall("agent", {
+  configFile: "/etc/rancher/k3s/config.yaml",
+  tokenFile: "/etc/rancher/k3s/agent-token", // a path, not the secret
+});
+```
+
 ## Output shape
 
 One file per declared entity. The first Server/Agent config is the primary
@@ -88,3 +131,5 @@ with any kubectl.
 | K3S103 | error | an Agent with no `server` to join |
 | K3S104 | warning | kubeconfig written wider than 0644 |
 | K3S105 | warning | registry TLS verification disabled |
+| K3S106 | warning | tls-san missing for a declared bind/advertise address |
+| K3S107 | warning | disable names a component the config also configures |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-k3s",
-  "version": "0.46.0",
+  "version": "0.49.0",
   "type": "module",
   "files": [
     "src/",
@@ -17,6 +17,11 @@
       "types": "./dist/*.d.ts",
       "default": "./src/*.ts"
     },
+    "./op/activities": {
+      "development": "./src/op/activities/index.ts",
+      "types": "./dist/op/activities/index.d.ts",
+      "default": "./src/op/activities/index.ts"
+    },
     "./lint/post-synth": {
       "development": "./src/lint/post-synth/index.ts",
       "types": "./dist/lint/post-synth/index.d.ts",
@@ -38,14 +43,14 @@
     "@intentius/chant": "*",
     "tsc-alias": "^1.8.17",
     "typescript": "^5.9.3",
-    "js-yaml": "^4.1.0",
+    "js-yaml": "^4.3.1",
     "@types/js-yaml": "^4.0.9"
   },
   "publishConfig": {
     "access": "public"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.46.0",
+    "@intentius/chant": "^0.49.0",
     "typescript": "^5.9.3"
   },
   "description": "k3s lexicon for chant — the k3s distro's host configuration as declarable data",

package/src/describe-resources.test.ts

@@ -0,0 +1,209 @@
+import { describe, expect, it } from "vitest";
+import { describeObservationConformance } from "@intentius/chant-test-utils";
+import { normalizeObservation } from "@intentius/chant/observation";
+import {
+  describeResources,
+  declaredNodeName,
+  type ExecFn,
+} from "./describe-resources";
+import { k3sPlugin } from "./plugin";
+import { SERVER_TYPE, AGENT_TYPE, REGISTRIES_TYPE } from "./serializer";
+import { K3S_VERSION } from "./spec/fetch";
+
+const VERSION_CMD = "kubectl version -o json";
+
+function fakeExec(handlers: Record<string, string | Error>): ExecFn {
+  return async (command: string) => {
+    for (const [prefix, result] of Object.entries(handlers)) {
+      if (command.startsWith(prefix)) {
+        if (result instanceof Error) throw result;
+        return { stdout: result };
+      }
+    }
+    throw new Error(`unexpected command: ${command}`);
+  };
+}
+
+const VERSION_OK = JSON.stringify({ serverVersion: { gitVersion: K3S_VERSION } });
+const VERSION_OLD = JSON.stringify({ serverVersion: { gitVersion: "v1.30.0+k3s1" } });
+
+function readyNode(labels: Record<string, string> = {}) {
+  return JSON.stringify({
+    metadata: { uid: "node-uid-1", labels, creationTimestamp: "2026-01-01T00:00:00Z" },
+    status: {
+      nodeInfo: { kubeletVersion: K3S_VERSION },
+      conditions: [{ type: "Ready", status: "True" }],
+    },
+  });
+}
+
+const OWNED_LABELS = {
+  "app.kubernetes.io/managed-by": "chant",
+  "chant.intentius.io/stack": "probe",
+  "chant.intentius.io/env": "local",
+};
+
+function options(
+  entities: Array<[string, string, Record<string, unknown>]> = [["cp", SERVER_TYPE, { "node-name": "cp-1" }]],
+  extra: { owned?: boolean } = {},
+) {
+  return {
+    environment: "probe-env-unbound",
+    buildOutput: "",
+    entityNames: entities.map(([name]) => name),
+    entities: new Map(entities.map(([name, entityType, props]) => [name, { entityType, props }])),
+    ...extra,
+  };
+}
+
+describe("k3s describeResources", () => {
+  it("reports a Ready, chant-labelled server node as present and owned", async () => {
+    const result = await describeResources(
+      options(),
+      fakeExec({ [VERSION_CMD]: VERSION_OK, "kubectl get node": readyNode(OWNED_LABELS) }),
+    );
+    const { resources } = normalizeObservation(result);
+    expect(resources.cp.status).toBe("Ready");
+    expect(resources.cp.ownership).toBe("owned");
+    expect(resources.cp.physicalId).toBe("node-uid-1");
+    expect((resources.cp.attributes as Record<string, unknown>).versionMatchesPin).toBe(true);
+  });
+
+  it("reports a node without the marker as foreign", async () => {
+    const result = await describeResources(
+      options(),
+      fakeExec({ [VERSION_CMD]: VERSION_OK, "kubectl get node": readyNode() }),
+    );
+    const { resources } = normalizeObservation(result);
+    expect(resources.cp.ownership).toBe("foreign");
+  });
+
+  it("reports the live k3s build against the pin — a mismatch is informational, not a failure", async () => {
+    const result = await describeResources(
+      options(),
+      fakeExec({ [VERSION_CMD]: VERSION_OLD, "kubectl get node": readyNode(OWNED_LABELS) }),
+    );
+    const { resources } = normalizeObservation(result);
+    expect((resources.cp.attributes as Record<string, unknown>).k3sVersion).toBe("v1.30.0+k3s1");
+    expect((resources.cp.attributes as Record<string, unknown>).versionMatchesPin).toBe(false);
+  });
+
+  it("reports a NotReady node's reason as the status", async () => {
+    const notReady = JSON.stringify({
+      metadata: { uid: "node-uid-2", labels: OWNED_LABELS },
+      status: { conditions: [{ type: "Ready", status: "False", reason: "KubeletNotReady" }] },
+    });
+    const result = await describeResources(
+      options(),
+      fakeExec({ [VERSION_CMD]: VERSION_OK, "kubectl get node": notReady }),
+    );
+    const { resources } = normalizeObservation(result);
+    expect(resources.cp.status).toBe("KubeletNotReady");
+  });
+
+  it("reports a missing node as absent — in neither map", async () => {
+    const result = await describeResources(
+      options(),
+      fakeExec({
+        [VERSION_CMD]: VERSION_OK,
+        "kubectl get node": new Error(`Error from server (NotFound): nodes "cp-1" not found`),
+      }),
+    );
+    const { resources, unobserved } = normalizeObservation(result);
+    expect(resources.cp).toBeUndefined();
+    expect(unobserved.cp).toBeUndefined();
+  });
+
+  it("reports not-observed, naming the context, when the apiserver is unreachable — never absence", async () => {
+    const result = await describeResources(
+      options([
+        ["cp", SERVER_TYPE, { "node-name": "cp-1" }],
+        ["worker", AGENT_TYPE, { "node-name": "agent-1" }],
+      ]),
+      fakeExec({ [VERSION_CMD]: new Error("some unexpected apiserver fault") }),
+    );
+    const { resources, unobserved } = normalizeObservation(result);
+    expect(Object.keys(resources)).toHaveLength(0);
+    expect(unobserved.cp.reason).toBe("read-failed");
+    expect(unobserved.worker.reason).toBe("read-failed");
+    expect(unobserved.cp.detail).toContain("kubectl context");
+    expect(unobserved.cp.detail).toContain("apiserver fault");
+  });
+
+  it("reports read-failed for an entity with no declared node-name — never a guessed address", async () => {
+    const result = await describeResources(
+      options([["cp", SERVER_TYPE, {}]]),
+      fakeExec({ [VERSION_CMD]: VERSION_OK }),
+    );
+    const { resources, unobserved } = normalizeObservation(result);
+    expect(resources.cp).toBeUndefined();
+    expect(unobserved.cp.reason).toBe("read-failed");
+    expect(unobserved.cp.detail).toContain("node-name");
+  });
+
+  it("reports K3s::Registries as unsupported-kind — no live object exists to read", async () => {
+    const result = await describeResources(
+      options([["reg", REGISTRIES_TYPE, {}]]),
+      fakeExec({ [VERSION_CMD]: VERSION_OK }),
+    );
+    const { unobserved } = normalizeObservation(result);
+    expect(unobserved.reg.reason).toBe("unsupported-kind");
+  });
+
+  it("filters a foreign node out under --owned, without reporting it absent", async () => {
+    const result = await describeResources(
+      options(undefined, { owned: true }),
+      fakeExec({ [VERSION_CMD]: VERSION_OK, "kubectl get node": readyNode() }),
+    );
+    const { resources, unobserved } = normalizeObservation(result);
+    expect(resources.cp).toBeUndefined();
+    expect(unobserved.cp.reason).toBe("filtered");
+  });
+
+  it("keeps an owned node present under --owned", async () => {
+    const result = await describeResources(
+      options(undefined, { owned: true }),
+      fakeExec({ [VERSION_CMD]: VERSION_OK, "kubectl get node": readyNode(OWNED_LABELS) }),
+    );
+    const { resources } = normalizeObservation(result);
+    expect(resources.cp.ownership).toBe("owned");
+  });
+
+  it("resolves node identity from the declared node-name only — never a guess", () => {
+    expect(declaredNodeName({ name: "entity", type: SERVER_TYPE, props: { "node-name": "real" } })).toBe(
+      "real",
+    );
+    expect(declaredNodeName({ name: "entity", type: SERVER_TYPE, props: {} })).toBeUndefined();
+  });
+});
+
+describeObservationConformance({
+  lexicon: "k3s",
+  ownershipChannel: k3sPlugin.ownershipChannel,
+  scenarios: [
+    {
+      name: "Ready owned server node",
+      declared: ["cp"],
+      owned: true,
+      expectPresent: ["cp"],
+      run: () =>
+        describeResources(options(), fakeExec({ [VERSION_CMD]: VERSION_OK, "kubectl get node": readyNode(OWNED_LABELS) })),
+    },
+    {
+      name: "apiserver unreachable",
+      declared: ["cp"],
+      expectUnobserved: ["cp"],
+      run: () => describeResources(options(), fakeExec({ [VERSION_CMD]: new Error("connection refused") })),
+    },
+    {
+      name: "node absent",
+      declared: ["cp"],
+      expectAbsent: ["cp"],
+      run: () =>
+        describeResources(
+          options(),
+          fakeExec({ [VERSION_CMD]: VERSION_OK, "kubectl get node": new Error("NotFound") }),
+        ),
+    },
+  ],
+});