@intentius/chant-lexicon-fountain 0.52.1 → 0.53.0

package/dist/deep-observe-hooks.d.ts

@@ -0,0 +1,78 @@
+/**
+ * fountain deep-observation noise rules (#1217).
+ *
+ * Plain data, imported statically by `plugin.ts`, because core applies the
+ * identical rules to the *declared* property tree — which no reader ever
+ * touches — before it diffs. Burying them inside the read would normalize the
+ * two sides differently and report everything as drift.
+ *
+ * ## Why a static table and not an ownership walk
+ *
+ * Kubernetes records `managedFields`, so the k8s row can subtract whatever a
+ * controller owns. A fountain REST payload never says who wrote a field, so
+ * this row follows the GCP precedent (`lexicons/gcp/src/deep-observe-hooks.ts`)
+ * — a hand-maintained table naming what the server populates. The cost is
+ * explicit: a server-set field nobody has listed reads as drift until it is
+ * listed. That is visible and fixable; an over-broad rule silently hides real
+ * drift, which is the worse of the two failures.
+ *
+ * Every value below is read off fountain's own Ecto schemas (`Environment`,
+ * `Vault`, `Agent`) and the JSON views that render them, not guessed from a
+ * sample payload.
+ *
+ * ## Secrets
+ *
+ * chant authors an environment's or vault's `secrets` as an ordered
+ * `{key, value}[]`, so the declared node holds real secret material. Core's
+ * key-name mask (`SENSITIVE_KEY_PATTERNS` matches `secrets`) collapses the
+ * whole node to `[REDACTED]` on both trees before any diff sees it, which is
+ * the correct outcome and also the limit of what this row can report: presence
+ * — an environment that declares no secrets and has some, or the reverse —
+ * never the key set, and never a value. Making the key set diffable needs
+ * fountain#148's reference model, where secrets stop being inline values.
+ *
+ * {@link fountainDeepNormalizationHooks.mask} adds one narrow rule on top:
+ * a string matching a known credential shape is collapsed wherever it appears,
+ * whatever the key is called. FTN001/FTN012 already refuse those at lint time;
+ * this is the backstop for a value that reached the live instance some other
+ * way, so a drift row can never print one.
+ */
+import type { DeepNormalizationHooks } from "@intentius/chant/deep-observation";
+export declare const ENVIRONMENT_TYPE = "Fountain::V1::Environment";
+export declare const VAULT_TYPE = "Fountain::V1::Vault";
+export declare const AGENT_TYPE = "Fountain::V1::Agent";
+/**
+ * Top-level payload fields fountain writes and a caller cannot: the primary
+ * key, the `timestamps()` pair, the owning user, the virtual `*_count` rollups
+ * the `*_with_counts` reads attach, the avatar's derived media type, and `acp`
+ * (computed per request from the runtime, never stored).
+ *
+ * Pruned on BOTH sides and regardless of what source declared, since a user who
+ * writes one is writing something the API overwrites anyway.
+ *
+ * Matched on the whole pattern rather than its last segment: `name` and `id`
+ * also occur *inside* `skills[]` and `repositories[]`, where they are authored
+ * configuration. `SERVER_FIELDS` is shared with the import/export path so the
+ * two cannot disagree about what a caller may author.
+ */
+export declare const FOUNTAIN_SERVER_FIELDS: ReadonlySet<string>;
+/**
+ * Per-kind values fountain fills in when the request omits them, keyed by the
+ * index-erased pattern from the tree root.
+ *
+ * Noise only where **source never declared the property** — the
+ * `counterpart === "absent"` gate below. A default somebody wrote out
+ * explicitly is a fact worth diffing, and a later change away from it has to
+ * stay reportable.
+ *
+ * Straight off the Ecto `schema` blocks. `networking_type: "unrestricted"` is
+ * the one worth arguing about: subtracting it means an environment that never
+ * states its networking posture does not report one. That case is FTN010's, at
+ * lint time, where it is a build finding rather than drift; and the case this
+ * row exists for — a reviewed `limited` environment flipped to `unrestricted`
+ * in the UI — has a declared counterpart, so the gate keeps it and it reports
+ * as `changed`.
+ */
+export declare const FOUNTAIN_DEFAULTS: Readonly<Record<string, Readonly<Record<string, unknown>>>>;
+export declare const fountainDeepNormalizationHooks: DeepNormalizationHooks;
+//# sourceMappingURL=deep-observe-hooks.d.ts.map

