@caracal-lynx/sluice 0.1.1 → 0.1.3

package/LICENCE-FAQ.md

@@ -1,74 +1,74 @@
-# Sluice Licence FAQ
-
-Sluice is published under the **Elastic Licence 2.0 (ELv2)**. This page explains in plain English what that means for you. If in doubt, read the [full licence text](LICENSE) or contact us.
-
----
-
-## Can I use Sluice to run data migrations for my own business?
-
-**Yes, absolutely.** If you are running Sluice internally — your own team, your own data, your own migration project — you are welcome to use it free of charge with no restrictions. That is exactly what it was built for.
-
----
-
-## Can I use Sluice as part of an internal IT project or toolchain?
-
-**Yes.** Embedding Sluice in internal scripts, automation pipelines, or tooling used within your own organisation is permitted.
-
----
-
-## Can I modify Sluice for my own use?
-
-**Yes.** You can fork the repository, modify the code, and run your modified version internally. You are not required to publish your changes, though contributions back to the project are always welcome.
-
----
-
-## Can I use Sluice to deliver a data migration project for a client?
-
-**No.** Using Sluice as the basis of a commercial service delivered to third parties — for example, running Sluice pipelines on behalf of a paying client as part of a consultancy engagement — requires a commercial licence from Caracal Lynx Ltd.
-
-This restriction exists because Sluice is the core product of Caracal Lynx's data migration practice. We are happy for businesses to use it for themselves; we are not able to allow other consultancies to compete directly using our tool without an agreement in place.
-
----
-
-## I am a consultant. Can I recommend Sluice to my clients and help them set it up?
-
-**Yes, with a distinction.** You may recommend Sluice to clients and help them understand it. The restriction applies when Sluice is central to a commercial service *you* are delivering — i.e. you are operating or running pipelines on the client's behalf as a paid engagement. If the client is operating Sluice themselves after your initial help, that is their internal use and is permitted.
-
-If you are unsure whether your situation requires a commercial licence, please contact us — we would rather clarify upfront than create problems later.
-
----
-
-## Can I resell Sluice or white-label it as my own product?
-
-**No.** Reselling, repackaging, or white-labelling Sluice — with or without modifications — is not permitted under ELv2.
-
----
-
-## Can I write and publish plugins or adapters for Sluice?
-
-**Yes.** Building and publishing `sluice-adapter-*` or `sluice-plugin-*` packages on npm is encouraged. The restriction on commercial use applies to Sluice itself; it does not prevent you from building and selling plugins or adapters as separate products, provided those products do not effectively replicate Sluice's core functionality.
-
----
-
-## Can I contribute to the Sluice codebase?
-
-**Yes, and thank you.** Pull requests are welcome. By submitting a contribution you agree that your code is licenced under the same ELv2 terms as the rest of the project, and that Caracal Lynx Ltd. retains the right to include it in future releases (including any future commercial releases).
-
----
-
-## What if I want to use Sluice commercially?
-
-Contact us. We offer commercial licences for consultancies and service providers who want to use Sluice as part of a paid offering. Pricing is by arrangement and depends on the nature and scale of use.
-
-📧 **michael.scott@caracallynx.com**
-🌐 **Caracal Lynx Ltd.** — registered in Scotland, SC826823
-
----
-
-## Is this "open source"?
-
-Technically, no. The Elastic Licence 2.0 is a *source available* licence — the code is fully public, you can read it, fork it, and use it for internal purposes, but it does not meet the OSI definition of "open source" because of the restriction on commercial service use. We have chosen this approach to keep Sluice accessible to businesses while protecting the consultancy practice that funds its development.
-
----
-
-*This FAQ is a plain-English guide and does not constitute legal advice. The [LICENSE](LICENSE) file is the authoritative legal text. Last updated: April 2026.*
+# Sluice Licence FAQ
+
+Sluice is published under the **Elastic Licence 2.0 (ELv2)**. This page explains in plain English what that means for you. If in doubt, read the [full licence text](LICENSE) or contact us.
+
+---
+
+## Can I use Sluice to run data migrations for my own business?
+
+**Yes, absolutely.** If you are running Sluice internally — your own team, your own data, your own migration project — you are welcome to use it free of charge with no restrictions. That is exactly what it was built for.
+
+---
+
+## Can I use Sluice as part of an internal IT project or toolchain?
+
+**Yes.** Embedding Sluice in internal scripts, automation pipelines, or tooling used within your own organisation is permitted.
+
+---
+
+## Can I modify Sluice for my own use?
+
+**Yes.** You can fork the repository, modify the code, and run your modified version internally. You are not required to publish your changes, though contributions back to the project are always welcome.
+
+---
+
+## Can I use Sluice to deliver a data migration project for a client?
+
+**No.** Using Sluice as the basis of a commercial service delivered to third parties — for example, running Sluice pipelines on behalf of a paying client as part of a consultancy engagement — requires a commercial licence from Caracal Lynx Ltd.
+
+This restriction exists because Sluice is the core product of Caracal Lynx's data migration practice. We are happy for businesses to use it for themselves; we are not able to allow other consultancies to compete directly using our tool without an agreement in place.
+
+---
+
+## I am a consultant. Can I recommend Sluice to my clients and help them set it up?
+
+**Yes, with a distinction.** You may recommend Sluice to clients and help them understand it. The restriction applies when Sluice is central to a commercial service *you* are delivering — i.e. you are operating or running pipelines on the client's behalf as a paid engagement. If the client is operating Sluice themselves after your initial help, that is their internal use and is permitted.
+
+If you are unsure whether your situation requires a commercial licence, please contact us — we would rather clarify upfront than create problems later.
+
+---
+
+## Can I resell Sluice or white-label it as my own product?
+
+**No.** Reselling, repackaging, or white-labelling Sluice — with or without modifications — is not permitted under ELv2.
+
+---
+
+## Can I write and publish plugins or adapters for Sluice?
+
+**Yes.** Building and publishing `sluice-adapter-*` or `sluice-plugin-*` packages on npm is encouraged. The restriction on commercial use applies to Sluice itself; it does not prevent you from building and selling plugins or adapters as separate products, provided those products do not effectively replicate Sluice's core functionality.
+
+---
+
+## Can I contribute to the Sluice codebase?
+
+**Yes, and thank you.** Pull requests are welcome. By submitting a contribution you agree that your code is licenced under the same ELv2 terms as the rest of the project, and that Caracal Lynx Ltd. retains the right to include it in future releases (including any future commercial releases).
+
+---
+
+## What if I want to use Sluice commercially?
+
+Contact us. We offer commercial licences for consultancies and service providers who want to use Sluice as part of a paid offering. Pricing is by arrangement and depends on the nature and scale of use.
+
+📧 **michael.scott@caracallynx.com**
+🌐 **Caracal Lynx Ltd.** — registered in Scotland, SC826823
+
+---
+
+## Is this "open source"?
+
+Technically, no. The Elastic Licence 2.0 is a *source available* licence — the code is fully public, you can read it, fork it, and use it for internal purposes, but it does not meet the OSI definition of "open source" because of the restriction on commercial service use. We have chosen this approach to keep Sluice accessible to businesses while protecting the consultancy practice that funds its development.
+
+---
+
+*This FAQ is a plain-English guide and does not constitute legal advice. The [LICENSE](LICENSE) file is the authoritative legal text. Last updated: April 2026.*

