oracular 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.4.0
+
+### Minor Changes
+
+- [#22](https://github.com/Yuribenjamin/oracular/pull/22) [`0bb5841`](https://github.com/Yuribenjamin/oracular/commit/0bb5841fb93d2f16dcac74601f1ee218b70dda0e) Thanks [@Yuribenjamin](https://github.com/Yuribenjamin)! - Three small ergonomics for writing configs.
+  
+  - **`validateConfig(config)`** runs the checks `createState` and `deserialize` run, without building a state, and returns the normalized copy they would store. It accepts `unknown`, so parsed JSON can be passed as it is; use it to fail fast at startup or in a test.
+  - **`ms`**: `ms.seconds(n)`, `ms.minutes(n)`, `ms.hours(n)`, `ms.days(n)` and `ms.weeks(n)` spell durations in milliseconds, so `halfLife: ms.days(7)` replaces `7 * 24 * 60 * 60 * 1000`. Plain multiplications, nothing else.
+  - **A JSON Schema for the config**, shipped in the package as `oracular/config.schema.json` and served at https://yuribenjamin.github.io/oracular/config.schema.json, for completion and checks on a config kept as JSON. `oracular replay --config file.json` now ignores a top-level `$schema` key, so a file can point at the schema and still be the config the engine runs.
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -250,6 +250,8 @@ createRecord(state, event, { installId, mode }): EventRecord   // one recorder l
 createEndRecord(at, { installId, mode }): EndRecord           // one recorder line: the episode ended
 serialize(state): string
 deserialize(json: string, opts?: { config?: EngineConfig; migrate?: Migrate }): EngineState
+validateConfig(config: unknown): EngineConfig   // the checks createState runs, without a state; returns the normalized copy
+ms.seconds(n), ms.minutes(n), ms.hours(n), ms.days(n), ms.weeks(n)   // durations in milliseconds
 STATE_VERSION // 2
 RECORD_VERSION // 1
 ```
@@ -286,7 +288,7 @@ interface RevealOptions {
 }
 ```
 
-Reveal options resolve per call → intent → engine → defaults. Invalid config throws a `TypeError` or `RangeError` with the offending path in the message.
+Reveal options resolve per call → intent → engine → defaults. Invalid config throws a `TypeError` or `RangeError` with the offending path in the message. `validateConfig(config)` runs those checks without building a state and returns the normalized copy `createState` stores, so a bad weight fails at startup or in a test rather than on first use. For a config kept as JSON, the package ships a [JSON Schema](./schema/config.schema.json) as `oracular/config.schema.json`, also served at <https://yuribenjamin.github.io/oracular/config.schema.json>, for editor completion; `oracular replay` ignores the `$schema` key such a file carries, the engine does not.
 
 ### Results
 
@@ -317,7 +319,7 @@ interface SignalExplanation {
 
 ### Time
 
-`at` is a timestamp. Every duration (`halfLife`, `cooldown`, `episodeTimeout`, `learning.halfLife`) is in the same unit as `at`. Milliseconds from `Date.now()` are the obvious choice, but the library never calls `Date.now()` itself: you pass time in, which keeps every function deterministic and makes tests trivial. A clock that jumps backwards is tolerated (no decay, no error).
+`at` is a timestamp. Every duration (`halfLife`, `cooldown`, `episodeTimeout`, `learning.halfLife`) is in the same unit as `at`. Milliseconds from `Date.now()` are the obvious choice, but the library never calls `Date.now()` itself: you pass time in, which keeps every function deterministic and makes tests trivial. A clock that jumps backwards is tolerated (no decay, no error). When `at` is in milliseconds, `ms.days(7)`, `ms.hours(3)` and `ms.minutes(30)` spell the durations; they are plain multiplications.
 
 ## Persistence
 
@@ -385,7 +387,7 @@ npx oracular replay shadow.ndjson --config oracular.config.json
 
 ## Roadmap
 
-Next is 0.3, themed **proof**: a recorder format for shadow mode, `npx oracular replay` to measure a config offline, per-episode saturation, and state robustness tests. Then cross-episode attribution and `tune` in 0.4, and a written stability policy before 1.0. Framework bindings wait for a third integration. The full list, with the reasoning and what was declined, is on the [roadmap page](https://yuribenjamin.github.io/oracular/guide/roadmap).
+Now is 0.4, themed **learning that matches how people behave**: cross-episode attribution, so a session's signals can earn credit for an outcome days later; `npx oracular tune` to seed a config from a shadow log; presets; and small ergonomics (`validateConfig`, `ms`, a JSON Schema for the config). 0.3 shipped shadow mode, `npx oracular replay` and per-episode saturation. Then a written stability policy before 1.0. Framework bindings wait for a third integration. The full list, with the reasoning and what was declined, is on the [roadmap page](https://yuribenjamin.github.io/oracular/guide/roadmap).
 
 ## Contributing
 

package/dist/cli.js

@@ -7,7 +7,7 @@ import { readFileSync } from "fs";
 import { createRequire } from "module";
 import { extname, resolve } from "path";
 import { pathToFileURL } from "url";
-import { createState as createState2 } from "oracular";
+import { validateConfig } from "oracular";
 
 // cli/log.ts
 import { RECORD_VERSION } from "oracular";
@@ -425,7 +425,8 @@ reveals per user, and a reliability table with a Brier score.
 
 Options:
   --config <file>        the config to replay under: a .json file, or a .js, .mjs or .cjs
-                         module whose default (or \`config\`) export is the config
+                         module whose default (or \`config\`) export is the config. A top-level
+                         "$schema" key in a .json file is ignored
   --thresholds <list>    thresholds to score, comma separated
                          (default: 0.3 to 0.9 by 0.1, plus each intent's configured threshold)
   --window <duration>    how long after a reveal an outcome still counts for it: 3d, 12h, 90m
@@ -544,6 +545,9 @@ async function loadConfig(path, io) {
     } catch (error) {
       throw new Error(`${path}: ${error.message}`);
     }
+    if (typeof value === "object" && value !== null && "$schema" in value) {
+      value = Object.fromEntries(Object.entries(value).filter(([key]) => key !== "$schema"));
+    }
   } else if (ext === ".js" || ext === ".mjs" || ext === ".cjs") {
     const mod = await import(pathToFileURL(path).href);
     value = mod.default ?? mod.config;
@@ -568,7 +572,7 @@ async function replayCommand(argv, io) {
   const config = await loadConfig(configPath, io);
   let declared;
   try {
-    declared = Object.keys(createState2(config).config.intents);
+    declared = Object.keys(validateConfig(config).intents);
   } catch (error) {
     throw new Error(
       `${configPath} is not a valid config: ${error.message.replace(/^oracular: /, "")}`

package/dist/index.cjs

@@ -943,6 +943,20 @@ function reconcile(raw, config) {
   };
 }
 
+// src/units.ts
+var ms = {
+  seconds: (n) => n * 1e3,
+  minutes: (n) => n * 6e4,
+  hours: (n) => n * 36e5,
+  days: (n) => n * 864e5,
+  weeks: (n) => n * 6048e5
+};
+
+// src/validate.ts
+function validateConfig(config) {
+  return normalizeConfig(config);
+}
+
 exports.RECORD_VERSION = RECORD_VERSION;
 exports.STATE_VERSION = STATE_VERSION;
 exports.createEndRecord = createEndRecord;
@@ -955,9 +969,11 @@ exports.evaluate = evaluate;
 exports.evidenceToReveal = evidenceToReveal;
 exports.explain = explain;
 exports.markRevealed = markRevealed;
+exports.ms = ms;
 exports.observe = observe;
 exports.predict = predict;
 exports.serialize = serialize;
 exports.shouldReveal = shouldReveal;
+exports.validateConfig = validateConfig;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map