package/dist/deep-observe-hooks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deep-observe-hooks.d.ts","sourceRoot":"","sources":["../src/deep-observe-hooks.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,OAAO,KAAK,EAGV,sBAAsB,EACvB,MAAM,mCAAmC,CAAC;AAG3C,eAAO,MAAM,gBAAgB,8BAA8B,CAAC;AAC5D,eAAO,MAAM,UAAU,wBAAwB,CAAC;AAChD,eAAO,MAAM,UAAU,wBAAwB,CAAC;AAEhD;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,sBAAsB,EAAE,WAAW,CAAC,MAAM,CAKrD,CAAC;AAEH;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,iBAAiB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAC,CAiBzF,CAAC;AAoDF,eAAO,MAAM,8BAA8B,EAAE,sBA0E5C,CAAC"}

package/dist/deep-observe.d.ts

@@ -0,0 +1,84 @@
+/**
+ * fountain deep observation (#1217) — the fountain row of the deep-observe
+ * contract (#1014).
+ *
+ * `describeResources()` (./describe-resources.ts) answers whether a declared
+ * Environment/Vault/Agent exists and hands back its id and timestamps. That
+ * misses the drift the design was written for: an environment hand-edited in
+ * the fountain UI from `networking_type: limited` to `unrestricted`, an
+ * `allowed_vault_ids` allowlist widened, a skill repointed at an unpinned
+ * branch, a secret added to a reviewed sandbox. All of it lives one level
+ * down, in properties nobody was reading.
+ *
+ * ## The read is the thin path's read
+ *
+ * Transport, endpoint and auth are the applier's, unchanged
+ * (`FOUNTAIN_ENDPOINT` / `FOUNTAIN_TOKEN`), so plan reads the instance
+ * `fountainApply` writes. And the depth is free: fountain's list endpoints
+ * render the full record — `GET /api/environments` returns every configuration
+ * field the request schema accepts, not a summary — so there is no per-resource
+ * follow-up GET the way the AWS row needs Cloud Control on top of
+ * `describe-stack-resources`. One list per declared kind, cached, exactly as
+ * the thin path does it.
+ *
+ * ## The payload passes through
+ *
+ * fountain's JSON views name their fields the same way the request schema does
+ * (`networking_type`, `env_vars`, `skills`), so the live tree and the declared
+ * tree already speak one vocabulary — the AWS situation, not temporal's. The
+ * payload is therefore forwarded as-is and the noise rules
+ * (./deep-observe-hooks.ts) do the rest. A field fountain adds in a later
+ * release surfaces as `undeclared` until the table names it, which is the
+ * deliberate trade: visible and fixable beats silently dropped.
+ *
+ * One exception, and it is the reference edge. chant declares an agent's
+ * environment as a typed reference (`environment`), fountain stores the id it
+ * resolved to (`environment_id`). Passing the id through would report
+ * `<undeclared> -> <uuid>` on every clean read, so where source did not author
+ * `environment_id` itself the id is resolved back to the environment's name and
+ * emitted as `environment` — the same translation `exportResources()` does for
+ * the import path.
+ *
+ * ## Secrets: presence, never keys, never values
+ *
+ * Values are write-only upstream and are never read here at all. The secrets
+ * sub-resource is listed (keys and timestamps only) so that an environment or
+ * vault which declares no secrets and has some — somebody adding one to a
+ * locked-down sandbox — reports as drift. Core's key-name mask collapses the
+ * whole `secrets` node on both trees, so what a diff row can say is that
+ * secrets exist, not which. See the hooks module for why the key set itself is
+ * not expressible until fountain#148 lands.
+ *
+ * That listing is one extra request per observed Environment and Vault. A
+ * fountain tenant holds a handful of each, and the alternative — inferring
+ * presence from the newer payload's `secret_count` — would silently report
+ * "no secrets" against any instance predating that field.
+ */
+import type { DeepObservationResult } from "@intentius/chant/lexicon";
+import { type FountainHttp } from "./op/activities/fountain-apply.js";
+import { fountainDeepNormalizationHooks } from "./deep-observe-hooks.js";
+export { fountainDeepNormalizationHooks };
+export interface FountainDeepObserveOptions {
+    environment: string;
+    buildOutput?: string;
+    entityNames: string[];
+    entities: Map<string, {
+        entityType: string;
+        props: Record<string, unknown>;
+    }>;
+    stack?: string;
+    /** Restrict to resources carrying the `managed-by: chant` marker. */
+    owned?: boolean;
+    /** Endpoint override (tests). Defaults to resolveEndpoint(). */
+    endpoint?: string;
+}
+/**
+ * Read the live property tree for each declared fountain entity.
+ *
+ * `http` is injectable for tests; the default reuses the applier's fetch client
+ * (bearer token from FOUNTAIN_TOKEN). A missing token is the whole-lexicon
+ * failure the thin path already names — every declared entity NOT-OBSERVED with
+ * `no-credentials`, never an empty tree, which would read as "nothing drifted".
+ */
+export declare function observeResourcesDeepFountain(options: FountainDeepObserveOptions, injected?: FountainHttp): Promise<DeepObservationResult>;
+//# sourceMappingURL=deep-observe.d.ts.map

