primitive-admin 1.1.0-alpha.9 → 1.1.0

package/dist/src/lib/db-codegen/generated-operation-def-descriptor.js

@@ -0,0 +1,211 @@
+/**
+ * GENERATED FILE — DO NOT EDIT BY HAND.
+ *
+ * Vendored byte-for-byte from the canonical server module
+ * `src/app-api/controllers/operation-definition-descriptor.ts` — the SAME
+ * allow-lists the server validator (`validateDefinition` / `validateParams`)
+ * enforces. The client operation-definition types
+ * (`src/client/api/operationDefinition.ts`) hand-author the matching union;
+ * a key-parity test compares them against this committed copy.
+ *
+ * Regenerate with:
+ *   node cli/scripts/gen-operation-def-descriptor.mjs   (runs at CLI prebuild)
+ *
+ * A CI freshness guard
+ * (`cli/scripts/gen-operation-def-descriptor.mjs --check`, also asserted by
+ * `cli/tests/unit/operation-def-descriptor-drift-guard.test.ts`) fails if
+ * this committed copy does not match the source — see issue #1544 / #1442.
+ */
+/**
+ * Canonical, dependency-free descriptor of the database operation-definition
+ * schema (issue #1544).
+ *
+ * The server validator (`validateDefinition` / `validateParams` in
+ * `database-type-operations-controller.ts`) and the CLIENT operation-definition
+ * types (`src/client/api/operationDefinition.ts`, consumed by
+ * `createOperation` / `updateOperation` / `DatabaseOperationInfo`) must agree on
+ * the set of operation types and the allowed keys for each definition shape —
+ * otherwise a hand-authored `OperationDefinition` member promises a key the
+ * runtime rejects (or omits one the runtime accepts).
+ *
+ * This module is the single source of that declarative contract: the op-type
+ * list, the per-type allowed definition-key sets, the per-type mutation/action
+ * op-name enums, and the param-schema key/type enums. The validator imports
+ * these constants directly (so a change here changes what the server enforces),
+ * and the CLI vendors a byte-for-byte copy as a committed artifact via
+ * `cli/scripts/gen-operation-def-descriptor.mjs` (the #1442 workflow
+ * schema-descriptor pattern). A drift-guard test runs that generator in
+ * `--check` mode, and a key-parity test asserts the hand-authored client type
+ * members' keys equal the corresponding allow-lists here — so the validator and
+ * the client types can never silently diverge. The CLI never imports server
+ * `src/` at runtime; only the build-time generator reads this file.
+ *
+ * The value-shape checks that are NOT purely declarative (requiredness, nested
+ * object structure, CEL parsing) stay imperative in the validator. This
+ * descriptor captures the declarative allow-lists — the part that is genuinely
+ * shared between the runtime boundary and the descriptive client types.
+ *
+ * Ordering is significant: the validator joins these arrays into its 400-level
+ * error messages (`Must be one of: ${X.join(", ")}`), so reordering an array
+ * changes an error string. Keep entries in their current order.
+ */
+/** The operation `type` values accepted by `createOperation` / `updateOperation`. */
+export const OPERATION_TYPES = [
+    "query",
+    "mutation",
+    "count",
+    "aggregate",
+    "pipeline",
+    "applyToQuery",
+];
+// ── Per-type definition key allow-lists ──
+/** Allowed top-level keys in a `query` definition. `cache` (#1247) is query-only. */
+export const QUERY_DEF_KEYS = [
+    "filter",
+    "sort",
+    "limit",
+    "projection",
+    "include",
+    "cache",
+];
+/** Allowed top-level keys in a `mutation` definition. */
+export const MUTATION_DEF_KEYS = ["operations"];
+/** Allowed top-level keys in a `count` definition. */
+export const COUNT_DEF_KEYS = ["filter"];
+/** Allowed top-level keys in an `aggregate` definition. */
+export const AGGREGATE_DEF_KEYS = [
+    "groupBy",
+    "operations",
+    "filter",
+    "limit",
+    "sort",
+];
+/** Allowed top-level keys in a `pipeline` definition. */
+export const PIPELINE_DEF_KEYS = ["steps", "return"];
+/** Allowed top-level keys in an `applyToQuery` definition. */
+export const APPLY_TO_QUERY_DEF_KEYS = ["source", "action"];
+// ── Op-name enums nested inside definitions ──
+/** Mutation op names allowed in a `mutation` definition's `operations[]`. */
+export const MUTATION_OPS = [
+    "save",
+    "patch",
+    "delete",
+    "increment",
+    "addToSet",
+    "removeFromSet",
+];
+/**
+ * Aggregate op `type` names allowed in an `aggregate` definition's
+ * `operations[]`.
+ */
+export const AGGREGATE_OP_TYPES = [
+    "count",
+    "sum",
+    "avg",
+    "min",
+    "max",
+];
+/**
+ * Allowed keys on a single nested aggregate op (an entry in an `aggregate`
+ * definition's `operations[]`, and in a pipeline `aggregate` step's
+ * `operations[]`). Only `type` and `field` are honored by the runtime — the
+ * aggregate SELECT always aliases columns to the fixed output names
+ * (`count` / `<type>_<field>`), so there is no supported way to rename an
+ * output. `outputField` was historically accepted here but read by no code
+ * (issue #1767); any key outside this list is now rejected at registration so
+ * dead config can't be silently stored.
+ */
+export const AGGREGATE_OP_KEYS = ["type", "field"];
+/**
+ * `applyToQuery` action ops. Only mutation ops that operate on existing matched
+ * records — `save` is excluded because it makes no sense in a find-and-mutate
+ * flow.
+ */
+export const APPLY_TO_QUERY_ACTIONS = [
+    "delete",
+    "patch",
+    "increment",
+    "addToSet",
+    "removeFromSet",
+];
+/** Allowed keys in an `applyToQuery` `source` block. */
+export const APPLY_TO_QUERY_SOURCE_KEYS = [
+    "filter",
+    "sort",
+    "limit",
+];
+/** Allowed keys in an `applyToQuery` `action` block. */
+export const APPLY_TO_QUERY_ACTION_KEYS = [
+    "op",
+    "data",
+    "fields",
+    "stringSets",
+];
+// ── Pipeline step allow-lists ──
+/** Step `type` values allowed inside a `pipeline` definition's `steps[]`. */
+export const PIPELINE_STEP_TYPES = [
+    "query",
+    "count",
+    "aggregate",
+];
+/** Allowed keys on a pipeline `query` step. */
+export const PIPELINE_QUERY_STEP_KEYS = [
+    "name",
+    "type",
+    "modelName",
+    "filter",
+    "sort",
+    "limit",
+    "projection",
+    "include",
+];
+/** Allowed keys on a pipeline `count` step. */
+export const PIPELINE_COUNT_STEP_KEYS = [
+    "name",
+    "type",
+    "modelName",
+    "filter",
+];
+/** Allowed keys on a pipeline `aggregate` step. */
+export const PIPELINE_AGGREGATE_STEP_KEYS = [
+    "name",
+    "type",
+    "modelName",
+    "groupBy",
+    "operations",
+    "filter",
+    "limit",
+    "sort",
+];
+// ── Param-schema enums ──
+/**
+ * Built-in param types. `integer` (#1488) is accepted here and by the runtime
+ * coercion path. `array` (#1488) declares a list param with a scalar `items`
+ * element type. Keep in step with the runtime coercion list
+ * (`MODEL_PARAM_SCALAR_TYPES` in `database-operations-controller.ts`).
+ */
+export const PARAM_TYPES = [
+    "string",
+    "number",
+    "boolean",
+    "integer",
+    "object",
+    "array",
+];
+/** Scalar element types allowed for an `array` param's `items` (#1488). */
+export const ARRAY_ELEMENT_TYPES = [
+    "string",
+    "number",
+    "boolean",
+    "integer",
+];
+/** Allowed keys in a single param definition. */
+export const PARAM_DEF_KEYS = [
+    "type",
+    "required",
+    "access",
+    "coerce",
+    "enum",
+    "items",
+];
+//# sourceMappingURL=generated-operation-def-descriptor.js.map

