primitive-admin 1.1.0-alpha.4 → 1.1.0-alpha.40

package/dist/src/lib/toml-metadata-config.d.ts

@@ -0,0 +1,108 @@
+/**
+ * CLI TOML parser / validator / serializer for resource-metadata config
+ * surfaces (issue #1304, P-B — CLI/TOML config-sync).
+ *
+ * Two surfaces, mirroring the "config change ships all three surfaces" rule
+ * (CLAUDE.md; same shape as the database type-config helpers in
+ * `toml-database-config.ts`):
+ *
+ *   1. `MetadataCategoryConfig` blocks — a per-`{resourceType, category}`
+ *      typed-schema + read/write-rule definition. These round-trip through
+ *      `primitive sync push` / `pull` against the P-A REST API
+ *      (`metadata-categories` CRUD). One file = one category, using a single
+ *      `[metadataCategoryConfig]` section so the nested `schema.fields.*`
+ *      tables serialize cleanly and byte-stably.
+ *
+ *   2. The declared-access manifest (`[metadata]` + `secrets` blocks) that
+ *      lives on the owning config surfaces (`CollectionTypeConfig` /
+ *      `DatabaseTypeConfig` / `WorkflowDefinition`). This module provides the
+ *      TOML *structure* + *validator* + byte-stable round-trip helpers for the
+ *      manifest so a bad value is rejected with a clear error. Wiring the
+ *      manifest onto those config models' sync push/pull (which needs a
+ *      storage field on each model) is P-C's "persist the manifest on owning
+ *      configs" work — this module ships the parse/validate/serialize the
+ *      P-C eval-site folding will call, matching how earlier phases shipped a
+ *      validated mechanism ahead of its live wiring.
+ *
+ * All functions here are pure and unit-testable (no network, no filesystem).
+ * `validate*` functions return an error string (or `null` when valid) rather
+ * than throwing, mirroring `validateCategorySchema` server-side.
+ */
+/** The reserved projected category (computed live from a resource's columns).
+ *  Matches the server's `RESERVED_PROJECTED_CATEGORY`. */
+export declare const RESERVED_CATEGORY = "attrs";
+/** The REST body shape for a category-config upsert (P-A `metadata-categories`). */
+export interface MetadataCategoryConfigInput {
+    resourceType: string;
+    category: string;
+    schema: unknown;
+    readRule: string | null;
+    writeRule: string | null;
+    description: string | null;
+}
+/**
+ * Normalize a parsed `[metadataCategoryConfig]` TOML section into the REST
+ * upsert body. Server-managed fields (`schemaVersion`, `generation`) are never
+ * emitted or read here — they'd churn a round-trip.
+ */
+export declare function parseMetadataCategoryToml(tomlData: any): MetadataCategoryConfigInput;
+/**
+ * Validate a parsed category config (post-{@link parseMetadataCategoryToml}).
+ * Returns an error string, or `null` when valid. The server re-validates on
+ * write; this is the fast local check so `sync push` fails with a clear
+ * message before hitting the network.
+ */
+export declare function validateMetadataCategoryConfig(input: MetadataCategoryConfigInput): string | null;
+/**
+ * Validate the `schema` block is a well-formed js-bao `FieldOptions` map:
+ * `{ fields: { <name>: { type, required?, maxLength?, maxCount?, enum? } } }`.
+ * Mirrors the server's `validateCategorySchema`.
+ */
+export declare function validateCategorySchema(schema: unknown): string | null;
+/**
+ * Serialize a category config (as returned by the P-A REST API — `schema` is a
+ * parsed object) to byte-stable TOML. Only the authored fields are emitted;
+ * server-managed `schemaVersion` / `generation` / `appId` / `categoryKey` are
+ * dropped so a pull → push → pull cycle is a no-op.
+ *
+ * Scalars are inserted before `schema` so `@iarna/toml` emits them ahead of
+ * the nested `[metadataCategoryConfig.schema.fields.*]` tables.
+ */
+export declare function serializeMetadataCategoryConfig(config: any): string;
+export interface DeclaredAccessManifest {
+    self?: {
+        categories: string[];
+    };
+    paths?: Record<string, {
+        from?: string;
+        rootFrom?: string;
+        via?: string;
+        type?: string;
+        categories: string[];
+    }>;
+    secrets?: string[];
+}
+/**
+ * Read the declared-access manifest out of a parsed config TOML: the top-level
+ * `[metadata]` table (self + paths) and the `secrets` array. Returns `null`
+ * when neither is present (the config declares no metadata/secrets access).
+ */
+export declare function parseDeclaredAccessManifestToml(tomlData: any): DeclaredAccessManifest | null;
+/**
+ * Validate a declared-access manifest structurally. Returns an error string,
+ * or `null` when valid. This is the local surface-level check (identifier
+ * names, key shape, exactly-one-root per path); the server's
+ * `validatePathGraph` still does the deep graph validation (cycles, depth,
+ * schema-mismatch) at persist time.
+ */
+export declare function validateDeclaredAccessManifest(manifest: DeclaredAccessManifest | null | undefined): string | null;
+/**
+ * Serialize a declared-access manifest into the TOML fragment object that
+ * merges into an owning config's TOML data (the caller spreads the returned
+ * keys alongside the config's own section). Returns `{}` when empty so a
+ * config with no declared access emits nothing (byte-stable).
+ */
+export declare function serializeDeclaredAccessManifest(manifest: DeclaredAccessManifest | null | undefined): {
+    metadata?: any;
+    secrets?: string[];
+};

