@intentius/chant-lexicon-fountain 0.33.0

package/src/composites/composites.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+import { ConciergeStack } from "./concierge-stack";
+
+describe("ConciergeStack", () => {
+  it("defaults to deny-all egress, no vaults, and the ownership marker", () => {
+    const { environment, agent } = ConciergeStack({
+      name: "concierge",
+      model: "anthropic/claude-sonnet-4-6",
+    });
+
+    const env = (environment as unknown as { props: Record<string, unknown> }).props;
+    const a = (agent as unknown as { props: Record<string, unknown> }).props;
+    expect(env.networking_type).toBe("limited");
+    expect((env.networking_config as { allowed_hosts: string[] }).allowed_hosts).toEqual([]);
+    expect((env.metadata as Record<string, unknown>)["managed-by"]).toBe("chant");
+    expect(a.allowed_vault_ids).toEqual([]);
+    expect(a.environment).toBe(environment);
+    expect(a.runtime).toBe("claude");
+  });
+
+  it("loosening is explicit", () => {
+    const { environment, agent } = ConciergeStack({
+      name: "helper",
+      model: "anthropic/claude-sonnet-4-6",
+      allowedHosts: ["github.com"],
+      allowedVaultIds: ["vault-1"],
+      metadata: { team: "payments" },
+    });
+
+    const env = (environment as unknown as { props: Record<string, unknown> }).props;
+    expect((env.networking_config as { allowed_hosts: string[] }).allowed_hosts).toEqual(["github.com"]);
+    expect((agent as unknown as { props: Record<string, unknown> }).props.allowed_vault_ids).toEqual(["vault-1"]);
+    expect((env.metadata as Record<string, unknown>).team).toBe("payments");
+  });
+});

package/src/composites/concierge-stack.ts

@@ -0,0 +1,71 @@
+/**
+ * ConciergeStack — a locked-down Environment + Agent pair with the
+ * secure-by-construction defaults for agents that touch anything
+ * sensitive:
+ *
+ *   - `networking_type: limited` with an explicit allowlist (empty =
+ *     deny-all egress — fountain's isolation mode)
+ *   - `allowed_vault_ids: []` — no conversation may override the
+ *     reviewed environment at spawn
+ *   - the `managed-by: chant` marker on both, so owned-only
+ *     reconcile/prune and drift filtering see them
+ *
+ * Loosening any of it is a visible, reviewable act: pass an allowlist,
+ * pass vault ids, or drop to the raw classes.
+ */
+
+import { Environment, Agent } from "../generated/index";
+
+export interface ConciergeStackOpts {
+  /** Base name; the environment is `<name>-env`, the agent `<name>`. */
+  name: string;
+  /** Canonical provider/model_id. */
+  model: string;
+  /** Agent runtime. Default "claude". */
+  runtime?: "claude" | "codex" | "gemini" | "opencode";
+  /** Egress allowlist. Default [] — deny all egress. */
+  allowedHosts?: string[];
+  /** Vaults that may attach at conversation create. Default [] — none. */
+  allowedVaultIds?: string[];
+  /** Skill installs. Pin github-sourced entries with `ref`. */
+  skills?: Array<Record<string, unknown>>;
+  /** MCP server definitions (use ${VAR} references for secrets). */
+  mcpServers?: Record<string, unknown>;
+  /** System prompt. */
+  system?: string;
+  /** Extra environment fields (packages, env_vars, setup_script, repositories). */
+  environment?: Record<string, unknown>;
+  /** Extra metadata merged over the managed-by marker. */
+  metadata?: Record<string, unknown>;
+}
+
+export interface ConciergeStackResources {
+  environment: InstanceType<typeof Environment>;
+  agent: InstanceType<typeof Agent>;
+}
+
+export function ConciergeStack(opts: ConciergeStackOpts): ConciergeStackResources {
+  const metadata = { "managed-by": "chant", ...(opts.metadata ?? {}) };
+
+  const environment = new Environment({
+    name: `${opts.name}-env`,
+    networking_type: "limited",
+    networking_config: { allowed_hosts: opts.allowedHosts ?? [] },
+    metadata,
+    ...(opts.environment ?? {}),
+  });
+
+  const agent = new Agent({
+    name: opts.name,
+    model: opts.model,
+    runtime: opts.runtime ?? "claude",
+    environment,
+    allowed_vault_ids: opts.allowedVaultIds ?? [],
+    ...(opts.skills ? { skills: opts.skills } : {}),
+    ...(opts.mcpServers ? { mcp_servers: opts.mcpServers } : {}),
+    ...(opts.system !== undefined ? { system: opts.system } : {}),
+    metadata,
+  });
+
+  return { environment, agent };
+}