package/dist/src/lib/db-codegen/generated-operation-def-descriptor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generated-operation-def-descriptor.js","sourceRoot":"","sources":["../../../../src/lib/db-codegen/generated-operation-def-descriptor.ts"],"names":[],"mappings":"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"}

package/dist/src/lib/deprecation.d.ts

@@ -0,0 +1,22 @@
+import type { Command } from "commander";
+/**
+ * Print the standard runtime warning for a deprecated command. `warn` writes
+ * to stderr, so `--json` output on stdout stays parseable.
+ *
+ * @param command   the command as the user typed it, e.g. "primitive scripts list"
+ * @param successor what to use instead, e.g. "server functions (primitive functions)"
+ * @param issue     optional tracking issue number
+ */
+export declare function warnDeprecated(command: string, successor: string, issue?: number): void;
+/** The full command path, e.g. "primitive workflows runs list". */
+export declare function commandPath(cmd: Command): string;
+/**
+ * Warn on every subcommand of a deprecated command group, through a commander
+ * `preAction` hook on the group. `exempt` names subcommands (by name, direct
+ * children of `group`) that stay supported and must not warn; their own
+ * subcommands are exempt too.
+ */
+export declare function deprecateCommandGroup(group: Command, successor: string, options?: {
+    issue?: number;
+    exempt?: string[];
+}): void;

