@niscorp/tide 0.1.9 → 0.1.10

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,13 @@
1
1
  # @niscorp/tide
2
2
 
3
+ ## 0.1.10
4
+
5
+ ### Patch Changes
6
+
7
+ - 2fc1bf0: The docs name the identity seam `actor`, say a fact kind refuses only the other kinds' key fields, list everything load refuses and `graph()`'s `refusals`, and show `migrations/` in the file layout.
8
+
9
+ **What to change:** nothing. Documentation only.
10
+
3
11
  ## 0.1.9
4
12
 
5
13
  ### Patch Changes
package/DESIGN.md CHANGED
@@ -64,7 +64,7 @@ of those properties. Tide exists so that piece never has to be written.
64
64
 
65
65
  5. **Identity-blind.** Tide never learns what a principal is. Every reflex names an
66
66
  `as`; the host resolves it to whatever authority means there (under moss: a
67
- charter-resolved, engine-enforced `ActorContext`) and tide threads it through to
67
+ charter-resolved, engine-enforced principal) and tide threads it through to
68
68
  effects untouched. It is also *written down* on every run, so a host can scope its
69
69
  own ledger by it without tide knowing what it scoped. The same blindness charter
70
70
  has toward universes, tide has toward identity — and for the same reason:
@@ -281,7 +281,9 @@ drive tide; nothing else about the producer is tide's business.
281
281
  ```
282
282
 
283
283
  **The union is enforced, and ⟲ it was not.** Each kind requires the fields that make it
284
- addressable and refuses the fields belonging to the others. `{ kind: 'write' }` with no
284
+ addressable and refuses the key fields of the others (`entity`, `name`, `target`,
285
+ `runId`; a `signal` also refuses `op`). The rest are not checked by kind: a `write`
286
+ accepts `payload`, `reflex`, `stats` and `by`. `{ kind: 'write' }` with no
285
287
  entity used to parse, store, match nothing, get marked delivered, and vanish — a
286
288
  producer with no way to learn its fact was never going to wake anything. An
287
289
  unenforced union is worse than none, because it is documented.
@@ -671,8 +673,9 @@ cannot count it:
671
673
  Releasing a parked fact **records** the override; **⟲** clearing the park alone was a
672
674
  ping-pong, because the depth that parked it had not changed and never would.
673
675
 
674
- Load **refuses** outright: an unguarded cycle, a reflex naming an unregistered
675
- effect, a `when` on a non-fact trigger. The verification is only as good as the
676
+ Load **refuses** outright: a reflex that does not parse, a duplicate id, a reflex
677
+ naming an unregistered effect, a `when` on a non-fact trigger, `each` mode with no
678
+ `unitKey`, a run subscription to a reflex that is not loaded, an unguarded cycle. The verification is only as good as the
676
679
  effects' `writes`: under moss they are *derived* (from `mutationEffect` on the vex
677
680
  mutation behind each effect), so an edge is never guessed; a plain host declares
678
681
  them or forgoes the check, and an effect with none is reported as a **blind** edge,
@@ -746,7 +749,7 @@ the argument that tide is a *nisc* library and not a scheduler with JSON config:
746
749
  | `transform` | `(config, source) => value` | Prism's `evaluate`, or anything | **nova's exact socket** — nova doesn't know Prism; neither does tide |
747
750
  | `select` | `(query, ctx) => AsyncIterable<row>` — the query blob is opaque | vex replay under the actor's policy; or raw SQL; or an array | vex's `generateDsl` / `mapToShape` |
748
751
  | `effects` | `name → { run(input, ctx), writes?, preview? }` | vex mutation replays, fns, cortex agents; or plain functions | moss's `functions` seam |
749
- | `ctx` | opaque, threaded through to `select` and `effects`; carries `taskKey`, `emit`, `now` | moss: `ActorContext` (principal, policy, wire) | charter's universe-blindness, applied to identity |
752
+ | `actor` | `(as) => unknown`; its answer is threaded opaque into `select` and `effects` as `ctx.actor` | moss: the principal `as` names (policy, wire) | charter's universe-blindness, applied to identity |
750
753
 
751
754
  Plus the driver-facing edges, contracts rather than injections: **`ingest(fact)`**
752
755
  in, **`advance({ now, limit })`** to run one committed increment, and
@@ -822,7 +825,7 @@ Moss fills every seam but the store, which is tide's own:
822
825
  | `select` | vex replay **through the actor's own wire** — selection inherits replay-only, scoped, cached, inspectable; the tenant filter is in the SQL, engine-injected, unforgeable |
823
826
  | `effects` | every seeded vex **mutation** auto-registered under its fingerprint (with `writes` *derived* from `mutationEffect`) + the app's `effects(actor)` |
824
827
  | `transform` | prism — the same wiring the shell's transform socket already gets |
825
- | `ctx` | `ActorContext`: the charter-resolved, engine-enforced, no-shell principal |
828
+ | `actor` | the principal a run's `as` names: charter-resolved, engine-enforced, no shell |
826
829
  | the ledger | ordinary vex entries over `tide_run`, scoped by the host on the identity the run declared |
827
830
 
828
831
  **The engine's writes do not go through vex's mutation pipeline, and the reason is
@@ -886,6 +889,9 @@ src/
886
889
  types.ts ledger rows, seam types, TideStore, UNIQUE_BY, reports
887
890
  errors.ts TideError (code + details)
888
891
 
892
+ migrations/
893
+ index.ts TIDE_GRAMMAR, TIDE_SCHEMAS — a reflex or a draft as a stored document (the ./migrations entry)
894
+
889
895
  schemas/
890
896
  reflex.schema.ts ReflexSchema — trigger, select, effect, policy, enabled; the draft schemas and the timer
891
897
  trigger.schema.ts clock | fact | manual, with narrowing helpers
@@ -909,7 +915,7 @@ src/
909
915
 
910
916
  store/
911
917
  memory.ts createMemoryStore — the reference implementation + snapshot()
912
- postgres/ the Postgres store — the ./postgres entry; the only directory that imports strata
918
+ postgres/ the Postgres store — the ./postgres entry; with migrations/, the only code that imports strata
913
919
  index.ts the door: createTideStore, TIDE_SEQUENCE, TIDE_TABLES, TIDE_DDL, TidePool
914
920
  pool.ts the pool the store runs on, as much of one as it uses
915
921
  tables.ts the four tables, and the strata sequence that makes them
@@ -1031,7 +1037,7 @@ a host can do: turning its own writes into facts.
1031
1037
  truthiness rather than a second reading of it.
1032
1038
 
1033
1039
  13. **Identity is the host's, entirely — and written down.** Tide threads an opaque
1034
- `ctx`; moss's `ActorContext` supplies principal, compiled policy and tenancy. An
1040
+ `actor`, what the host's `actor(as)` returns: principal, compiled policy and tenancy. An
1035
1041
  automation that "runs as root" is unbuildable through this seam, because tide has
1036
1042
  no root to offer. Recording `as` on the run is what lets a host scope the ledger
1037
1043
  without tide learning what it scoped.
@@ -1063,7 +1069,7 @@ The wishlist, answered — including its own open questions:
1063
1069
  | Idempotency before the effect | task insert refused by `UNIQUE(runId, unit)`; task key in `ctx` for downstream |
1064
1070
  | Retry vs terminal | throw vs return (§ decision 6); `retry()` for the parked, and it rewinds the run |
1065
1071
  | Concurrency, overlap, ordering, partial failure, timeout, catch-up | leased claims + fencing, `overlap`, `order: 'serial'` inside the claim, task-per-unit, `timeoutMs`, `catchUp` |
1066
- | Scoped no-session identity, tenant-bounded | `ctx` seam ← moss's `ActorContext`; engine-side enforcement, unchanged |
1072
+ | Scoped no-session identity, tenant-bounded | `actor` seam ← the host's `actor(as)`; engine-side enforcement, unchanged |
1067
1073
  | Run ledger, dry run, preview with names, silence alerting, ledger-as-data | facts/runs/tasks; `preview()`; materialized-ahead pending rows; host-readable tables with a retention policy |
1068
1074
  | Per-tenant config, instant disarm, versioning across runs | reflexes are tenant rows; disarming is the host's row write + `load` (§ decision 11); content-hash versions (§ decision 14) |
1069
1075
  | Host-agnostic wake-up; serverless and local both | `advance({ now })` + `nextDue(now)`: the driver wakes on ingest and sleeps until the next due instant; its janitor beat is recovery, not pacing |
@@ -1071,7 +1077,7 @@ The wishlist, answered — including its own open questions:
1071
1077
  | Durable across restarts | `createTideStore(pool)`, `@niscorp/tide/postgres`; the memory store remains the reference and the check harness |
1072
1078
  | Wishlist: dependency between automations | run facts — `on: { fact: { run: 'A' } }` with `when` on the stats |
1073
1079
  | **Open: one library or two?** | one, standalone — "react to a change" is a fact reflex; same machine |
1074
- | **Open: does the identity belong here?** | no — moss's `ActorContext`, consumed through an opaque seam |
1080
+ | **Open: does the identity belong here?** | no — the host's, consumed through the opaque `actor` seam |
1075
1081
  | **Open: how much effect vocabulary is closed?** | the seam is closed (one shape), the vocabulary is open (registered handlers) |
1076
1082
  | **Open: what does versioning mean?** | content hash pinned by the ledger; `enabled` is the host's field, so pausing isn't a version |
1077
1083
  | **Open: do notifications belong here?** | no — an automation writes rows; whatever notifies is another consumer of rows |
package/DOCS.md CHANGED
@@ -313,7 +313,9 @@ type FactInput = {
313
313
 
314
314
  **The union is enforced end to end.** A `write` needs an `entity`, a `signal` a
315
315
  `name`, a `manual` a `target`, a `run` both `reflex` and `runId` — and each
316
- refuses the fields belonging to the others. `{ kind: 'write' }` with no entity
316
+ refuses the key fields of the others (`entity`, `name`, `target`, `runId`; a
317
+ `signal` also refuses `op`). The rest are not checked by kind: a `write`
318
+ accepts `payload`, `reflex`, `stats` and `by`. `{ kind: 'write' }` with no entity
317
319
  used to parse, store, match nothing, get marked delivered and vanish, with no
318
320
  way for the producer to learn its fact was never going to wake anything.
319
321
 
@@ -442,7 +444,7 @@ the same `now` may create no run. `fired` is `false`, with a `reason`, when
442
444
  throws, a unit key repeats); `true` does not say a run is due.
443
445
 
444
446
  ```typescript