package/src/coverage.test.ts

@@ -0,0 +1,63 @@
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { computeFountainCoverage, formatVerbose, EXCLUDED_KINDS } from "./coverage";
+
+const srcDir = dirname(fileURLToPath(import.meta.url));
+const spec = readFileSync(join(srcDir, "spec", "fountain-openapi.snapshot.json"), "utf-8");
+const surface = JSON.parse(
+  readFileSync(join(srcDir, "..", "surface.snapshot.json"), "utf-8"),
+) as { entries: Record<string, { kind: string; props?: string[] }> };
+
+describe("fountain coverage", () => {
+  it("reports the committed surface as fully covering the spec", () => {
+    const report = computeFountainCoverage(spec, surface);
+
+    expect(report.overallPct).toBe(100);
+    expect(report.modeledKinds.sort()).toEqual(["Agent", "Environment", "Vault"]);
+    for (const kind of report.kinds) {
+      expect(kind.missing).toEqual([]);
+      expect(kind.stale).toEqual([]);
+    }
+  });
+
+  it("accounts for every request schema in the spec", () => {
+    // The guard that matters: a new upstream kind must be modeled or
+    // explicitly excluded, never silently absent.
+    const report = computeFountainCoverage(spec, surface);
+    expect(report.unaccountedKinds).toEqual([]);
+  });
+
+  it("flags a property upstream added that the surface lacks", () => {
+    const stripped = structuredClone(surface);
+    stripped.entries.Agent.props = stripped.entries.Agent.props!.filter(
+      (p) => !p.startsWith("system:"),
+    );
+
+    const report = computeFountainCoverage(spec, stripped);
+    const agent = report.kinds.find((k) => k.kind === "Agent")!;
+
+    expect(agent.missing).toEqual(["system"]);
+    expect(report.overallPct).toBeLessThan(100);
+  });
+
+  it("flags a surface property upstream no longer has", () => {
+    const extra = structuredClone(surface);
+    extra.entries.Vault.props = [...extra.entries.Vault.props!, "retired_field:false"];
+
+    const report = computeFountainCoverage(spec, extra);
+    const vault = report.kinds.find((k) => k.kind === "Vault")!;
+
+    expect(vault.stale).toEqual(["retired_field"]);
+  });
+
+  it("names the reason for each unmodeled kind in verbose output", () => {
+    const text = formatVerbose(computeFountainCoverage(spec, surface));
+
+    for (const [name, reason] of Object.entries(EXCLUDED_KINDS)) {
+      expect(text).toContain(name);
+      expect(text).toContain(reason);
+    }
+  });
+});

package/src/coverage.ts