package/LICENSE

@@ -1,92 +1,92 @@
-Elastic License 2.0
-
-URL: https://www.elastic.co/licensing/elastic-license
-
-## Acceptance
-
-By using the software, you agree to all of the terms and conditions below.
-
-## Copyright License
-
-The licensor grants you a non-exclusive, royalty-free, worldwide,
-non-sublicensable, non-transferable license to use, copy, distribute, make
-available, and prepare derivative works of the software, in each case subject
-to the limitations and conditions below.
-
-## Limitations
-
-You may not provide the software to third parties as a hosted or managed
-service, where the service provides users with access to any substantial set
-of the features or functionality of the software.
-
-You may not move, change, disable, or circumvent the license key functionality
-in the software, and you may not remove or obscure any functionality in the
-software that is protected by the license key.
-
-You may not alter, remove, or obscure any licensing, copyright, or other
-notices of the licensor in the software. Any use of the licensor's trademarks
-is subject to applicable law.
-
-## Patents
-
-The licensor grants you a license, under any patent claims the licensor can
-license, or becomes able to license, to make, have made, use, sell, offer for
-sale, import and have imported the software, in each case subject to the
-limitations and conditions in this license. This license does not cover any
-patent claims that you cause to be infringed by modifications or additions to
-the software. If you or your company make any written claim that the software
-infringes or contributes to infringement of any patent, your patent license
-for the software granted under these terms ends immediately. If your company
-makes such a claim, your patent license ends immediately for work on behalf
-of your company.
-
-## Notices
-
-You must ensure that anyone who gets a copy of any part of the software from
-you also gets a copy of these terms.
-
-If you modify the software, you must include in any modified copies of the
-software prominent notices stating that you have modified the software.
-
-## No Other Rights
-
-These terms do not imply any licenses other than those expressly granted in
-these terms.
-
-## Termination
-
-If you use the software in violation of these terms, such use is not licensed,
-and your licenses will automatically terminate. If the licensor provides you
-with a notice of your violation, and you cease all violation of this license
-no later than 30 days after you receive that notice, your licenses will be
-reinstated retroactively. However, if you violate these terms after such
-reinstatement, any additional violation of these terms will cause your
-licenses to terminate automatically and permanently.
-
-## No Liability
-
-As far as the law allows, the software comes as is, without any warranty or
-condition, and the licensor will not be liable to you for any damages arising
-out of these terms or the use or nature of the software, under any kind of
-legal claim.
-
-## Definitions
-
-The **licensor** is the entity offering these terms, and the **software** is
-the software the licensor makes available under these terms.
-
-**You** refers to the individual or entity agreeing to these terms.
-
-**Your company** is any legal entity, sole proprietorship, or other kind of
-organization that you work for, plus all organizations that have control over,
-are under the control of, or are under common control with that organization.
-**Control** means ownership of substantially all the assets of an entity, or
-the power to direct its management and policies by vote, contract, or
-otherwise. Control can be direct or indirect.
-
-**Your licenses** are all the licenses granted to you for the software under
-these terms.
-
-**Use** means anything you do with the software requiring one of your licenses.
-
-**Trademark** means trademarks, service marks, and similar rights.
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject
+to the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set
+of the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other
+notices of the licensor in the software. Any use of the licensor's trademarks
+is subject to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If your company
+makes such a claim, your patent license ends immediately for work on behalf
+of your company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from
+you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license
+no later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your
+licenses to terminate automatically and permanently.
+
+## No Liability
+
+As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is
+the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that organization.
+**Control** means ownership of substantially all the assets of an entity, or
+the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.
+
+**Trademark** means trademarks, service marks, and similar rights.