package/dist/src/lib/toml-metadata-config.js

@@ -0,0 +1,371 @@
+/**
+ * CLI TOML parser / validator / serializer for resource-metadata config
+ * surfaces (issue #1304, P-B — CLI/TOML config-sync).
+ *
+ * Two surfaces, mirroring the "config change ships all three surfaces" rule
+ * (CLAUDE.md; same shape as the database type-config helpers in
+ * `toml-database-config.ts`):
+ *
+ *   1. `MetadataCategoryConfig` blocks — a per-`{resourceType, category}`
+ *      typed-schema + read/write-rule definition. These round-trip through
+ *      `primitive sync push` / `pull` against the P-A REST API
+ *      (`metadata-categories` CRUD). One file = one category, using a single
+ *      `[metadataCategoryConfig]` section so the nested `schema.fields.*`
+ *      tables serialize cleanly and byte-stably.
+ *
+ *   2. The declared-access manifest (`[metadata]` + `secrets` blocks) that
+ *      lives on the owning config surfaces (`CollectionTypeConfig` /
+ *      `DatabaseTypeConfig` / `WorkflowDefinition`). This module provides the
+ *      TOML *structure* + *validator* + byte-stable round-trip helpers for the
+ *      manifest so a bad value is rejected with a clear error. Wiring the
+ *      manifest onto those config models' sync push/pull (which needs a
+ *      storage field on each model) is P-C's "persist the manifest on owning
+ *      configs" work — this module ships the parse/validate/serialize the
+ *      P-C eval-site folding will call, matching how earlier phases shipped a
+ *      validated mechanism ahead of its live wiring.
+ *
+ * All functions here are pure and unit-testable (no network, no filesystem).
+ * `validate*` functions return an error string (or `null` when valid) rather
+ * than throwing, mirroring `validateCategorySchema` server-side.
+ */
+import * as TOML from "@iarna/toml";
+/** Identifier-safe name: letters, digits, underscore; not starting with a digit.
+ *  Matches the server's `METADATA_KEY_PATTERN`. */
+const IDENTIFIER_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/;
+/** The reserved projected category (computed live from a resource's columns).
+ *  Matches the server's `RESERVED_PROJECTED_CATEGORY`. */
+export const RESERVED_CATEGORY = "attrs";
+/** The subset of js-bao `FieldOptions` field types the metadata schema accepts.
+ *  Matches the server's `MetadataFieldType`. */
+const METADATA_FIELD_TYPES = new Set([
+    "string",
+    "number",
+    "boolean",
+    "date",
+    "id",
+    "stringset",
+]);
+const CATEGORY_SECTION_KEYS = new Set([
+    "resourceType",
+    "category",
+    "schema",
+    "readRule",
+    "writeRule",
+    "description",
+]);
+/**
+ * Normalize a parsed `[metadataCategoryConfig]` TOML section into the REST
+ * upsert body. Server-managed fields (`schemaVersion`, `generation`) are never
+ * emitted or read here — they'd churn a round-trip.
+ */
+export function parseMetadataCategoryToml(tomlData) {
+    const section = (tomlData && tomlData.metadataCategoryConfig) || {};
+    return {
+        resourceType: section.resourceType,
+        category: section.category,
+        schema: section.schema,
+        readRule: section.readRule ?? null,
+        writeRule: section.writeRule ?? null,
+        description: section.description ?? null,
+    };
+}
+/**
+ * Validate a parsed category config (post-{@link parseMetadataCategoryToml}).
+ * Returns an error string, or `null` when valid. The server re-validates on
+ * write; this is the fast local check so `sync push` fails with a clear
+ * message before hitting the network.
+ */
+export function validateMetadataCategoryConfig(input) {
+    if (!input.resourceType || typeof input.resourceType !== "string") {
+        return "metadataCategoryConfig.resourceType is required and must be a string";
+    }
+    if (!IDENTIFIER_PATTERN.test(input.resourceType)) {
+        return `metadataCategoryConfig.resourceType "${input.resourceType}" must be identifier-safe (letters, digits, underscore; not starting with a digit)`;
+    }
+    if (!input.category || typeof input.category !== "string") {
+        return "metadataCategoryConfig.category is required and must be a string";
+    }
+    if (!IDENTIFIER_PATTERN.test(input.category)) {
+        return `metadataCategoryConfig.category "${input.category}" must be identifier-safe (letters, digits, underscore; not starting with a digit)`;
+    }
+    if (input.category === RESERVED_CATEGORY) {
+        return `metadataCategoryConfig.category "${RESERVED_CATEGORY}" is reserved (a projected category computed from the resource's own columns) and cannot be defined`;
+    }
+    if (input.readRule !== null &&
+        input.readRule !== undefined &&
+        typeof input.readRule !== "string") {
+        return "metadataCategoryConfig.readRule must be a string (a CEL expression)";
+    }
+    if (input.writeRule !== null &&
+        input.writeRule !== undefined &&
+        typeof input.writeRule !== "string") {
+        return "metadataCategoryConfig.writeRule must be a string (a CEL expression)";
+    }
+    if (input.description !== null &&
+        input.description !== undefined &&
+        typeof input.description !== "string") {
+        return "metadataCategoryConfig.description must be a string";
+    }
+    return validateCategorySchema(input.schema);
+}
+/**
+ * Validate the `schema` block is a well-formed js-bao `FieldOptions` map:
+ * `{ fields: { <name>: { type, required?, maxLength?, maxCount?, enum? } } }`.
+ * Mirrors the server's `validateCategorySchema`.
+ */
+export function validateCategorySchema(schema) {
+    if (schema === null || typeof schema !== "object" || Array.isArray(schema)) {
+        return "metadataCategoryConfig.schema must be a table with a 'fields' map";
+    }
+    const fields = schema.fields;
+    if (fields === null || typeof fields !== "object" || Array.isArray(fields)) {
+        return "metadataCategoryConfig.schema.fields must be a table";
+    }
+    // Reject unknown top-level keys under `schema` (only `fields` is meaningful).
+    for (const key of Object.keys(schema)) {
+        if (key !== "fields") {
+            return `metadataCategoryConfig.schema has an unknown key "${key}" (only "fields" is allowed)`;
+        }
+    }
+    for (const [name, def] of Object.entries(fields)) {
+        if (!IDENTIFIER_PATTERN.test(name)) {
+            return `schema field name "${name}" must be identifier-safe`;
+        }
+        if (def === null || typeof def !== "object" || Array.isArray(def)) {
+            return `schema field "${name}" must be a table with a "type"`;
+        }
+        const field = def;
+        if (typeof field.type !== "string" || !METADATA_FIELD_TYPES.has(field.type)) {
+            return `schema field "${name}" has an invalid type (allowed: ${[
+                ...METADATA_FIELD_TYPES,
+            ].join(", ")})`;
+        }
+        if (field.enum !== undefined) {
+            if (!Array.isArray(field.enum) ||
+                field.enum.some((v) => typeof v !== "string")) {
+                return `schema field "${name}" enum must be an array of strings`;
+            }
+            if (field.type !== "string") {
+                return `schema field "${name}" enum is only valid on a "string" field`;
+            }
+        }
+        if (field.maxLength !== undefined && typeof field.maxLength !== "number") {
+            return `schema field "${name}" maxLength must be a number`;
+        }
+        if (field.maxCount !== undefined && typeof field.maxCount !== "number") {
+            return `schema field "${name}" maxCount must be a number`;
+        }
+        if (field.required !== undefined && typeof field.required !== "boolean") {
+            return `schema field "${name}" required must be a boolean`;
+        }
+    }
+    return null;
+}
+/**
+ * Serialize a category config (as returned by the P-A REST API — `schema` is a
+ * parsed object) to byte-stable TOML. Only the authored fields are emitted;
+ * server-managed `schemaVersion` / `generation` / `appId` / `categoryKey` are
+ * dropped so a pull → push → pull cycle is a no-op.
+ *
+ * Scalars are inserted before `schema` so `@iarna/toml` emits them ahead of
+ * the nested `[metadataCategoryConfig.schema.fields.*]` tables.
+ */
+export function serializeMetadataCategoryConfig(config) {
+    const section = {
+        resourceType: config.resourceType,
+        category: config.category,
+    };
+    if (config.readRule !== null && config.readRule !== undefined) {
+        section.readRule = config.readRule;
+    }
+    if (config.writeRule !== null && config.writeRule !== undefined) {
+        section.writeRule = config.writeRule;
+    }
+    if (config.description !== null &&
+        config.description !== undefined &&
+        config.description !== "") {
+        section.description = config.description;
+    }
+    // `schema` may arrive as a parsed object (REST) or a JSON string (defensive).
+    let schema = config.schema;
+    if (typeof schema === "string") {
+        try {
+            schema = JSON.parse(schema);
+        }
+        catch {
+            schema = { fields: {} };
+        }
+    }
+    section.schema = schema ?? { fields: {} };
+    return TOML.stringify({ metadataCategoryConfig: section });
+}
+// --- Declared-access manifest (`[metadata]` + `secrets`) -------------------
+//
+// The manifest that lives on an owning config surface. Shape mirrors the
+// server's `MetadataDeclaration` (`src/app-api/helpers/metadata-cel-access.ts`):
+//   metadata.self.categories = ["profile"]
+//   [metadata.paths.<name>]  from|rootFrom, via, type, categories
+//   secrets = ["STRIPE_KEY"]
+/** Root contexts a `rootFrom` path may start at (subjectless contexts). */
+const ROOT_CONTEXT_PREFIXES = ["input", "record", "params"];
+const MANIFEST_KEYS = new Set(["self", "paths", "secrets"]);
+const SELF_KEYS = new Set(["categories"]);
+const PATH_KEYS = new Set(["from", "rootFrom", "via", "type", "categories"]);
+/**
+ * Read the declared-access manifest out of a parsed config TOML: the top-level
+ * `[metadata]` table (self + paths) and the `secrets` array. Returns `null`
+ * when neither is present (the config declares no metadata/secrets access).
+ */
+export function parseDeclaredAccessManifestToml(tomlData) {
+    const metadata = tomlData?.metadata;
+    const secrets = tomlData?.secrets;
+    if (metadata === undefined && secrets === undefined)
+        return null;
+    const manifest = {};
+    if (metadata && typeof metadata === "object") {
+        if (metadata.self !== undefined) {
+            manifest.self = { categories: metadata.self?.categories };
+        }
+        if (metadata.paths !== undefined) {
+            manifest.paths = metadata.paths;
+        }
+    }
+    if (secrets !== undefined) {
+        manifest.secrets = secrets;
+    }
+    return manifest;
+}
+/**
+ * Validate a declared-access manifest structurally. Returns an error string,
+ * or `null` when valid. This is the local surface-level check (identifier
+ * names, key shape, exactly-one-root per path); the server's
+ * `validatePathGraph` still does the deep graph validation (cycles, depth,
+ * schema-mismatch) at persist time.
+ */
+export function validateDeclaredAccessManifest(manifest) {
+    if (manifest === null || manifest === undefined)
+        return null;
+    if (typeof manifest !== "object" || Array.isArray(manifest)) {
+        return "declared-access manifest must be a table";
+    }
+    // `self`
+    if (manifest.self !== undefined) {
+        const self = manifest.self;
+        if (self === null || typeof self !== "object" || Array.isArray(self)) {
+            return "metadata.self must be a table with a 'categories' array";
+        }
+        for (const key of Object.keys(self)) {
+            if (!SELF_KEYS.has(key)) {
+                return `metadata.self has an unknown key "${key}" (only "categories" is allowed)`;
+            }
+        }
+        const catError = validateCategoryList(self.categories, "metadata.self");
+        if (catError)
+            return catError;
+    }
+    // `paths`
+    if (manifest.paths !== undefined) {
+        const paths = manifest.paths;
+        if (paths === null || typeof paths !== "object" || Array.isArray(paths)) {
+            return "metadata.paths must be a table of named path declarations";
+        }
+        const declaredNodes = new Set(["self", ...Object.keys(paths)]);
+        for (const [name, raw] of Object.entries(paths)) {
+            if (!IDENTIFIER_PATTERN.test(name)) {
+                return `metadata.paths."${name}" name must be identifier-safe`;
+            }
+            if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+                return `metadata.paths."${name}" must be a table`;
+            }
+            const p = raw;
+            for (const key of Object.keys(p)) {
+                if (!PATH_KEYS.has(key)) {
+                    return `metadata.paths."${name}" has an unknown key "${key}" (allowed: ${[
+                        ...PATH_KEYS,
+                    ].join(", ")})`;
+                }
+            }
+            const hasFrom = typeof p.from === "string" && p.from !== "";
+            const hasRoot = typeof p.rootFrom === "string" && p.rootFrom !== "";
+            if (hasFrom === hasRoot) {
+                return `metadata.paths."${name}" must declare exactly one of "from" or "rootFrom"`;
+            }
+            if (hasFrom) {
+                if (!declaredNodes.has(p.from)) {
+                    return `metadata.paths."${name}" from "${p.from}" references an undeclared node (must be "self" or another declared path)`;
+                }
+                if (typeof p.via !== "string" || !p.via.includes(".")) {
+                    return `metadata.paths."${name}" must declare a "via" of the form "<category>.<key>"`;
+                }
+            }
+            else {
+                // rootFrom: a static context path (`input.*` / `record.*` / `params.*`).
+                const rootFrom = p.rootFrom;
+                const prefix = rootFrom.split(".")[0];
+                if (!ROOT_CONTEXT_PREFIXES.includes(prefix)) {
+                    return `metadata.paths."${name}" rootFrom "${rootFrom}" must be a static context path (${ROOT_CONTEXT_PREFIXES.join(".")}.*)`;
+                }
+                if (p.via !== undefined) {
+                    return `metadata.paths."${name}" roots at "${rootFrom}" and must not also declare "via"`;
+                }
+            }
+            if (typeof p.type !== "string" || p.type === "") {
+                return `metadata.paths."${name}" must declare a target "type" (the resource type)`;
+            }
+            const catError = validateCategoryList(p.categories, `metadata.paths."${name}"`);
+            if (catError)
+                return catError;
+        }
+    }
+    // `secrets`
+    if (manifest.secrets !== undefined) {
+        if (!Array.isArray(manifest.secrets) ||
+            manifest.secrets.some((s) => typeof s !== "string")) {
+            return "secrets must be an array of secret key names (strings)";
+        }
+        for (const key of manifest.secrets) {
+            if (!IDENTIFIER_PATTERN.test(key)) {
+                return `secrets key "${key}" must be identifier-safe`;
+            }
+        }
+    }
+    return null;
+}
+function validateCategoryList(categories, where) {
+    if (!Array.isArray(categories) ||
+        categories.some((c) => typeof c !== "string")) {
+        return `${where}.categories must be an array of category names (strings)`;
+    }
+    for (const cat of categories) {
+        if (cat !== RESERVED_CATEGORY && !IDENTIFIER_PATTERN.test(cat)) {
+            return `${where}.categories entry "${cat}" must be identifier-safe`;
+        }
+    }
+    return null;
+}
+/**
+ * Serialize a declared-access manifest into the TOML fragment object that
+ * merges into an owning config's TOML data (the caller spreads the returned
+ * keys alongside the config's own section). Returns `{}` when empty so a
+ * config with no declared access emits nothing (byte-stable).
+ */
+export function serializeDeclaredAccessManifest(manifest) {
+    if (!manifest)
+        return {};
+    const out = {};
+    const metadata = {};
+    if (manifest.self && Array.isArray(manifest.self.categories)) {
+        metadata.self = { categories: manifest.self.categories };
+    }
+    if (manifest.paths && Object.keys(manifest.paths).length > 0) {
+        metadata.paths = manifest.paths;
+    }
+    if (Object.keys(metadata).length > 0) {
+        out.metadata = metadata;
+    }
+    if (Array.isArray(manifest.secrets) && manifest.secrets.length > 0) {
+        out.secrets = manifest.secrets;
+    }
+    return out;
+}
+//# sourceMappingURL=toml-metadata-config.js.map