@@ -0,0 +1,178 @@
+/**
+ * Coverage analysis for the fountain lexicon.
+ *
+ * The shared `computeCoverage` measures CloudFormation-shaped dimensions
+ * (lifecycle flags, return attributes, extension constraints) that a
+ * three-kind OpenAPI lexicon has no analog for — it would report 0% on
+ * everything and mean nothing. What fountain actually needs to know is
+ * whether its generated surface still matches upstream, because the spec
+ * is a rolling endpoint with no release tag to pin (see spec/fetch.ts):
+ *
+ *   1. Property coverage — request-schema properties per modeled kind vs
+ *      what the committed surface baseline exposes. A gap means upstream
+ *      added a field and `just generate` has not been rerun.
+ *   2. Kind coverage — which request-shaped schemas are modeled as
+ *      declarables, and which are deliberately not (with the reason), so
+ *      an unmodeled kind is a decision on record rather than an omission.
+ */
+
+import { readFileSync } from "fs";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+import { fetchSchemas } from "./spec/fetch";
+import { parseFountainOpenAPI, fountainShortName } from "./spec/parse";
+
+/** Request schemas with no typed resource, and why. */
+export const EXCLUDED_KINDS: Record<string, string> = {
+  ConversationCreateRequest: "conversations are runs, not declarables — started by the fountainRun op",
+  PromptRequest: "turn-level input inside a conversation run",
+  SecretRequest: "secrets are a write-only sub-resource — upserted by fountainApply",
+  VaultSecretRequest: "secrets are a write-only sub-resource — upserted by fountainApply",
+};
+
+export interface KindCoverage {
+  kind: string;
+  specProps: number;
+  modeledProps: number;
+  /** In the upstream request schema, absent from the generated surface. */
+  missing: string[];
+  /** In the generated surface, absent from the upstream request schema. */
+  stale: string[];
+}
+
+export interface FountainCoverageReport {
+  kinds: KindCoverage[];
+  /** Request schemas modeled as declarables. */
+  modeledKinds: string[];
+  /** Request schemas deliberately not modeled → reason. */
+  excludedKinds: Record<string, string>;
+  /** Request schemas neither modeled nor on the exclusion list. */
+  unaccountedKinds: string[];
+  /** Modeled properties as a percentage of upstream request properties. */
+  overallPct: number;
+}
+
+interface SurfaceSnapshot {
+  entries: Record<string, { kind: string; props?: string[] }>;
+}
+
+/** Strip the `name:required` encoding the surface baseline uses. */
+function surfaceProps(entry: { props?: string[] }): string[] {
+  return (entry.props ?? []).map((p) => p.split(":")[0]);
+}
+
+export function computeFountainCoverage(
+  specJSON: string | Buffer,
+  surface: SurfaceSnapshot,
+): FountainCoverageReport {
+  const parsed = parseFountainOpenAPI(specJSON);
+
+  const kinds: KindCoverage[] = [];
+  const modeledKinds: string[] = [];
+
+  for (const result of parsed) {
+    if (result.isProperty) continue;
+    const kind = fountainShortName(result.resource.typeName);
+    modeledKinds.push(kind);
+
+    const specNames = result.resource.properties.map((p) => p.name);
+    const entry = surface.entries[kind];
+    const modeledNames = entry ? surfaceProps(entry) : [];
+
+    const modeled = new Set(modeledNames);
+    const spec = new Set(specNames);
+
+    kinds.push({
+      kind,
+      specProps: specNames.length,
+      modeledProps: specNames.filter((n) => modeled.has(n)).length,
+      missing: specNames.filter((n) => !modeled.has(n)),
+      stale: modeledNames.filter((n) => !spec.has(n)),
+    });
+  }
+
+  // Which upstream request schemas are neither modeled nor excluded?
+  const schemas = Object.keys(
+    (JSON.parse(typeof specJSON === "string" ? specJSON : specJSON.toString("utf-8")) as {
+      components?: { schemas?: Record<string, unknown> };
+    }).components?.schemas ?? {},
+  );
+  const modeledRequests = new Set(modeledKinds.map((k) => `${k}Request`));
+  const unaccountedKinds = schemas.filter(
+    (name) =>
+      name.endsWith("Request") && !modeledRequests.has(name) && !(name in EXCLUDED_KINDS),
+  );
+
+  const totalSpec = kinds.reduce((n, k) => n + k.specProps, 0);
+  const totalModeled = kinds.reduce((n, k) => n + k.modeledProps, 0);
+
+  return {
+    kinds,
+    modeledKinds,
+    excludedKinds: EXCLUDED_KINDS,
+    unaccountedKinds,
+    overallPct: totalSpec === 0 ? 0 : Math.round((totalModeled / totalSpec) * 100),
+  };
+}
+
+export function formatSummary(report: FountainCoverageReport): string {
+  const parts = report.kinds.map((k) => `${k.kind} ${k.modeledProps}/${k.specProps}`);
+  return `Coverage: ${report.overallPct}% of upstream request properties (${parts.join(", ")}).`;
+}
+
+export function formatVerbose(report: FountainCoverageReport): string {
+  const lines = [formatSummary(report), ""];
+
+  for (const k of report.kinds) {
+    lines.push(`${k.kind}: ${k.modeledProps}/${k.specProps} properties`);
+    if (k.missing.length > 0) {
+      lines.push(`  missing (upstream has, lexicon does not): ${k.missing.join(", ")}`);
+    }
+    if (k.stale.length > 0) {
+      lines.push(`  stale (lexicon has, upstream does not): ${k.stale.join(", ")}`);
+    }
+  }
+
+  lines.push("", "Not modeled as declarables:");
+  for (const [name, reason] of Object.entries(report.excludedKinds)) {
+    lines.push(`  ${name} — ${reason}`);
+  }
+
+  if (report.unaccountedKinds.length > 0) {
+    lines.push(
+      "",
+      `Unaccounted request schemas (model them or add to EXCLUDED_KINDS): ${report.unaccountedKinds.join(", ")}`,
+    );
+  }
+
+  return lines.join("\n");
+}
+
+/** Run coverage analysis for the fountain lexicon. */
+export async function analyzeFountainCoverage(opts?: {
+  basePath?: string;
+  verbose?: boolean;
+  minOverall?: number;
+}): Promise<FountainCoverageReport> {
+  const basePath = opts?.basePath ?? dirname(dirname(fileURLToPath(import.meta.url)));
+
+  const specs = await fetchSchemas();
+  const specJSON = specs.get("fountain-openapi.json");
+  if (!specJSON) throw new Error("fountain coverage: no spec returned by fetchSchemas");
+
+  const surface = JSON.parse(
+    readFileSync(join(basePath, "surface.snapshot.json"), "utf-8"),
+  ) as SurfaceSnapshot;
+
+  const report = computeFountainCoverage(specJSON, surface);
+
+  console.error(opts?.verbose ? formatVerbose(report) : formatSummary(report));
+
+  if (typeof opts?.minOverall === "number" && report.overallPct < opts.minOverall) {
+    throw new Error(
+      `Coverage ${report.overallPct}% is below the ${opts.minOverall}% threshold`,
+    );
+  }
+
+  return report;
+}