445
- graph(): GraphReport // { edges: { from, to, via }[], cycles, blind, errors, warnings } over what is loaded
447
+ graph(): GraphReport // { edges: { from, to, via }[], cycles, blind, errors, refusals, warnings } over what is loaded
446
448
  sweep(now, retention): Promise<number> // { facts?, runs?, tasks? } horizons in ms
447
449
  ```
448
450
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@niscorp/tide",
3
- "version": "0.1.9",
3
+ "version": "0.1.10",
4
4
  "description": "Host-blind automation engine — a reflex turns the clock and the fact into one named effect, through a durable ledger.",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {
@@ -76,8 +76,8 @@
76
76
  },
77
77
  "peerDependencies": {
78
78
  "zod": "^4.2.0",
79
- "@niscorp/cortex": "^0.1.4",
80
- "@niscorp/strata": "^0.1.7"
79
+ "@niscorp/cortex": "^0.1.6",
80
+ "@niscorp/strata": "^0.1.9"
81
81
  },
82
82
  "devDependencies": {
83
83
  "@electric-sql/pglite": "^0.5.1",
@@ -86,8 +86,8 @@
86
86
  "typescript": "^6.0.2",
87
87
  "vitest": "^4.1.2",
88
88
  "zod": "^4.6.5",
89
- "@niscorp/cortex": "^0.1.4",
90
- "@niscorp/strata": "^0.1.7"
89
+ "@niscorp/strata": "^0.1.9",
90
+ "@niscorp/cortex": "^0.1.6"
91
91
  },
92
92
  "peerDependenciesMeta": {
93
93
  "@niscorp/cortex": {