package/dist/src/lib/deprecation.js

@@ -0,0 +1,43 @@
+import { warn } from "./output.js";
+/**
+ * Print the standard runtime warning for a deprecated command. `warn` writes
+ * to stderr, so `--json` output on stdout stays parseable.
+ *
+ * @param command   the command as the user typed it, e.g. "primitive scripts list"
+ * @param successor what to use instead, e.g. "server functions (primitive functions)"
+ * @param issue     optional tracking issue number
+ */
+export function warnDeprecated(command, successor, issue) {
+    const ref = issue ? ` (#${issue})` : "";
+    warn(`\`${command}\` is deprecated${ref}; use ${successor} instead.`);
+}
+/** The full command path, e.g. "primitive workflows runs list". */
+export function commandPath(cmd) {
+    const names = [];
+    let current = cmd;
+    while (current) {
+        names.unshift(current.name());
+        current = current.parent;
+    }
+    return names.join(" ");
+}
+/**
+ * Warn on every subcommand of a deprecated command group, through a commander
+ * `preAction` hook on the group. `exempt` names subcommands (by name, direct
+ * children of `group`) that stay supported and must not warn; their own
+ * subcommands are exempt too.
+ */
+export function deprecateCommandGroup(group, successor, options = {}) {
+    const exempt = new Set(options.exempt ?? []);
+    group.hook("preAction", (_thisCommand, actionCommand) => {
+        // Walk up from the running command to the direct child of `group`.
+        let child = actionCommand;
+        while (child && child.parent && child.parent !== group) {
+            child = child.parent;
+        }
+        if (child && child.parent === group && exempt.has(child.name()))
+            return;
+        warnDeprecated(commandPath(actionCommand), successor, options.issue);
+    });
+}
+//# sourceMappingURL=deprecation.js.map