package/dist/deep-observe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deep-observe.d.ts","sourceRoot":"","sources":["../src/deep-observe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAEH,OAAO,KAAK,EACV,qBAAqB,EAGtB,MAAM,0BAA0B,CAAC;AAGlC,OAAO,EAML,KAAK,YAAY,EAClB,MAAM,gCAAgC,CAAC;AACxC,OAAO,EACL,8BAA8B,EAI/B,MAAM,sBAAsB,CAAC;AAM9B,OAAO,EAAE,8BAA8B,EAAE,CAAC;AAW1C,MAAM,WAAW,0BAA0B;IACzC,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,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,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,qEAAqE;IACrE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AA+ED;;;;;;;GAOG;AACH,wBAAsB,4BAA4B,CAChD,OAAO,EAAE,0BAA0B,EACnC,QAAQ,CAAC,EAAE,YAAY,GACtB,OAAO,CAAC,qBAAqB,CAAC,CAkGhC"}

package/dist/import/local-agents.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Re-express a machine's local agent configuration as fountain resources.
+ *
+ * `chant audit --agents` answers "what is configured on this machine". This is
+ * the other half: taking that inventory and turning it into chant code, so a
+ * configuration that accumulated by hand over months becomes a reviewable,
+ * version-controlled, reproducible declaration.
+ *
+ * The mapping is close to 1:1 because fountain's `Agent` models the same four
+ * ideas the harnesses do:
+ *
+ *   | local agent config            | fountain              |
+ *   |-------------------------------|-----------------------|
+ *   | CLAUDE.md / AGENTS.md         | `Agent.system`        |
+ *   | `mcpServers` / `mcp_servers`  | `Agent.mcp_servers`   |
+ *   | `skills/*​/SKILL.md`           | `Agent.skills`        |
+ *   | settings `env`                | `Environment.env_vars`|
+ *
+ * Three places where it is deliberately *not* a transcription:
+ *
+ *  1. **Egress is derived, not copied.** A local agent runs with the machine's
+ *     full network access; a fountain sandbox must declare intent (FTN010). The
+ *     hosts the config's own remote MCP servers use are exactly the egress it
+ *     demonstrably needs, so those become the `allowed_hosts` allowlist and
+ *     everything else is denied. Copying "unrestricted" would launder an
+ *     implicit local permission into an explicit remote one.
+ *  2. **Secrets are not carried over.** A literal credential found in local
+ *     config (AGT002) is rewritten to a `${VAR}` reference in the emitted code.
+ *     Generated chant code gets committed; transcribing a live secret into it
+ *     would turn a local mistake into a repository one.
+ *  3. **Skills are inlined by content where possible.** A local skill is text
+ *     on this machine with no upstream, so `{name, content}` is the only form
+ *     that reproduces it elsewhere. Remote skills keep `{source, ref}`.
+ *
+ * Cursor is discovered by the scanner but has no fountain `runtime` value, so
+ * its sites are reported as skipped rather than silently mapped onto a
+ * different agent runtime.
+ */
+import type { AgentConfigSite, McpServerDecl, SkillDecl } from "@intentius/chant/agents";
+import type { AgentImportOutcome } from "@intentius/chant/agents/importer";
+/** Runtimes fountain's `Agent.runtime` accepts. `cursor` is absent by design. */
+export declare const MAPPABLE_RUNTIMES: readonly ["claude", "codex", "gemini", "opencode"];
+export type MappableRuntime = (typeof MAPPABLE_RUNTIMES)[number];
+/**
+ * Default model per runtime, used when the local config pins none.
+ *
+ * `Agent.model` is required by fountain, and most local configs leave the model
+ * to the harness's own default — a value that isn't written down anywhere this
+ * scanner can read. Emitting a documented default that the user edits is more
+ * honest than inventing a pin and calling it discovered; `unmappedModel` in the
+ * result reports every site this applied to.
+ */
+export declare const DEFAULT_MODEL: Record<MappableRuntime, string>;
+/**
+ * Build the `system` prompt from the site's instruction files.
+ *
+ * Provenance is kept as a comment header per file. A user reading the generated
+ * code needs to know which of their three CLAUDE.md files a paragraph came
+ * from, and a single concatenated blob without headers makes that unrecoverable.
+ */
+export declare function buildSystem(site: AgentConfigSite): string | undefined;
+/** Project the normalized MCP declarations back into fountain's `mcp_servers` map. */
+export declare function toMcpServers(servers: McpServerDecl[], onRedact: () => void): Record<string, unknown> | undefined;
+/**
+ * Project skills into fountain's two accepted forms.
+ *
+ * fountain requires exactly one of `content` or `source` per entry. A local
+ * skill has no upstream to install from, so its text is inlined — that is what
+ * makes the emitted code reproduce the configuration on a machine that has
+ * never seen this one.
+ */
+export declare function toSkills(skills: SkillDecl[]): Record<string, unknown>[] | undefined;
+/**
+ * Hosts the config's own remote MCP servers reach.
+ *
+ * This is the evidence-based egress allowlist: every host here is one the
+ * configuration already talks to, so the sandbox stays functional while
+ * everything else stays denied.
+ */
+export declare function derivedAllowedHosts(servers: McpServerDecl[]): string[];
+/** Canonicalize a local model name into fountain's `provider/model_id` form. */
+export declare function canonicalModel(local: string | undefined, runtime: MappableRuntime): {
+    model: string;
+    defaulted: boolean;
+};
+/**
+ * Convert discovered agent config sites into fountain import IR.
+ *
+ * Each mappable site yields an `Agent`, plus an `Environment` when it has
+ * anything environmental to declare (env vars, or remote MCP hosts to
+ * allowlist). Feed the result to `FountainGenerator` to get chant TypeScript.
+ */
+export declare function sitesToTemplateIR(sites: AgentConfigSite[]): AgentImportOutcome;
+//# sourceMappingURL=local-agents.d.ts.map