package/src/describe-resources.test.ts

@@ -0,0 +1,203 @@
+import { describe, expect, it } from "vitest";
+import { describeObservationConformance } from "@intentius/chant-test-utils";
+import { normalizeObservation } from "@intentius/chant/observation";
+import { describeResources, type DescribeResourcesOptions } from "./describe-resources";
+import type { FountainHttp } from "./op/activities/fountain-apply";
+
+function entities(
+  defs: Record<string, { entityType: string; props?: Record<string, unknown> }>,
+): Map<string, { entityType: string; props: Record<string, unknown> }> {
+  return new Map(
+    Object.entries(defs).map(([name, d]) => [name, { entityType: d.entityType, props: d.props ?? {} }]),
+  );
+}
+
+function opts(
+  ents: Map<string, { entityType: string; props: Record<string, unknown> }>,
+  extra?: Partial<DescribeResourcesOptions>,
+): DescribeResourcesOptions {
+  return {
+    environment: "local",
+    buildOutput: "",
+    entityNames: [...ents.keys()],
+    entities: ents,
+    ...extra,
+  };
+}
+
+describe("list caching under the observer harness", () => {
+  it("lists each kind once no matter how many entities of it are declared", async () => {
+    const calls: string[] = [];
+    const counting: FountainHttp = async (method, path) => {
+      calls.push(`${method} ${path}`);
+      return { status: 200, json: { data: [] } };
+    };
+
+    await describeResources(
+      opts(
+        entities({
+          a: { entityType: "Fountain::V1::Environment" },
+          b: { entityType: "Fountain::V1::Environment" },
+          c: { entityType: "Fountain::V1::Environment" },
+          d: { entityType: "Fountain::V1::Agent" },
+        }),
+      ),
+      counting,
+    );
+
+    // The harness reads entities concurrently, so the cache must hold the
+    // in-flight promise — caching the settled result would let three
+    // simultaneous reads each fire their own list.
+    expect(calls.filter((c) => c === "GET /api/environments")).toHaveLength(1);
+    expect(calls.filter((c) => c === "GET /api/agents")).toHaveLength(1);
+  });
+
+  it("marks only the failed kind read-failed", async () => {
+    const partial: FountainHttp = async (_method, path) =>
+      path === "/api/agents" ? { status: 500, json: null } : { status: 200, json: { data: [] } };
+
+    const result = await describeResources(
+      opts(
+        entities({
+          env: { entityType: "Fountain::V1::Environment" },
+          agent: { entityType: "Fountain::V1::Agent" },
+        }),
+      ),
+      partial,
+    );
+
+    expect(result.unobserved?.agent?.reason).toBe("read-failed");
+    // The environment was genuinely asked about and reported missing —
+    // absent, not unobserved, so it stays eligible for `create`.
+    expect(result.unobserved?.env).toBeUndefined();
+    expect(result.resources?.env).toBeUndefined();
+  });
+});
+
+function routedHttp(routes: Record<string, { status: number; json?: unknown }>): FountainHttp {
+  return async (method, path) => {
+    const hit = routes[`${method} ${path}`];
+    if (!hit) throw new Error(`unrouted: ${method} ${path}`);
+    return { status: hit.status, json: hit.json ?? null };
+  };
+}
+
+const LIVE = routedHttp({
+  "GET /api/environments": {
+    status: 200,
+    json: {
+      data: [
+        {
+          id: "env-1",
+          name: "concierge-env",
+          metadata: { "managed-by": "chant" },
+          updated_at: "2026-07-30T00:00:00Z",
+        },
+      ],
+    },
+  },
+  "GET /api/vaults": { status: 200, json: { data: [] } },
+  "GET /api/agents": {
+    status: 200,
+    json: {
+      data: [
+        { id: "agent-1", name: "researcher", metadata: {}, environment_id: "env-1" },
+      ],
+    },
+  },
+});
+
+describe("fountain describeResources", () => {
+  it("reports present resources with ownership and reference attributes", async () => {
+    const ents = entities({
+      conciergeEnv: { entityType: "Fountain::V1::Environment", props: { name: "concierge-env" } },
+      researcher: { entityType: "Fountain::V1::Agent", props: { name: "researcher" } },
+      gone: { entityType: "Fountain::V1::Vault", props: { name: "not-there" } },
+    });
+
+    const { resources, unobserved } = normalizeObservation(await describeResources(opts(ents), LIVE));
+
+    expect(resources.conciergeEnv.ownership).toBe("owned");
+    expect(resources.conciergeEnv.physicalId).toBe("env-1");
+    expect(resources.researcher.ownership).toBe("foreign");
+    expect(resources.researcher.attributes?.environment_id).toBe("env-1");
+    // asked, absent → eligible for create, not unobserved
+    expect(resources.gone).toBeUndefined();
+    expect(unobserved.gone).toBeUndefined();
+  });
+
+  it("owned filter withholds foreign resources as filtered", async () => {
+    const ents = entities({
+      researcher: { entityType: "Fountain::V1::Agent", props: { name: "researcher" } },
+    });
+    const { resources, unobserved } = normalizeObservation(
+      await describeResources(opts(ents, { owned: true }), LIVE),
+    );
+    expect(resources.researcher).toBeUndefined();
+    expect(unobserved.researcher.reason).toBe("filtered");
+  });
+
+  it("a failed kind list marks only that kind read-failed", async () => {
+    const ents = entities({
+      e: { entityType: "Fountain::V1::Environment", props: { name: "concierge-env" } },
+      a: { entityType: "Fountain::V1::Agent", props: { name: "researcher" } },
+    });
+    const http = routedHttp({
+      "GET /api/environments": { status: 500 },
+      "GET /api/agents": {
+        status: 200,
+        json: { data: [{ id: "agent-1", name: "researcher", metadata: {} }] },
+      },
+    });
+    const { resources, unobserved } = normalizeObservation(await describeResources(opts(ents), http));
+    expect(unobserved.e.reason).toBe("read-failed");
+    expect(resources.a.status).toBe("PRESENT");
+  });
+});
+
+describeObservationConformance({
+  lexicon: "fountain",
+  scenarios: [
+    {
+      name: "mixed present/absent/foreign against a live listing",
+      declared: ["conciergeEnv", "researcher", "gone"],
+      expectPresent: ["conciergeEnv", "researcher"],
+      expectAbsent: ["gone"],
+      run: () =>
+        describeResources(
+          opts(
+            entities({
+              conciergeEnv: { entityType: "Fountain::V1::Environment", props: { name: "concierge-env" } },
+              researcher: { entityType: "Fountain::V1::Agent", props: { name: "researcher" } },
+              gone: { entityType: "Fountain::V1::Vault", props: { name: "not-there" } },
+            }),
+          ),
+          LIVE,
+        ),
+    },
+    {
+      name: "no credentials — everything unobserved, nothing creates",
+      declared: ["e"],
+      expectUnobserved: ["e"],
+      run: () => {
+        const saved = process.env.FOUNTAIN_TOKEN;
+        delete process.env.FOUNTAIN_TOKEN;
+        const result = describeResources(
+          opts(entities({ e: { entityType: "Fountain::V1::Environment" } })),
+        );
+        if (saved !== undefined) process.env.FOUNTAIN_TOKEN = saved;
+        return result;
+      },
+    },
+    {
+      name: "unknown kind is unobserved, not absent",
+      declared: ["weird"],
+      expectUnobserved: ["weird"],
+      run: () =>
+        describeResources(
+          opts(entities({ weird: { entityType: "Fountain::V1::Conversation" } })),
+          LIVE,
+        ),
+    },
+  ],
+});