package/dist/src/lib/toml-metadata-config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toml-metadata-config.js","sourceRoot":"","sources":["../../../src/lib/toml-metadata-config.ts"],"names":[],"mappings":"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"}

package/dist/src/lib/toml-params-validator.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Validator: every `$params.X` reference inside an operation's
+ * `definition` must correspond to a declared param in
+ * `[[operations.params]]` (or the legacy JSON-string params object).
+ *
+ * Background (issue #752): a typo like `$params.proectId` used to
+ * silently no-op at runtime. With native TOML, we can catch these at
+ * `sync push` time with the file path and line number of the
+ * operation block where the bad reference appears.
+ *
+ * Design notes:
+ *   - Line attribution is per-operation, not per-reference. We don't
+ *     parse `definition` line-by-line; we just locate the
+ *     `[[operations]]` header for the named op in the raw source and
+ *     report that line. This is the load-bearing UX (jump to the
+ *     offending op block); pinpointing the exact `$params.X` reference
+ *     inside a sub-table would require swapping the TOML parser, which
+ *     the issue explicitly leaves to implementer judgement.
+ *   - We intentionally diverge from the server-side `collectParamRefs`
+ *     in `database-type-operations-controller.ts:1163`. The server pushes
+ *     the full path (e.g. `"X.Y"` for `$params.X.Y`); the CLI extracts
+ *     only the first segment (`"X"`). Net effect: the CLI validator is
+ *     more lenient than the server — `$params.X.Y` passes the CLI check
+ *     when `X` alone is declared in `[[operations.params]]`, even though
+ *     the server treats the full path as the lookup key. The server
+ *     remains authoritative; the CLI's first-segment extraction is a
+ *     pragmatic choice so authors can declare structured params (e.g.
+ *     `config: { type: "object" }`) and reference sub-fields like
+ *     `$params.config.subKey` without listing every sub-field
+ *     individually (review feedback r3246635661).
+ */
+export interface ValidationIssue {
+    file: string;
+    line: number;
+    op: string;
+    message: string;
+}
+export interface ValidationResult {
+    errors: ValidationIssue[];
+    warnings: ValidationIssue[];
+}
+/**
+ * Walk an arbitrary JSON-ish value and collect `$params.X` references
+ * found in string-valued leaves, returning only the first dotted segment
+ * (`"X"` for `$params.X.Y`). Intentionally more lenient than the
+ * server-side helper, which pushes the full path — see the module
+ * doc-comment for the rationale.
+ */
+export declare function collectParamRefs(value: any): string[];
+/**
+ * Collect bare `params.X` references from a CEL string (issue #1239).
+ *
+ * Access rules reference operation params with the bare `params.X` form (no
+ * `$` prefix), unlike `definition`, which uses `$params.X` (scanned by
+ * {@link collectParamRefs}). This helper feeds the operation's `access` CEL
+ * and each per-param `access` CEL into the "referenced" set so a param used
+ * only by an access rule is not wrongly flagged "declared but not referenced".
+ *
+ * Supported forms, all whitespace-tolerant:
+ *   - dot notation:     `params.claimedUserId`, `params . claimedUserId`
+ *   - dot path:         `params.config.subField` → first segment `config`
+ *   - bracket notation: `params["claimedUserId"]`, `params['claimedUserId']`
+ *
+ * Word-boundary guard: a `params` preceded by an identifier char, `$`, or `.`
+ * is NOT a match, so `$params.x` (definition syntax), `myparams.x`, and a
+ * dotted member access like `database.metadata.params.userId` are ignored —
+ * `params` only counts as the params root when it's a standalone root
+ * identifier. To avoid counting a `params.` that merely appears inside a quoted
+ * string literal (e.g. `note == "see params.docs"`), bracket keys are scanned
+ * first (they legitimately contain quotes), then string literals are stripped
+ * before the dot-notation scan.
+ *
+ * Purely additive: this only grows the referenced set, loosening the soft
+ * warning. The blocking `$params` error path is untouched.
+ */
+export declare function collectCelParamRefs(cel: any): string[];
+/**
+ * Normalize a `params` value (object, array, or JSON string) into the
+ * set of declared param names.
+ */
+export declare function declaredParamNames(params: any): Set<string>;
+/**
+ * Find the 1-indexed line number in `rawToml` where the `[[operations]]`
+ * block declaring `opName` starts. Returns 0 if not found.
+ *
+ * Implementation: walk in source order, track the most recent
+ * `[[operations]]` header, and when we see a `name = "<opName>"` line
+ * before the next `[[operations]]` or top-level header, return that
+ * header's line.
+ */
+export declare function locateOperationLine(rawToml: string, opName: string): number;
+export interface ValidateOptions {
+    filePath: string;
+    rawToml: string;
+    /**
+     * Operations as parsed for the wire (definition/params already in JS
+     * object form). The validator works against the parsed shape so it's
+     * indifferent to native vs JSON-string source.
+     */
+    operations: Array<{
+        name: string;
+        definition: any;
+        params?: any;
+        /**
+         * The operation-level `access` CEL rule, if any (issue #1239). Params
+         * referenced here via bare `params.X` count as "referenced" so they are
+         * not wrongly flagged "declared but not referenced". May be null/absent
+         * when the operation inherits the type's `defaultAccess`.
+         */
+        access?: any;
+    }>;
+}
+/**
+ * Validate `$params` references across every operation in a parsed
+ * database-type config.
+ *
+ * Errors (blocking):
+ *   - A `$params.X` reference inside `definition` where `X` is not
+ *     declared in `[[operations.params]]`.
+ *
+ * Warnings (soft, not blocking):
+ *   - A param declared in `[[operations.params]]` that is not referenced
+ *     anywhere in `definition`. Authors may be staging a deprecation.
+ */
+export declare function validateOperations(opts: ValidateOptions): ValidationResult;
+/**
+ * Format a validation issue as `<file>:<line>: <message>`.
+ */
+export declare function formatIssue(issue: ValidationIssue): string;