package/PLUGINS.md

@@ -0,0 +1,294 @@
+# Sluice — Plugin Author Guide
+
+Sluice's pipeline configs are intentionally constrained — the schema is fixed, the field types are enumerated, the DQ check types are an explicit list. That keeps configs readable and reviewable. But every real migration eventually needs *something* the built-ins don't cover: a regex pattern that only makes sense for one client's data, a date format only one ERP uses, a merge strategy with custom precedence rules.
+
+Plugins fill that gap without forcing you to fork the engine. Sluice exposes a **three-tier extension model** that scales from "I just want a reusable composite rule for this client" to "I want to publish a paid adapter package on npm."
+
+---
+
+## The three tiers at a glance
+
+| Tier | What it is | Where it lives | Who writes it | Distribution |
+|---|---|---|---|---|
+| **Tier 1 — Composite YAML rules** | A named bundle of built-in DQ checks | YAML files in your project | Anyone — no code | In your repo |
+| **Tier 2 — File-based plugins** | TypeScript module exporting a `RulePlugin`, `TransformPlugin`, or `MergeStrategyPlugin` | `plugins/*.{rule,transform,merge}.ts` in your project | Anyone with TypeScript | In your repo |
+| **Tier 3 — npm package plugins** | A published npm package with a `register()` function | Anywhere installable via `npm install` | Plugin authors | npmjs.com (public or private) |
+
+You can mix tiers freely — a single pipeline can pull composite rules (Tier 1), a local dev's file plugin (Tier 2), and an installed npm rule pack (Tier 3) all at once.
+
+---
+
+## Tier 1 — Composite YAML rules
+
+A composite rule is a **named bundle of built-in checks** that you reference in pipeline DQ rules by a single ID. Useful when the same combination of checks (e.g., `notNull` + `pattern` + `maxLength` for an internal style number) repeats across many fields and many pipelines.
+
+### Library file
+
+Composite rules live in a YAML file referenced by `dq.rulesFile`. Convention: `shared/rules.yaml` at the repo root.
+
+```yaml
+# shared/rules.yaml
+version: "1.0"
+
+rules:
+  - id: ukVatNumber
+    description: UK VAT registration number — format only (existence check is a separate concern)
+    checks:
+      - { type: pattern, value: "^GB([0-9]{9}|[0-9]{12}|(GD|HA)[0-9]{3})$", severity: warning }
+
+  - id: positivePrice
+    description: Price must be a non-negative number with sensible upper bound
+    checks:
+      - { type: notNull, severity: critical }
+      - { type: min,     value: 0,       severity: critical }
+      - { type: max,     value: 99999.99, severity: warning  }
+```
+
+### Use in a pipeline
+
+```yaml
+# customers.pipeline.yaml
+dq:
+  rulesFile: ./shared/rules.yaml   # tell ConfigLoader where to find composite rules
+  rules:
+    - field: VAT_NUMBER
+      checks:
+        - { type: ukVatNumber }    # expands to the pattern check above at load time
+
+    - field: COST_PRICE
+      checks:
+        - { type: positivePrice }  # expands to all three checks at load time
+```
+
+`ConfigLoader` expands composite-rule references into their underlying built-in checks **before** Zod validation runs, so the DQ engine only ever sees standard check types.
+
+### When to reach for Tier 1
+
+- The same combination of checks repeats across multiple fields or pipelines.
+- The combination doesn't need any custom code — built-in checks suffice.
+- You want non-developers (data analysts, project managers) to be able to read and edit the rules.
+
+### Constraints
+
+- Composite rule IDs must be valid identifiers (`^[a-zA-Z][a-zA-Z0-9_-]*$`) and must not collide with built-in check type names (`notNull`, `unique`, `pattern`, etc.).
+- Composite rules can only contain built-in checks — they cannot reference other composite rules (no nesting).
+
+---
+
+## Tier 2 — File-based plugins
+
+When you need actual logic — a check that calls a custom regex with side conditions, a transform that does business-specific date parsing, a merge strategy that picks the maximum value across sources — write a TypeScript plugin file.
+
+Plugins are auto-discovered from a `plugins/` directory next to your pipeline YAML (or from any directory passed via `--plugins`).
+
+### File naming convention
+
+| Filename suffix | Plugin type | Exported symbol |
+|---|---|---|
+| `*.rule.ts` (or `.rule.js`) | DQ rule | `export const rule: RulePlugin` |
+| `*.transform.ts` (or `.transform.js`) | Field transform | `export const transform: TransformPlugin` |
+| `*.merge.ts` (or `.merge.js`) | Merge strategy | `export const mergeStrategy: MergeStrategyPlugin` |
+
+### Example — DQ rule plugin
+
+```typescript
+// plugins/ifs-customer-no.rule.ts
+import type { RulePlugin } from '@caracal-lynx/sluice';
+
+export const rule: RulePlugin = {
+  id: 'ifsCustomerNo',
+  description: 'IFS customer number — three uppercase letters followed by 4–7 digits',
+
+  validate(value, config, rowIndex, field) {
+    if (typeof value !== 'string') return null;
+    if (/^[A-Z]{3}[0-9]{4,7}$/.test(value)) return null;
+    return {
+      field,
+      rowIndex,
+      value,
+      rule: 'ifsCustomerNo',
+      severity: config.severity,
+      message: config.message ?? `${value} is not a valid IFS customer number`,
+    };
+  },
+};
+```
+
+Use it in a pipeline:
+
+```yaml
+dq:
+  rules:
+    - field: CUSTOMER_NO
+      checks:
+        - { type: ifsCustomerNo, severity: critical }
+```
+
+### Example — transform plugin
+
+```typescript
+// plugins/season-from-date.transform.ts
+import type { TransformPlugin } from '@caracal-lynx/sluice';
+
+export const transform: TransformPlugin = {
+  id: 'seasonFromDate',
+  description: 'Derives a fashion season code (SS25, AW25 …) from a YYYY-MM-DD launch date',
+
+  apply(value, row, config) {
+    if (typeof value !== 'string') return null;
+    const match = /^(\d{4})-(\d{2})-/.exec(value);
+    if (!match) return null;
+    const [, year, month] = match;
+    const yy = year!.slice(2);
+    const mm = parseInt(month!, 10);
+    return mm >= 1 && mm <= 6 ? `SS${yy}` : `AW${yy}`;
+  },
+};
+```
+
+Use it in a pipeline:
+
+```yaml
+transform:
+  fields:
+    - { from: LAUNCH_DATE, to: Season, type: custom, customOp: seasonFromDate }
+```
+
+### Example — merge strategy plugin
+
+```typescript
+// plugins/max-cost.merge.ts
+import type { MergeStrategyPlugin } from '@caracal-lynx/sluice';
+
+export const mergeStrategy: MergeStrategyPlugin = {
+  id: 'max-cost',
+  description: 'Coalesce by key, picking the highest COST_PRICE across all sources',
+  async merge(store, sources, config) {
+    // Implementation uses the StagingStore SQL surface — see docs for full example
+    // ...
+    return { rowsMerged: 0, conflicts: 0, unmatched: 0, tableName: 'stg_merged' };
+  },
+};
+```
+
+### Loading & discovery
+
+By default, the runner scans `{cwd}/plugins/` for files matching the suffixes above. You can pass extra directories with `--plugins`:
+
+```bash
+sluice run customers.pipeline.yaml --plugins ./shared/plugins --plugins ./team/plugins
+```
+
+All discovered plugins are registered before any pipeline phase runs. Duplicate IDs (across files, directories, or with built-ins) raise a `ConfigError` at startup — fail fast.
+
+### Constraints
+
+- **Plugins must be pure.** No I/O, no async, no mutation of the input row, no global state. The DQ and transform engines call them in tight loops — side effects break determinism.
+- **Errors must be predictable.** `RulePlugin.validate` returns `null` for "valid"; throw only on unrecoverable bugs. `TransformPlugin.apply` returns the transformed value; throw `TransformError` to fail the row.
+- **Plugin IDs are global.** `ifsCustomerNo` lives in the same namespace as the built-in `notNull`, `unique`, etc. Choose distinctive IDs.
+
+---
+
+## Tier 3 — npm package plugins
+
+When you want to **distribute** a plugin — to other projects in your organisation, to a client engagement, or to the public — package it as an npm module and register it via Sluice's package-discovery mechanism.
+
+### Package shape
+
+A plugin package exports a `register()` function that registers any combination of rules, transforms, and merge strategies:
+
+```typescript
+// @your-org/sluice-rules-uk/src/index.ts
+import type {
+  PluginPackage,
+  RuleRegistry,
+  TransformRegistry,
+  MergeStrategyRegistry,
+} from '@caracal-lynx/sluice';
+import { ukVatNumber } from './rules/uk-vat-number.js';
+import { ukPostcode } from './rules/uk-postcode-strict.js';
+import { sortCodeAccount } from './rules/sort-code-account.js';
+
+export const plugin: PluginPackage = {
+  register(rules: RuleRegistry, transforms: TransformRegistry, options, merges) {
+    rules.register(ukVatNumber);
+    rules.register(ukPostcode);
+    rules.register(sortCodeAccount);
+    // transforms.register(...) and merges?.register(...) work the same way
+  },
+};
+```
+
+`package.json`:
+
+```json
+{
+  "name": "@your-org/sluice-rules-uk",
+  "version": "1.0.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "peerDependencies": {
+    "@caracal-lynx/sluice": "^0.1.0"
+  }
+}
+```
+
+### Wiring it into a pipeline project
+
+Each Sluice project can declare its npm plugin packages in a top-level `sluice.config.yaml`:
+
+```yaml
+# sluice.config.yaml — alongside your pipeline YAMLs
+version: "1.0"
+
+plugins:
+  - package: '@your-org/sluice-rules-uk'
+    options:                          # passed verbatim to register()
+      enableExperimental: false
+  - package: '@your-org/sluice-rules-fashion'
+```
+
+Then `npm install` the packages and `sluice run` will load them automatically:
+
+```bash
+npm install @your-org/sluice-rules-uk @your-org/sluice-rules-fashion
+sluice run customers.pipeline.yaml
+```
+
+### When to reach for Tier 3
+
+- You want to share a plugin across multiple projects or teams.
+- You want to publish a commercial plugin (paid adapter, domain rule pack).
+- You want versioning and changelogs separate from your pipeline configs.
+
+### Distribution
+
+Public plugins go on the public npm registry. Private plugins use a private registry (npmjs.com Pro plan, GitHub Packages, Verdaccio, etc.) — Sluice doesn't care which.
+
+If you publish a public plugin, please mention `@caracal-lynx/sluice` as a `peerDependency` rather than a direct dependency, and declare a SemVer range that matches the Sluice public API surface you depend on.
+
+---
+
+## Plugin contracts (the rules)
+
+Regardless of tier, every Sluice plugin must obey these:
+
+1. **Pure.** No filesystem, network, database, or environment access. No timers, no `Math.random()` without a seed, no `Date.now()`. Plugins run inside tight loops — side effects break determinism and reproducibility.
+2. **Synchronous.** `RulePlugin.validate`, `TransformPlugin.apply`, and `MergeStrategyPlugin.merge` are called via the engine's synchronous (or `async`-but-deterministic) hot path. (`MergeStrategyPlugin` is `async` because merge strategies query the staging DB; their async-ness is bounded to that.)
+3. **Idempotent and stateless.** Calling a plugin twice with the same input must produce the same output. No instance state, no closures over external mutables.
+4. **Throw `TransformError` / return `RuleViolation`** — don't throw raw strings, don't return `undefined`. The engine catches at the pipeline boundary.
+5. **Don't mutate the row.** Plugins receive the source row by reference for cross-field reads; treat it as read-only.
+
+The one exception to Rule 1 is the **enrich phase** (Phase 4) — `EnrichPlugin` is async and may call external APIs. That's a separate plugin interface (`@caracal-lynx/sluice-enrich`) with its own contract; see the enrich-phase docs for details.
+
+---
+
+## More
+
+- The full schema reference for pipeline YAML, including how built-in checks and transforms work, lives in [CLAUDE.md](CLAUDE.md).
+- The runtime types (`RulePlugin`, `TransformPlugin`, `MergeStrategyPlugin`, `PluginPackage`) are exported from the package root: `import type { RulePlugin } from '@caracal-lynx/sluice'`.
+- Working examples of all three tiers ship in this repo's `tests/fixtures/plugins/` and `tests/fixtures/shared-rules.yaml`.
+
+Questions, gaps, or contributions to this guide? Open a Discussion or send a PR.
+
+— Caracal Lynx Ltd.