package/dist/src/lib/deprecation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"deprecation.js","sourceRoot":"","sources":["../../../src/lib/deprecation.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,IAAI,EAAE,MAAM,aAAa,CAAC;AAEnC;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAC5B,OAAe,EACf,SAAiB,EACjB,KAAc;IAEd,MAAM,GAAG,GAAG,KAAK,CAAC,CAAC,CAAC,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC;IACxC,IAAI,CAAC,KAAK,OAAO,mBAAmB,GAAG,SAAS,SAAS,WAAW,CAAC,CAAC;AACxE,CAAC;AAED,mEAAmE;AACnE,MAAM,UAAU,WAAW,CAAC,GAAY;IACtC,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,OAAO,GAAmB,GAAG,CAAC;IAClC,OAAO,OAAO,EAAE,CAAC;QACf,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;QAC9B,OAAO,GAAG,OAAO,CAAC,MAAM,CAAC;IAC3B,CAAC;IACD,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACzB,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,qBAAqB,CACnC,KAAc,EACd,SAAiB,EACjB,UAAiD,EAAE;IAEnD,MAAM,MAAM,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;IAC7C,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,YAAY,EAAE,aAAa,EAAE,EAAE;QACtD,mEAAmE;QACnE,IAAI,KAAK,GAAmB,aAAa,CAAC;QAC1C,OAAO,KAAK,IAAI,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,MAAM,KAAK,KAAK,EAAE,CAAC;YACvD,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC;QACvB,CAAC;QACD,IAAI,KAAK,IAAI,KAAK,CAAC,MAAM,KAAK,KAAK,IAAI,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;YAAE,OAAO;QACxE,cAAc,CAAC,WAAW,CAAC,aAAa,CAAC,EAAE,SAAS,EAAE,OAAO,CAAC,KAAK,CAAC,CAAC;IACvE,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/src/lib/document-export-permissions.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The `permissions.json` rows `primitive documents export` writes.
+ *
+ * Extracted from `exportSingleDocument` (#2951) so the shape change it went
+ * through is testable without a server. The export used to merge the legacy
+ * `GET /documents/:id/invitations` array — filtering `accepted` and
+ * `expiresAt` client-side — into the permission rows. That route is removed;
+ * pending entries now come from `GET /documents/:id/pending-invitations`,
+ * which returns a `{ items }` envelope of deferred grants the server has
+ * already filtered down to unresolved, unexpired, still-invited ones.
+ *
+ * The export tolerates the pending read failing (an older server answers 403
+ * or 404): the caller swallows the error and passes `null`, and the export
+ * still writes the permission rows.
+ */
+export interface ExportedPermissionRow {
+    email: string;
+    permission: string;
+    grantedAt?: string;
+    source?: "invitation";
+    status?: "pending";
+}
+/**
+ * Merge a document's permission rows and its pending deferred grants into the
+ * single email-keyed list `permissions.json` carries.
+ *
+ * @param permissionsResponse - `GET /documents/:id/permissions`, or `null` when the read failed.
+ * @param pendingResponse - `GET /documents/:id/pending-invitations`, or `null` when the read failed.
+ */
+export declare function buildPermissionsExport(permissionsResponse: unknown, pendingResponse: unknown): ExportedPermissionRow[];

package/dist/src/lib/document-export-permissions.js

@@ -0,0 +1,54 @@
+/**
+ * The `permissions.json` rows `primitive documents export` writes.
+ *
+ * Extracted from `exportSingleDocument` (#2951) so the shape change it went
+ * through is testable without a server. The export used to merge the legacy
+ * `GET /documents/:id/invitations` array — filtering `accepted` and
+ * `expiresAt` client-side — into the permission rows. That route is removed;
+ * pending entries now come from `GET /documents/:id/pending-invitations`,
+ * which returns a `{ items }` envelope of deferred grants the server has
+ * already filtered down to unresolved, unexpired, still-invited ones.
+ *
+ * The export tolerates the pending read failing (an older server answers 403
+ * or 404): the caller swallows the error and passes `null`, and the export
+ * still writes the permission rows.
+ */
+/** Unwrap a list that may arrive bare, or under `items`, or under a named key. */
+function rows(value, key) {
+    if (Array.isArray(value))
+        return value;
+    if (value && typeof value === "object") {
+        const envelope = value;
+        for (const candidate of ["items", key]) {
+            if (Array.isArray(envelope[candidate]))
+                return envelope[candidate];
+        }
+    }
+    return [];
+}
+/**
+ * Merge a document's permission rows and its pending deferred grants into the
+ * single email-keyed list `permissions.json` carries.
+ *
+ * @param permissionsResponse - `GET /documents/:id/permissions`, or `null` when the read failed.
+ * @param pendingResponse - `GET /documents/:id/pending-invitations`, or `null` when the read failed.
+ */
+export function buildPermissionsExport(permissionsResponse, pendingResponse) {
+    const granted = rows(permissionsResponse, "permissions")
+        .filter((p) => p?.email)
+        .map((p) => ({
+        email: p.email,
+        permission: p.permission,
+        grantedAt: p.grantedAt,
+    }));
+    const pending = rows(pendingResponse, "invitations")
+        .filter((i) => i?.email)
+        .map((i) => ({
+        email: i.email,
+        permission: i.permission,
+        source: "invitation",
+        status: "pending",
+    }));
+    return [...granted, ...pending];
+}
+//# sourceMappingURL=document-export-permissions.js.map

package/dist/src/lib/document-export-permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-export-permissions.js","sourceRoot":"","sources":["../../../src/lib/document-export-permissions.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAUH,kFAAkF;AAClF,SAAS,IAAI,CAAC,KAAc,EAAE,GAAW;IACvC,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC;IACvC,IAAI,KAAK,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QACvC,MAAM,QAAQ,GAAG,KAAgC,CAAC;QAClD,KAAK,MAAM,SAAS,IAAI,CAAC,OAAO,EAAE,GAAG,CAAC,EAAE,CAAC;YACvC,IAAI,KAAK,CAAC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC;gBAAE,OAAO,QAAQ,CAAC,SAAS,CAAU,CAAC;QAC9E,CAAC;IACH,CAAC;IACD,OAAO,EAAE,CAAC;AACZ,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CACpC,mBAA4B,EAC5B,eAAwB;IAExB,MAAM,OAAO,GAAG,IAAI,CAAC,mBAAmB,EAAE,aAAa,CAAC;SACrD,MAAM,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC;SAC5B,GAAG,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC;QAChB,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,SAAS,EAAE,CAAC,CAAC,SAAS;KACvB,CAAC,CAAC,CAAC;IAEN,MAAM,OAAO,GAAG,IAAI,CAAC,eAAe,EAAE,aAAa,CAAC;SACjD,MAAM,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC,EAAE,KAAK,CAAC;SAC5B,GAAG,CAAC,CAAC,CAAM,EAAE,EAAE,CAAC,CAAC;QAChB,KAAK,EAAE,CAAC,CAAC,KAAK;QACd,UAAU,EAAE,CAAC,CAAC,UAAU;QACxB,MAAM,EAAE,YAAqB;QAC7B,MAAM,EAAE,SAAkB;KAC3B,CAAC,CAAC,CAAC;IAEN,OAAO,CAAC,GAAG,OAAO,EAAE,GAAG,OAAO,CAAC,CAAC;AAClC,CAAC"}

package/dist/src/lib/document-ingest-artifact.d.ts

@@ -0,0 +1,120 @@
+/**
+ * The artifact `primitive documents ingest` uploads, built from a directory.
+ *
+ * Read the lines, check every one of them against the document's own schema,
+ * put each model's records in id order, and cut them into gzipped chunks whose
+ * descriptors match their bytes. All of it before a session exists: an ingest
+ * swaps a live document's tables, so a refusal the server would reach halfway
+ * through is a refusal this side should have reached first.
+ *
+ * Two passes over the input, not one. The first validates and decides whether
+ * a model's lines already ascend; the second builds. That is what lets an
+ * input that is already in order — every export, and most generated files —
+ * be streamed through with no temp file at any size, while an unsorted one
+ * falls back to a bounded external sort.
+ *
+ * The local check is the server's, said on this side: the rules it mirrors are
+ * `planLine`'s in `src/large-documents/ingest-pipeline.ts`, and the artifact's
+ * own rules are in `docs/large-document-ingest.md`.
+ */
+import type { DiscoveredIngestInput } from "./document-ingest-input.js";
+/** A line, a file or a plan this document's schema does not accept. */
+export declare class IngestArtifactError extends Error {
+    constructor(message: string);
+}
+/** What a model declares, as far as an ingest line is concerned. */
+export interface IngestModelSchema {
+    fields: Set<string>;
+    stringSets: Set<string>;
+}
+/** Every model the document has a declaration for. */
+export interface IngestSchema {
+    models: Map<string, IngestModelSchema>;
+}
+/**
+ * The schema as `GET documents/:id/schema` answers it.
+ *
+ * A stringset is a field whose declared `type` is `stringset`; every other
+ * declared field is a scalar. A field named `type` is an ordinary field like
+ * any other (#3501) — the word is read from the declaration's VALUE, never
+ * from a field's name.
+ */
+export declare function ingestSchemaFromIntrospection(response: any): IngestSchema;
+/** One chunk of the artifact: its descriptor, and where its bytes are. */
+export interface IngestChunkDescriptor {
+    model: string;
+    index: number;
+    rows: number;
+    bytes: number;
+    rawBytes: number;
+    sha256: string;
+    firstId: string;
+    lastId: string;
+    /** The gzipped body, on disk under the run's scratch directory. */
+    file: string;
+}
+/** What one model contributes to the plan. */
+export interface IngestModelSummary {
+    model: string;
+    rows: number;
+    chunks: number;
+    bytes: number;
+    rawBytes: number;
+    deletes: number;
+}
+/** The artifact, ready to upload. */
+export interface IngestArtifactPlan {
+    models: IngestModelSummary[];
+    chunks: IngestChunkDescriptor[];
+    rows: number;
+    bytes: number;
+    rawBytes: number;
+    deletes: number;
+    /** Temp files the external sort wrote; 0 when nothing needed sorting. */
+    sortRuns: number;
+    /** Remove every file this plan wrote. */
+    cleanup(): Promise<void>;
+}
+/** How the artifact is cut. Defaults are 75% of what a session accepts. */
+export interface BuildIngestArtifactOptions {
+    input: DiscoveredIngestInput;
+    schema: IngestSchema;
+    /** Where chunk bodies and sort runs are written. */
+    tmpDir?: string;
+    /** Cut a chunk at this many decompressed bytes. */
+    cutRawBytes?: number;
+    /** Cut a chunk at this many rows. */
+    cutRows?: number;
+    /** In-memory bound of one external-sort run. */
+    runBytes?: number;
+    maxChunkBytes?: number;
+    maxChunkRawBytes?: number;
+    maxChunkRows?: number;
+    maxChunks?: number;
+    maxTotalBytes?: number;
+}
+/** 75% of the session limits: a chunk the server will not have to refuse. */
+export declare const INGEST_CUT_RAW_BYTES: number;
+export declare const INGEST_CUT_ROWS = 40000;
+/** One external-sort run's in-memory bound. */
+export declare const INGEST_SORT_RUN_BYTES: number;
+export declare function buildIngestArtifact(options: BuildIngestArtifactOptions): Promise<IngestArtifactPlan>;
+/** One line's id and patch, whichever of the two forms it is written in. */
+export declare function parseIngestLine(where: string, text: string): {
+    id: string;
+    patch: string;
+    deleted: boolean;
+};
+/**
+ * One line, checked against the model's declaration.
+ *
+ * Every rule the server's `planLine` applies, applied here: a key the model
+ * does not declare, an array on a scalar field, a scalar on a stringset,
+ * `_deleted` beside anything else, or an `id` key that disagrees with the
+ * line's own id.
+ */
+export declare function checkIngestLine(where: string, model: string, text: string, declared: IngestModelSchema): {
+    id: string;
+    patch: string;
+    deleted: boolean;
+};