package/dist/import/local-agents.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local-agents.d.ts","sourceRoot":"","sources":["../../src/import/local-agents.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAGH,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,yBAAyB,CAAC;AACzF,OAAO,KAAK,EAAE,kBAAkB,EAAe,MAAM,kCAAkC,CAAC;AAExF,iFAAiF;AACjF,eAAO,MAAM,iBAAiB,oDAAqD,CAAC;AACpF,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,iBAAiB,CAAC,CAAC,MAAM,CAAC,CAAC;AAEjE;;;;;;;;GAQG;AACH,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,eAAe,EAAE,MAAM,CAKzD,CAAC;AA0BF;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,eAAe,GAAG,MAAM,GAAG,SAAS,CAIrE;AAuGD,sFAAsF;AACtF,wBAAgB,YAAY,CAAC,OAAO,EAAE,aAAa,EAAE,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAsBhH;AAED;;;;;;;GAOG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,SAAS,CAanF;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,aAAa,EAAE,GAAG,MAAM,EAAE,CAYtE;AAED,gFAAgF;AAChF,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,EAAE,OAAO,EAAE,eAAe,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAKzH;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,eAAe,EAAE,GAAG,kBAAkB,CA8E9E"}

package/dist/index.d.ts

@@ -1,5 +1,8 @@
 export { fountainPlugin } from "./plugin.js";
 export { fountainSerializer } from "./serializer.js";
