@mulmoclaude/core 1.0.1 → 1.2.0

package/dist/collection/core/schemaRules.d.ts

@@ -0,0 +1,167 @@
+import { CollectionSchemaInput } from './schemaZ';
+type Schema = CollectionSchemaInput;
+/** Exactly one storage declaration: native records need `dataPath`, an external
+ *  data file needs `dataSource`, an alternative backend needs `storage`. Zero
+ *  (nowhere to read) and several (ambiguous which wins) are equally
+ *  meaningless — fail loudly at load instead of picking silently. */
+export declare function declaresExactlyOneStore(schema: Schema): boolean;
+/** A `dataSource` collection is read-only by definition, so schema-level write
+ *  machinery can never fire: `singleton` pins CREATES, `ingest` REFILLS
+ *  records, `spawn` WRITES successor records. Rejecting them at validation
+ *  kills whole classes of writes before any runtime guard. */
+export declare function dataSourceDeclaresNoWriteMachinery(schema: Schema): boolean;
+/** Same rule for declarative host writes: a mutate action writes the record
+ *  it's invoked on, which a read-only collection has no business doing. */
+export declare function dataSourceDeclaresNoMutateAction(schema: Schema): boolean;
+/** Action ids must be unique so the dispatch route resolves unambiguously. */
+export declare function actionIdsAreUnique(schema: Schema): boolean;
+/** Collection-level action ids must likewise be unique. */
+export declare function collectionActionIdsAreUnique(schema: Schema): boolean;
+/** A mutate action's `set` writes real STORED fields: a typo'd key would write
+ *  a stray value forever, a computed/projected field is never persisted, and
+ *  the primaryKey is the filename (renaming is not a mutation). */
+export declare function mutateSetKeysNameStoredFields(schema: Schema): boolean;
+/** Every `$params.<name>` reference in `set` must name a declared param — an
+ *  undeclared one would silently no-op the assignment. */
+export declare function mutateParamRefsAreDeclared(schema: Schema): boolean;
+/** A collection-level action has no record to write. */
+export declare function collectionActionsAreNotMutate(schema: Schema): boolean;
+/** The singleton value becomes a record id (and thus a `<id>.json` filename),
+ *  so it must satisfy the SAME record-id rule the write path enforces —
+ *  otherwise the create form would lock the primary key to a value the POST
+ *  route then rejects, making the collection impossible to initialize. */
+export declare function singletonIsAValidRecordId(schema: Schema): boolean;
+/** A `currencyField` pointer must name a real top-level field that holds a code
+ *  string — a typo (`curreny`) would otherwise pass the per-field check, then
+ *  silently fall back to the literal / USD at render and mislabel amounts. */
+export declare function currencyFieldRefsNameCodeFields(schema: Schema): boolean;
+/** The pair must be declared together — one without the other is meaningless:
+ *  the host would either never fire (no done values to compare against) or
+ *  never clear (no field to read).
+ *
+ *  EXCEPTION: when `completionField` names a `flag` field, done ⇔ the flag's
+ *  `where` matches, so `completionDoneValues` carries no information and MUST
+ *  be omitted (declaring it would invite a contradictory second source of
+ *  truth). */
+export declare function completionPairIsCoherent(schema: Schema): boolean;
+/** `completionField` must name a real top-level field — a typo would silently
+ *  disable the notification mechanism otherwise. */
+export declare function completionFieldIsDeclared(schema: Schema): boolean;
+/** A flag named by `completionField` is evaluated against the RAW record — the
+ *  reconciler (and spawn's fallback) read items straight off disk, BEFORE any
+ *  `deriveAll` enrichment — so its `where` may only reference STORED fields. A
+ *  condition over a computed sibling would see an absent key: `ne` matches
+ *  vacuously, every other op reads false, and the bell would clear wrongly /
+ *  never. General (non-completion) flags keep the full vocabulary — the UI
+ *  evaluates them post-enrichment. */
+export declare function completionFlagReadsOnlyStoredFields(schema: Schema): boolean;
+/** `displayField`, like `completionField`, must name a real top-level field —
+ *  a typo would silently fall back to the primaryKey forever. */
+export declare function displayFieldIsDeclared(schema: Schema): boolean;
+/** A field's `when.field` gates its visibility against a sibling's value, so it
+ *  must name a real top-level field — a typo would silently keep the field
+ *  hidden forever (the gate never matches). */
+export declare function fieldVisibilityGatesNameDeclaredFields(schema: Schema): boolean;
+/** A flag's `where` reads sibling fields (both `cond.field` and a same-record
+ *  `valueFrom.field`), so each must name a real top-level field — a typo would
+ *  silently pin the flag false forever (`ne`: true forever). */
+export declare function flagConditionsNameDeclaredFields(schema: Schema): boolean;
+/** An `embed`'s `idField` resolves the target record id from a sibling's value,
+ *  so it must name a real top-level field — and one whose stored value is a
+ *  plain id string. Only `ref` / `string` qualify: the editor writes the picked
+ *  id into that field, so a non-persisted or composite type would either not
+ *  round-trip on save or hold no usable id. */
+export declare function embedIdFieldsNameIdBearingFields(schema: Schema): boolean;
+/** The sync writes each mapped value into a declared field, and puts the Google
+ *  event id in the primary field — so a map key that names no field (or names
+ *  the primary) would silently drop data or fight the id. */
+export declare function googleCalendarMapNamesStoredFields(schema: Schema): boolean;
+/** A `toggle` field projects an `enum` field: its `field` must name a real
+ *  top-level enum, and `onValue` / `offValue` must be members of that enum's
+ *  `values` — otherwise toggling would write a value outside the closed set
+ *  (and never appear "checked"). */
+export declare function togglesProjectValidEnums(schema: Schema): boolean;
+/** `triggerField` requires the completion pair: the time gate only suppresses
+ *  the *completion* bell until the date, and the bell still clears via
+ *  `completionDoneValues`. Without completion there is no bell to gate. */
+export declare function triggerFieldRequiresCompletion(schema: Schema): boolean;
+/** `triggerField` must name a real `date` field — the gate parses its value as
+ *  `YYYY-MM-DD`; any other type can't be compared to the clock. */
+export declare function triggerFieldIsADateField(schema: Schema): boolean;
+/** `triggerLeadDays` only means something relative to a trigger date. */
+export declare function triggerLeadDaysRequiresTriggerField(schema: Schema): boolean;
+/** `spawn` advances `triggerField` to compute the successor's trigger date, so
+ *  the schema must declare one. */
+export declare function spawnRequiresTriggerField(schema: Schema): boolean;
+/** `spawn.when.field` must name a real top-level field — a typo would silently
+ *  never match. */
+export declare function spawnWhenFieldIsDeclared(schema: Schema): boolean;
+/** Every `spawn.carry` entry must name a real top-level field — a typo would
+ *  silently never copy. */
+export declare function spawnCarryEntriesAreDeclared(schema: Schema): boolean;
+/** A successor must NOT be born already matching its own spawn predicate — it
+ *  would re-spawn on its first reconcile, fanning out into an unbounded chain
+ *  of records. The predicate field/values are `spawn.when` when given, else the
+ *  completion-done pair. The successor's value for that field is `set[field]`
+ *  if set, else the carried source value (which matched, by definition, when
+ *  the spawn fired) if carried, else absent (safe). */
+export declare function spawnSuccessorStartsInert(schema: Schema): boolean;
+/** `spawnSuccessorStartsInert` cannot see through a flag's `where` (the
+ *  predicate would need full record evaluation against `set`/`carry`). So a
+ *  schema whose completion is flag-form may only spawn with an explicit
+ *  `spawn.when` — which that check CAN evaluate. */
+export declare function flagCompletionSpawnDeclaresWhen(schema: Schema): boolean;
+/** §4.1 — `fromField` must name a real top-level `enum` field. The `map` keys
+ *  are only meaningful against a closed value set, and the field renders as a
+ *  form `<select>`; a non-enum target has no finite values to validate. */
+export declare function fieldDrivenFromFieldIsEnum(schema: Schema): boolean;
+/** §4.2 — `map` keys must EXACTLY cover the enum's `values` (no missing keys —
+ *  a record could pick an unmapped frequency and silently stall; no extra keys
+ *  — a stale map outliving an enum edit). */
+export declare function fieldDrivenMapCoversValues(schema: Schema): boolean;
+/** §4.5 — `fromField` must reach the successor (via `carry` or `set`);
+ *  otherwise the successor loses its frequency and the NEXT spawn along the
+ *  chain can't resolve an interval, silently halting the recurrence.
+ *
+ *  `set` writes a FIXED value, so it must itself be a key of `map` (else the
+ *  successor is born with an unresolvable driver and `resolveEvery` skips it —
+ *  the exact silent-halt §4.5 exists to prevent). `carry` copies the source's
+ *  own value, which — for a record that matched the spawn — is one of the
+ *  enum's values, all of which `map` covers by §4.2; so a carried driver is
+ *  always resolvable and needs no value check here. */
+export declare function fieldDrivenFromFieldCarried(schema: Schema): boolean;
+/** `calendarField` must name a real `date`/`datetime` field — the calendar view
+ *  parses its value to place records on the month grid (a `datetime` anchor
+ *  also carries the clock for the day view). */
+export declare function calendarFieldIsDateLike(schema: Schema): boolean;
+/** `calendarEndField` marks the end of a multi-day span, so it only means
+ *  something alongside a start anchor. */
+export declare function calendarEndFieldRequiresCalendarField(schema: Schema): boolean;
+/** `calendarEndField` must also name a real `date`/`datetime` field — same parse. */
+export declare function calendarEndFieldIsDateLike(schema: Schema): boolean;
+/** `calendarTimeField` places records on the day view, so it only means
+ *  something alongside a start anchor. */
+export declare function calendarTimeFieldRequiresCalendarField(schema: Schema): boolean;
+/** `calendarTimeField` must name a real top-level field (a free-form time
+ *  string the day view parses). */
+export declare function calendarTimeFieldIsDeclared(schema: Schema): boolean;
+/** …and that field must be string-backed — the day view parses its value as a
+ *  time string, so a number/enum/date column can't drive it. */
+export declare function calendarTimeFieldIsStringBacked(schema: Schema): boolean;
+/** `kanbanField` must name a real `enum` field — the board groups records into
+ *  one column per declared enum value; any other type has no closed set of
+ *  columns to group by. */
+export declare function kanbanFieldIsAnEnum(schema: Schema): boolean;
+/** `notifyWhen` narrows the completion bell, so it only means something with
+ *  completion tracking. */
+export declare function notifyWhenRequiresCompletion(schema: Schema): boolean;
+/** `notifyWhen.field` must name a real top-level field. */
+export declare function notifyWhenFieldIsDeclared(schema: Schema): boolean;
+/** Every custom view `id` must be a valid slug — it doubles as the view-mode
+ *  selector key (`custom:<id>`) and the capability-token clamp key, both of
+ *  which expect a path-safe token. */
+export declare function viewIdsAreSlugs(schema: Schema): boolean;
+/** Custom view ids must be unique so the selector + token clamp resolve
+ *  unambiguously. */
+export declare function viewIdsAreUnique(schema: Schema): boolean;
+export {};