@hockeymask/core 0.1.0 → 0.1.1

package/dist/index.d.mts

@@ -206,7 +206,8 @@ export declare class SourceUnavailable extends ConnectorError {
 //#region src/mapping/result.d.ts
 /**
  * Failure as a value. Steps, nodes and the compiler return `Result` instead of throwing, so
- * the executor can apply each node's failure policy (arch.md, "Step signature").
+ * the executor can apply each node's failure policy (arch.md,
+ * "Failure policy and partial results").
  */
 export type Result<T, E> = {
   readonly ok: true;
@@ -231,7 +232,7 @@ export interface StepError {
   readonly code: ErrorCode;
   readonly detail: string;
 }
-/** A runtime failure located in the graph (arch.md `MappingError`). */
+/** A runtime failure located in the graph. */
 export interface MappingError extends StepError {
   readonly node: string;
   readonly op: string;
@@ -913,7 +914,7 @@ interface Origin {
 interface NodeOutput {
   readonly type: RecordType;
   readonly origins: Readonly<Record<string, Origin>>;
-  /** Can drop records on a failed field (limitation #20). */
+  /** Can drop records on a failed field. */
   readonly canSkip?: boolean;
 }
 /** An input slot: the param path that holds an upstream node id. */
@@ -977,7 +978,7 @@ interface SinkWrite {
    * The rows are the complete set of the target for the company (and source system, where
    * the identity has one): the host calls `synchronize_all(rows, scope)`, deleting rows not
    * written. Writes of one run go in one transaction, inserts parent-first and deletes
-   * child-first (exclusions before the lanes they reference). A sink that does not write
+   * child-first (join-table rows before the entities they reference). A sink that does not write
    * (held, stopped, failed) deletes nothing.
    */
   readonly mode?: 'replace';
@@ -1022,7 +1023,7 @@ interface RunOptions {
 interface CompiledNode {
   /** Null for a node without an output relation (`sink`); `metrics` types what it reports. */
   readonly output: NodeOutput | null;
-  /** Target entities a sink writes (one sink per entity, structural rule 3). */
+  /** Target entities a sink writes (one sink per entity, structural rule 4). */
   readonly writes?: readonly string[];
   readonly run: (inputs: Inputs, ctx: RunContext, options?: RunOptions) => Result<NodeRun, NodeFailure>;
 }
@@ -1040,7 +1041,7 @@ interface NodeDef<P = unknown> {
   readonly defaults: () => Record<string, unknown>;
   /** Parses the node object without `id`, `op` and `label`. */
   readonly params: z.ZodType<P>;
-  /** Accepts `tolerate_skips` (limitation #20). */
+  /** Accepts `tolerate_skips` (arch.md, "Failure policy and partial results"). */
   readonly toleratesSkips?: (params: P) => boolean;
   readonly compile: (params: P, env: NodeEnv) => Result<CompiledNode, readonly NodeIssue[]>;
 }
@@ -1361,7 +1362,7 @@ export declare function topologicalOrder(nodes: readonly NodeJson[]): string[];
 export declare function sourceRecordType(schema: JsonSchema): Result<RecordType, string>;
 /** A starting `expectedSchema` for a source table, from what its connector describes. */
 export declare function tableJsonSchema(table: Table, system?: string): JsonSchema;
-/** The pinned schema of an internal entity read as a source (structural rule 4). */
+/** The pinned schema of an internal entity read as a source. */
 export declare function entityJsonSchema(entity: TargetEntity): JsonSchema;
 /** Does a runtime value inhabit this type? */
 export declare function conforms(value: Val, type: MType): boolean;
@@ -1389,12 +1390,12 @@ interface OpDef<P = unknown> {
   readonly nulls: 'propagate' | 'consume';
   /**
    * What the op reads: 'value' (default) needs a piped value; 'none' starts a pipeline and
-   * takes no piped input (`()` in arch.md signatures); 'any' accepts either (`when`).
+   * takes no piped input; 'any' accepts either (`when`).
    */
   readonly input?: 'value' | 'none' | 'any';
   /** Must be the last step (`omit_if_null`). */
   readonly terminal?: boolean;
-  /** Whether this op can return an error at runtime, given its params (limitation #20). */
+  /** Whether this op can return an error at runtime, given its params. */
   readonly fallible: (params: P, env: RecordEnv, input: MType) => boolean;
   /** Output type for an input type; an error message when the input is not accepted. */
   readonly signature: (input: MType, params: P, env: RecordEnv) => Result<MType, string>;
@@ -1437,8 +1438,8 @@ export type StepJson = {
 export declare function expandStep(raw: StepJson): Result<StepJson, string>;
 /**
  * The form a version is stored and compiled in: sugar expanded, `lookup_entity` rewritten
- * into graph nodes, and every internal source's schema pinned from the target model
- * (structural rule 4). Idempotent.
+ * into graph nodes, and every internal source's schema pinned from the target model.
+ * Idempotent.
  */
 export declare function normalizeVersion(version: MappingVersion, env: Pick<GraphEnv, 'targets'>): {
   version: MappingVersion;

package/dist/index.mjs

@@ -64,7 +64,7 @@ function stepError(code, detail) {
 * The runtime value of the `date` type is an `Instant`: a frozen point in time in epoch
 * milliseconds. Calendar math ("+10y", "start of day") happens in an IANA time zone, using
 * `Intl.DateTimeFormat` to move between instants and wall-clock time. "now" only ever comes
-* from the run context (arch.md limitation #10), never from `Date.now()`.
+* from the run context (arch.md, "Time"), never from `Date.now()`.
 */
 var Instant = class Instant {
 	epochMs;
@@ -609,7 +609,7 @@ function typeName(text) {
 * A record is a plain frozen-by-convention object; an absent key reads as null (that is how
 * `omit_if_null` and `skip_field` leave a field out of a write). Nothing here depends on
 * insertion order: hashing and sorting go through `canonicalKey` and `compareVals`, so two
-* runs over the same snapshot produce identical output (arch.md limitation #17).
+* runs over the same snapshot produce identical output (arch.md, "Execution model").
 */
 /** Returned by a step to leave its field out of the record entirely (`omit_if_null`). */
 const OMIT = Symbol("omit");
@@ -698,8 +698,8 @@ function sortRecords(rows, fields) {
 //#endregion
 //#region src/mapping/predicate.ts
 /**
-* The one predicate vocabulary (arch.md, "Conditional"), shared by `when`, `filter_list`,
-* the `filter` node, join `where`, aggregate `where`, and `rows` expectations.
+* The one predicate vocabulary, shared by `when`, `filter_list`, the `filter` node, join
+* `where`, aggregate `where`, and `rows` expectations.
 *
 * Shape: `{ path?, <predicate>: operand }` with exactly one predicate key, or a composition
 * `{ all: { of: [...] } }`, `{ any: { of: [...] } }`, `{ not: cond }`. Without `path` the
@@ -707,7 +707,7 @@ function sortRecords(rows, fields) {
 * `{ param: name }`.
 *
 * Null never compares: ordering and equality with a null side are false, `neq` and `not_in`
-* are their negations and so hold for null (arch.md L366).
+* are their negations and so hold for null (arch.md, "Null semantics").
 */
 const COMPARISONS = [
 	"eq",
@@ -1173,7 +1173,7 @@ function compileExpectation(node, exp, output, renv) {
 //#endregion
 //#region src/mapping/nodes/def.ts
 /**
-* Collection node definitions (arch.md, "Node definition, collection scope").
+* Collection node definitions.
 *
 * A node definition compiles itself: from its params and the types of its inputs it returns
 * its output type and a closure, in one step, so type checking and compilation stay the same
@@ -1208,7 +1208,7 @@ function fail(message, extra = {}) {
 * `aggregate`: one record per group of `group_by` (one record overall for `group_by: []`,
 * even on empty input). Every aggregation takes an optional `where`, making it a filtered
 * aggregate. Results never depend on input order: `sum` adds in sorted order, `collect_set`
-* is sorted, and `collect_list`, `first`, `last` require `order_by` (limitation #17).
+* is sorted, and `collect_list`, `first`, `last` require `order_by`.
 */
 const orderBy = z.array(z.union([z.string().min(1), z.strictObject({
 	path: z.string().min(1),
@@ -1444,7 +1444,7 @@ const aggregateNode = defineNode({
 //#endregion
 //#region src/mapping/ops/def.ts
 /**
-* Record op definitions (arch.md, "Op definition, record scope").
+* Record op definitions.
 *
 * An op is a params schema, a type function and a curried implementation. `signature` is
 * the validator's half; `run` binds params once per compiled version and returns the
@@ -1599,7 +1599,7 @@ function versionJsonSchema() {
 * - `unique`: `keys` unique.
 * - `rows`: every row satisfies `cond`.
 * - `acyclic`: the edges `edge.from -> edge.to` of `in` contain no cycle. With `edge.key` the
-*   edges belong to groups (an article's own routing graph) and each group is checked on its
+*   edges belong to groups (each product's own supply graph) and each group is checked on its
 *   own; with `per`, every distinct `per.key` of `per.in` is checked against all edges. Either
 *   way a group's rows of `remove.in` are taken out first. Cycle detection is iterative, so
 *   it is engine code rather than a composition of DAG nodes.
@@ -2025,7 +2025,7 @@ function tableJsonSchema(table, system) {
 		description: c.description
 	})));
 }
-/** The pinned schema of an internal entity read as a source (structural rule 4). */
+/** The pinned schema of an internal entity read as a source. */
 function entityJsonSchema(entity) {
 	return objectSchema(`internal.${entity.name}`, entity.fields.map((f) => ({
 		name: f.name,
@@ -2216,7 +2216,7 @@ const filterNode = defineNode({
 * with the same name on both sides merges, and any other collision is a save error. Null keys
 * never match.
 *
-* `cardinality` is declared and enforced while the hash table is built (limitation #16):
+* `cardinality` is declared and enforced while the hash table is built:
 * `n:1` right keys unique, `1:n` left keys unique, `1:1` both, `n:m` unrestricted but needs a
 * `count` expectation on this node.
 */
@@ -2940,7 +2940,7 @@ const requireOp = defineOp({
 });
 /**
 * Terminal. A null leaves the field out of the record (and so out of the write) instead of
-* setting it to null (limitation #8). Readers downstream see the field as nullable.
+* setting it to null. Readers downstream see the field as nullable.
 */
 const omitIfNull = defineOp({
 	name: "omit_if_null",
@@ -3347,7 +3347,7 @@ const slug = defineOp({
 //#endregion
 //#region src/mapping/ops/when.ts
 /**
-* `when`: the one general conditional (arch.md limitation #12). First matching case wins;
+* `when`: the one general conditional. First matching case wins;
 * `then` and `else` are a literal, `null`, or `{ "pass": true }` to forward the input. `else`
 * defaults to pass-through. As a pipeline's first step there is no input: every case must
 * test a `path`, and `else` is required.
@@ -3458,7 +3458,7 @@ const opRegistry = Object.fromEntries(all$1.map((op) => [op.name, op]));
 //#endregion
 //#region src/mapping/sugar.ts
 /**
-* Sugar, kept for readability and expanded on save (arch.md, "Conditional" and "Lookup").
+* Sugar, kept for readability and expanded on save.
 *
 * - `{ op: "if_<predicate>", <operand>, then, else? }` expands to a one-case `when`, e.g.
 *   `{ op: "if_lte", value: 0, then: null }` to
@@ -3672,8 +3672,8 @@ function rewriteLookups(node, env, sources, issues) {
 }
 /**
 * The form a version is stored and compiled in: sugar expanded, `lookup_entity` rewritten
-* into graph nodes, and every internal source's schema pinned from the target model
-* (structural rule 4). Idempotent.
+* into graph nodes, and every internal source's schema pinned from the target model.
+* Idempotent.
 */
 function normalizeVersion(version, env) {
 	const issues = [];
@@ -4026,14 +4026,14 @@ function metric(node, name, rows) {
 * fails at save, blamed on the `map` field that produced it.
 *
 * A reference field listed in `refs` is written as a natural key of the entity it references
-* (`product_id` as a SKU, a lane as its `(from, to)` pair) and typed by those fields, so a
+* (`product_id` as a SKU, a join-table row as its two keys) and typed by those fields, so a
 * key of the wrong shape fails at save; the host resolves it to an id when it writes. Key
 * fields must be non-null, except a nullable identity field of an entity whose identity
-* matches NULLs as equal (the inbound supplier lane, `from_warehouse_id = NULL`).
+* matches NULLs as equal (a transfer with no origin, `from_warehouse_id = NULL`).
 *
 * `mode: 'replace'` makes the rows the complete set of the target for the company: the host
 * reconciles with `synchronize_all`, deleting rows this run no longer produces. That is what a
-* presence-only entity needs (an exclusion row *is* the rule). Because a short source read
+* presence-only entity needs (a join-table row *is* the link). Because a short source read
 * would then delete real rows, `in` must carry a `count` expectation with a lower bound
 * (`min` or `shiftRatio.min`) whose action is `stop` or `skip_downstream`.
 *
@@ -4092,7 +4092,7 @@ const sinkNode = defineNode({
 	op: "sink",
 	label: "Write to target",
 	category: "target",
-	description: "Writes rows into a Spherecast entity, updating records with the same key.",
+	description: "Writes rows into a target entity, updating records with the same key.",
 	slots: [{
 		id: "in",
 		label: "In",
@@ -4488,7 +4488,7 @@ function topologicalOrder(nodes) {
 //#endregion
 //#region src/mapping/compile.ts
 /**
-* The graph compiler (arch.md, "The compiler"): walks nodes in topological order, threading
+* The graph compiler (arch.md, "Type checking"): walks nodes in topological order, threading
 * record types along edges, and compiles each node into a closure in the same pass. The
 * result is one plan per version; a run never touches JSON.
 *
@@ -4690,7 +4690,7 @@ function dedupe(issues) {
 		return true;
 	});
 }
-/** One sink per target entity (structural rule 3): resolve overlaps with a union. */
+/** One sink per target entity (structural rule 4): resolve overlaps with a union. */
 function sinkIssues(compiled) {
 	const writers = /* @__PURE__ */ new Map();
 	for (const [id, c] of compiled) for (const entity of c.node.writes ?? []) writers.set(entity, [...writers.get(entity) ?? [], id]);
@@ -4701,8 +4701,8 @@ function sinkIssues(compiled) {
 	}));
 }
 /**
-* Limitation #20: a map that can drop records upstream of a join or aggregate can flip its
-* result, so the first join or aggregate on every path from it must declare `tolerate_skips`.
+* A map that can drop records upstream of a join or aggregate can flip its result, so the
+* first join or aggregate on every path from it must declare `tolerate_skips`.
 */
 function skipIssues(version, compiled) {
 	const next = consumers(version.nodes);