+export { observeResourcesDeepFountain } from "./deep-observe.js";
+export type { FountainDeepObserveOptions } from "./deep-observe.js";
+export { fountainDeepNormalizationHooks, FOUNTAIN_SERVER_FIELDS, FOUNTAIN_DEFAULTS, } from "./deep-observe-hooks.js";
 export * from "./generated/index.js";
 export { fountainApply, fountainRun, DEFAULT_FOUNTAIN_BASE_URL } from "./op/activities/index.js";
 export type { FountainApplyArgs, FountainApplySummary, FountainRunArgs, FountainRunResult } from "./op/activities/index.js";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAG1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAGlD,cAAc,mBAAmB,CAAC;AAIlC,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AACxF,YAAY,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAGnH,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,YAAY,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,cAAc,EAAE,MAAM,UAAU,CAAC;AAG1C,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAIlD,OAAO,EAAE,4BAA4B,EAAE,MAAM,gBAAgB,CAAC;AAC9D,YAAY,EAAE,0BAA0B,EAAE,MAAM,gBAAgB,CAAC;AACjE,OAAO,EACL,8BAA8B,EAC9B,sBAAsB,EACtB,iBAAiB,GAClB,MAAM,sBAAsB,CAAC;AAG9B,cAAc,mBAAmB,CAAC;AAIlC,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,yBAAyB,EAAE,MAAM,iBAAiB,CAAC;AACxF,YAAY,EAAE,iBAAiB,EAAE,oBAAoB,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAGnH,OAAO,EAAE,cAAc,EAAE,MAAM,8BAA8B,CAAC;AAC9D,YAAY,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,MAAM,8BAA8B,CAAC"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "786fec6cfad4f4d2038f4cac675c486da09a3ed512b8619f43dbdd53ee07f25a",
+    "manifest.json": "3c1bc0c06594180eed030af320ad7a1cf16e5beda1a9c42ec44568e8b1e19368",
     "meta.json": "6666b7a77db9210a329219c6a5e107e5ae8794a34542f7310ce16d9bf95c64f5",
     "types/index.d.ts": "1dfdcba184fffcf464dac7d1d71ef7abed2ae02a8d638c0de50e0b0317b7eb01",
     "rules/ftn001-no-secret-literals.ts": "897a4ce1ec790b3c1540d32892603bd33ff4bf30eb6ba4cd2565dee356d4962e",
@@ -17,5 +17,5 @@
     "skills/chant-fountain-secrets.md": "27e349a91589510a92e518c7d7824a4a322cab5ef242cf5799373a55cbfcd1cd",
     "skills/chant-fountain-locked-sandboxes.md": "de82f06cb3a08ba6bf3ae45fb9869e21d6da18b9ebe0fc769da8aebaceea7dd1"
   },
-  "composite": "8b6dab62a2f3e42ad0d8fb770499b7d4c978895e398aec222b97cc3991dee178"
+  "composite": "3b6b337bb3b931f76ae5ddac80fb34cfaf53ca9d8fcd6084f09c52f0106bb1fe"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "fountain",
-  "version": "0.52.1",
+  "version": "0.53.0",
   "chantVersion": ">=0.1.0",
   "namespace": "Fountain",
   "specVersion": "v0.3.0"

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;AAuB7F;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,aA0J5B,CAAC"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAiC,MAAM,0BAA0B,CAAC;AAyB7F;;;;GAIG;AACH,eAAO,MAAM,cAAc,EAAE,aAyK5B,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-fountain",
-  "version": "0.52.1",
+  "version": "0.53.0",
   "type": "module",
   "description": "Fountain lexicon for chant — sandboxed agent environments, vaults, and agents as typed estate",
   "license": "Apache-2.0",
@@ -50,7 +50,7 @@
     "bundle": "tsx src/package-cli.ts"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.52.1",
+    "@intentius/chant": "^0.53.0",
     "typescript": "^5.9.3"
   },
   "devDependencies": {

package/src/deep-observe-hooks.ts

@@ -0,0 +1,237 @@
+/**
+ * fountain deep-observation noise rules (#1217).
+ *
+ * Plain data, imported statically by `plugin.ts`, because core applies the
+ * identical rules to the *declared* property tree — which no reader ever
+ * touches — before it diffs. Burying them inside the read would normalize the
+ * two sides differently and report everything as drift.
+ *
+ * ## Why a static table and not an ownership walk
+ *
+ * Kubernetes records `managedFields`, so the k8s row can subtract whatever a
+ * controller owns. A fountain REST payload never says who wrote a field, so
+ * this row follows the GCP precedent (`lexicons/gcp/src/deep-observe-hooks.ts`)
+ * — a hand-maintained table naming what the server populates. The cost is
+ * explicit: a server-set field nobody has listed reads as drift until it is
+ * listed. That is visible and fixable; an over-broad rule silently hides real
+ * drift, which is the worse of the two failures.
+ *
+ * Every value below is read off fountain's own Ecto schemas (`Environment`,
+ * `Vault`, `Agent`) and the JSON views that render them, not guessed from a
+ * sample payload.
+ *
+ * ## Secrets
+ *
+ * chant authors an environment's or vault's `secrets` as an ordered
+ * `{key, value}[]`, so the declared node holds real secret material. Core's
+ * key-name mask (`SENSITIVE_KEY_PATTERNS` matches `secrets`) collapses the
+ * whole node to `[REDACTED]` on both trees before any diff sees it, which is
+ * the correct outcome and also the limit of what this row can report: presence
+ * — an environment that declares no secrets and has some, or the reverse —
+ * never the key set, and never a value. Making the key set diffable needs
+ * fountain#148's reference model, where secrets stop being inline values.
+ *
+ * {@link fountainDeepNormalizationHooks.mask} adds one narrow rule on top:
+ * a string matching a known credential shape is collapsed wherever it appears,
+ * whatever the key is called. FTN001/FTN012 already refuse those at lint time;
+ * this is the backstop for a value that reached the live instance some other
+ * way, so a drift row can never print one.
+ */
+
+import type {
+  DeepArrayElement,
+  DeepNode,
+  DeepNormalizationHooks,
+} from "@intentius/chant/deep-observation";
+import { SERVER_FIELDS } from "./import/parser";
+
+export const ENVIRONMENT_TYPE = "Fountain::V1::Environment";
+export const VAULT_TYPE = "Fountain::V1::Vault";
+export const AGENT_TYPE = "Fountain::V1::Agent";
+
+/**
+ * Top-level payload fields fountain writes and a caller cannot: the primary
+ * key, the `timestamps()` pair, the owning user, the virtual `*_count` rollups
+ * the `*_with_counts` reads attach, the avatar's derived media type, and `acp`
+ * (computed per request from the runtime, never stored).
+ *
+ * Pruned on BOTH sides and regardless of what source declared, since a user who
+ * writes one is writing something the API overwrites anyway.
+ *
+ * Matched on the whole pattern rather than its last segment: `name` and `id`
+ * also occur *inside* `skills[]` and `repositories[]`, where they are authored
+ * configuration. `SERVER_FIELDS` is shared with the import/export path so the
+ * two cannot disagree about what a caller may author.
+ */
+export const FOUNTAIN_SERVER_FIELDS: ReadonlySet<string> = new Set([
+  ...SERVER_FIELDS,
+  "secret_count",
+  "agent_count",
+  "acp",
+]);
+
+/**
+ * Per-kind values fountain fills in when the request omits them, keyed by the
+ * index-erased pattern from the tree root.
+ *
+ * Noise only where **source never declared the property** — the
+ * `counterpart === "absent"` gate below. A default somebody wrote out
+ * explicitly is a fact worth diffing, and a later change away from it has to
+ * stay reportable.
+ *
+ * Straight off the Ecto `schema` blocks. `networking_type: "unrestricted"` is
+ * the one worth arguing about: subtracting it means an environment that never
+ * states its networking posture does not report one. That case is FTN010's, at
+ * lint time, where it is a build finding rather than drift; and the case this
+ * row exists for — a reviewed `limited` environment flipped to `unrestricted`
+ * in the UI — has a declared counterpart, so the gate keeps it and it reports
+ * as `changed`.
+ */
+export const FOUNTAIN_DEFAULTS: Readonly<Record<string, Readonly<Record<string, unknown>>>> = {
+  [ENVIRONMENT_TYPE]: {
+    setup_script: "",
+    networking_type: "unrestricted",
+    repositories: [],
+  },
+  [VAULT_TYPE]: {
+    description: "",
+  },
+  [AGENT_TYPE]: {
+    description: "",
+    system: "",
+    skills: [],
+    // ADR 0023. Not on the committed spec snapshot yet, so an instance that
+    // predates it simply never emits the field.
+    sandbox_mode: "ephemeral",
+  },
+};
+
+/**
+ * Credential shapes FTN001 refuses in source and FTN012 refuses in `env_vars`.
+ * Reused here as the mask's own rule so the two lists cannot drift apart in
+ * what they call a credential.
+ */
+const CREDENTIAL_VALUE_SHAPES: readonly RegExp[] = [
+  /^AKIA[0-9A-Z]{16}$/,
+  /^(ghp|gho|ghs|ghu)_[A-Za-z0-9]{20,}$/,
+  /^github_pat_[A-Za-z0-9_]{20,}$/,
+  /^sk-[A-Za-z0-9_-]{20,}$/,
+  /^ftn_[A-Za-z0-9]{16,}$/,
+  /^xox[baprs]-[A-Za-z0-9-]{10,}$/,
+  /^-----BEGIN [A-Z ]*PRIVATE KEY-----/,
+];
+
+/** Key-order-independent equality, so a default written as a container matches whatever order a payload arrives in. */
+function equalsDefault(expected: unknown, actual: unknown): boolean {
+  if (expected === actual) return true;
+  if (typeof expected !== typeof actual) return false;
+  return canonicalJson(expected) === canonicalJson(actual);
+}
+
+function canonicalJson(value: unknown): string {
+  return (
+    JSON.stringify(value, (_k, v: unknown) =>
+      v && typeof v === "object" && !Array.isArray(v)
+        ? Object.fromEntries(
+            Object.entries(v as Record<string, unknown>).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)),
+          )
+        : v,
+    ) ?? ""
+  );
+}
+
+/** An `{}` with nothing pruned out of it — fountain's spelling for an unset `:map` column. */
+function isEmptyObject(value: unknown): boolean {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && Object.keys(value).length === 0;
+}
+
+function isEmptyArray(value: unknown): boolean {
+  return Array.isArray(value) && value.length === 0;
+}
+
+/** The final segment of an index-erased pattern (`skills[].name` -> `name`). */
+function lastSegment(pattern: string): string {
+  const withoutIndex = pattern.replace(/\[\]$/, "");
+  const dot = withoutIndex.lastIndexOf(".");
+  return dot === -1 ? withoutIndex : withoutIndex.slice(dot + 1);
+}
+
+export const fountainDeepNormalizationHooks: DeepNormalizationHooks = {
+  /**
+   * A credential-shaped string never reaches a diff row, a log line or a
+   * snapshot. Collapsed on both trees, so a value that is the same on both
+   * still classifies as unchanged; a changed one classifies as changed without
+   * either side being printed. Same contract as the k8s row's Secret mask
+   * (#1365 decision 6): presence and paths, never values.
+   */
+  mask(node: DeepNode): boolean {
+    return typeof node.value === "string" && CREDENTIAL_VALUE_SHAPES.some((p) => p.test(node.value as string));
+  },
+
+  prune(node: DeepNode): boolean {
+    // Server-written, on either side, declared or not.
+    if (FOUNTAIN_SERVER_FIELDS.has(node.pattern)) return true;
+
+    // An authored-but-empty `secrets` list is not a fountain state: there is no
+    // sub-resource to read back for it, so leaving it on the declared side
+    // would report `absent` on every clean read.
+    if (lastSegment(node.pattern) === "secrets" && isEmptyArray(node.value)) return true;
+
+    // Below here: values fountain populated that source never asked for.
+    // `counterpart` is a tri-state and only `absent` licenses subtraction.
+    if (node.side !== "live" || node.counterpart !== "absent") return false;
+
+    // `name` is the key the read looked the resource up by, so it can never
+    // disagree with the declaration; it is undeclared only when the serializer
+    // fell back to the chant export name, which is chant reading back its own
+    // choice rather than drift.
+    if (node.pattern === "name") return true;
+
+    // fountain's spellings for "never configured": a nullable column and an
+    // unset `:map`. `[]` is deliberately NOT in this rule — an empty
+    // `allowed_vault_ids` means "no vault may attach", which is a posture
+    // somebody chose, not an absence. The empty-list defaults that ARE server
+    // defaults (`skills`, `repositories`) are named per kind below.
+    if (node.value === null || isEmptyObject(node.value)) return true;
+
+    const defaults = FOUNTAIN_DEFAULTS[node.entityType];
+    if (!defaults || !Object.prototype.hasOwnProperty.call(defaults, node.pattern)) return false;
+    return equalsDefault(defaults[node.pattern], node.value);
+  },
+
+  /**
+   * The set-shaped lists. `repositories` and `skills` are keyed by their own
+   * identity so one added entry does not rename every entry after it in the
+   * flattened diff; the id/host lists are keyed by the element itself.
+   *
+   * Nothing else is reordered. An array whose elements do not all yield a key
+   * keeps the order the payload arrived in, which is the right answer wherever
+   * order might carry meaning.
+   */
+  orderKey(element: DeepArrayElement): string | undefined {
+    const name = lastSegment(element.pattern);
+    const el = element.element;
+
+    if (name === "allowed_vault_ids" || name === "allowed_environment_ids" || name === "allowed_hosts") {
+      return typeof el === "string" ? el : undefined;
+    }
+
+    if (name === "repositories" && isRecord(el)) {
+      return typeof el.mount_path === "string" ? el.mount_path : undefined;
+    }
+
+    if (name === "skills" && isRecord(el)) {
+      // An inline entry is identified by its name, a github entry by its repo.
+      // Exactly one of the two is set — the server's own changeset enforces it.
+      if (typeof el.name === "string") return el.name;
+      if (typeof el.source === "string") return el.source;
+      return undefined;
+    }
+
+    return undefined;
+  },
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}