3 Commits

Author SHA1 Message Date
John Dvorak 9111c4b20d feat: duration seconds; required fields; type-validated insertions/updates/retrievals
CI / publish (push) Successful in 9s
CI / test (push) Successful in 19s
- Duration literals now accept s/m/h/d/w (was m/h/d/w): 'BEHAVES { ttl 30s }'
  is 30s, and 'within 30s' temporal expressions parse.
- Definition fields are REQUIRED by default ('field: type'); 'field: type?'
  marks a field optional. addNode enforces presence on insert, getSchema
  exposes per-field requiredness, and updateNodeData still validates the
  provided fields' types.
- Provider-returned edges are validated against the fact's declared typing:
  a value-carrying fact must return { value, possibility } with a value of the
  declared type (bare-number shorthand is rejected); a non-value fact must not
  carry a value; and every possibility must lie in [0, 1]. Violations throw a
  clear provider-authoring error instead of silently injecting malformed edges.

Tests: DSLRuntimeTyping (duration units, required-field enforcement, schema
requiredness, value-type + shape + possibility validation).
2026-08-03 16:00:49 -07:00
John Dvorak aa38fbfd8c feat: provider-cache bypass knob; reject non-final comparator chain steps
CI / publish (push) Successful in 9s
CI / test (push) Successful in 18s
- check() gains cacheProviderResults (per-check option + policy default): the
  provider cache is a STORE-RETRIEVAL cache (wall-clock), independent of the
  caller's decision { now }; callers who pin time or want fresh retrieval can
  opt out per-check or globally.
- The generator now rejects a comparator evidence referenced at a NON-final
  chain position (a comparator compares values at (src, candidate) but
  provides no candidate set, so it cannot enumerate intermediate nodes).
  Final-position comparators still lower to condition steps.

Tests: cache bypass (per-check + policy), comparator final OK / intermediate
error.
2026-08-03 15:43:59 -07:00
John Dvorak ad365a65a9 feat: direct fact checks consult registered providers
CI / test (push) Successful in 19s
CI / publish (push) Successful in 9s
Checking a FACT relation directly (rt.check('u:1', 'owns', 'doc:9')) now
runs the provider-retrieval pipeline instead of returning 0 without ever
consulting the registered provider. The retrieval set for a direct fact
check is the fact itself (plus, for evidence checks, the injectable deps as
before). The result reports requiredFacts/providedFacts/missingFacts for the
fact, and missingFacts surfaces 'no_provider' when neither a provider nor an
edge can satisfy the check.
2026-08-03 15:25:33 -07:00
9 changed files with 933 additions and 712 deletions
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "@arbiter/evidence-dsl",
"version": "1.7.0",
"version": "1.10.0",
"description": "Evidence DSL v2 compiler: translates the natural Evidence DSL (ADR-000) into @arbiter/core relation configurations.",
"license": "ISC",
"type": "module",
+9
View File
@@ -1111,6 +1111,15 @@ export class RuleGenerator {
out.push(...this._expandChainSteps(resolved.steps, refStack));
continue;
}
if (resolved.type === 'relational_comparator' && idx !== steps.length - 1) {
// A comparator compares values at (src, candidate) but provides no
// candidate set — it cannot enumerate intermediate nodes, so only
// a FINAL comparator step (verified at the known object) lowers.
this.errors.push(`Chain step '${stepName}' references a comparator evidence at a non-final position. ` +
'Comparators can only be the final chain step (the object is known); intermediate positions are not enumerable.');
out.push(step);
continue;
}
// Condition step: inline the evidence's config as a rule step. As the
// FINAL step the engine verifies it at (intermediate, object); as an
// INTERMEDIATE step the engine EXPANDS it from the current node
+5 -2
View File
@@ -54,11 +54,14 @@ Definition "A type definition"
}
Field
= name:Identifier _ ":" _ fieldType:Type _ isArray:("[]")? _ behavior:Behavior? _ cache:CacheDirective? {
= name:Identifier _ ":" _ fieldType:Type optional:("?")? _ isArray:("[]")? _ behavior:Behavior? _ cache:CacheDirective? {
return {
type: "Field",
name,
fieldType,
// `field: type` is REQUIRED on node insert; `field: type?` is optional.
// Presence is enforced by the DSLRuntime when a node is created.
required: !optional,
isArray: !!isArray,
behavior: behavior || null,
cache: cache || null
@@ -392,7 +395,7 @@ Boolean "A boolean literal"
= value:("true" / "false") { return { type: "Literal", value: value === "true" }; }
Duration "A time duration literal"
= value:([0-9]+ ("h" / "d" / "w" / "m")) { return { type: "Literal", value: text(), unit: text().slice(-1) }; }
= value:([0-9]+ ("s" / "m" / "h" / "d" / "w")) { return { type: "Literal", value: text(), unit: text().slice(-1) }; }
// -- Core Tokens & Whitespace --
File diff suppressed because it is too large Load Diff
+72 -22
View File
@@ -60,6 +60,12 @@ export class DSLRuntime {
this.clock = typeof options.clock === 'function' ? options.clock : (() => Date.now());
// Default provider-result TTL in ms (0 disables caching).
this.defaultProviderCacheTTL = options.policy?.providerCacheTTL ?? options.providerCacheTTL ?? 30_000;
// Provider caching is a STORE-RETRIEVAL cache (wall-clock), deliberately
// independent of the caller's decision `{ now }` — a provider returns the
// store's current data, not a time-travel snapshot. Callers who pin time
// or otherwise want fresh retrieval can disable it per-check
// (options.cacheProviderResults: false) or globally (policy).
this.cacheProviderResults = options.policy?.cacheProviderResults ?? options.cacheProviderResults ?? true;
// Per-fact overrides (ms). DSL-declared ttl behaviors are indexed here too.
this.factTTLs = new Map(Object.entries(options.factTTLs || {}));
}
@@ -97,7 +103,8 @@ export class DSLRuntime {
fields: [...fields.entries()].map(([fieldName, f]) => ({
name: fieldName,
type: f.type,
isArray: f.isArray
isArray: f.isArray,
required: f.required !== false
}))
}));
const facts = [...this.relations.entries()]
@@ -126,7 +133,7 @@ export class DSLRuntime {
for (const def of this.program.definitions || []) {
const fields = new Map();
for (const field of def.fields || []) {
fields.set(field.name, { type: field.fieldType, isArray: !!field.isArray });
fields.set(field.name, { type: field.fieldType, isArray: !!field.isArray, required: field.required !== false });
}
this.types.set(def.name, { fields });
}
@@ -296,7 +303,7 @@ export class DSLRuntime {
const b = behavior.behavior || behavior;
if (b && b.behaviorType === 'ttl' && b.duration) {
const n = parseInt(String(b.duration.value), 10);
const mult = { h: 3600_000, d: 86_400_000, w: 604_800_000, m: 60_000 }[b.duration.unit];
const mult = { s: 1000, m: 60_000, h: 3600_000, d: 86_400_000, w: 604_800_000 }[b.duration.unit];
if (!Number.isNaN(n) && mult) return n * mult;
}
return null;
@@ -307,30 +314,59 @@ export class DSLRuntime {
* array of edge objects) into an array of partial-graph edge objects. The
* destination follows the DSL fact's declared shape: unary and value-carrying
* facts are self-edges on the subject; binary entity facts go subject object.
* Provider-returned edges are validated against the fact's declared typing:
* a value-carrying fact must return an object with a value of the declared
* type, and possibilities must be in [0, 1]. A violation throws it is a
* provider-authoring error, not a denial.
*/
_normalizeProviderEdges(result, factMeta, user, object) {
_normalizeProviderEdges(result, factMeta, fact, user, object) {
const edges = Array.isArray(result) ? result : [result];
const secondParamType = factMeta.params[1] && factMeta.params[1].type;
const defaultDst = factMeta.params.length >= 2 && this._isValueType(secondParamType)
? user
: (factMeta.params.length >= 2 ? object : user);
const isValueFact = factMeta.params.length >= 2 && this._isValueType(secondParamType);
const defaultDst = isValueFact ? user : (factMeta.params.length >= 2 ? object : user);
const label = `provider for '${fact}'`;
const out = [];
for (const edge of edges) {
const normalized = typeof edge === 'boolean' || typeof edge === 'number'
? { src: user, dst: defaultDst, possibility: edge === true ? 1 : edge }
: {
...(edge.relation ? { relation: edge.relation } : {}),
src: edge.src ?? user,
dst: edge.dst ?? defaultDst,
possibility: edge.possibility ?? 1,
...(edge.value !== undefined ? { value: edge.value } : {}),
...(edge.reliability !== undefined ? { reliability: edge.reliability } : {})
};
? (() => {
if (isValueFact) {
throw new Error(`DSLRuntime: ${label} is a value-carrying fact — return { value, possibility } (got a bare ${typeof edge === 'number' ? 'number' : 'boolean'})`);
}
const possibility = edge === true ? 1 : edge;
this._checkPossibility(possibility, label);
return { src: user, dst: defaultDst, possibility };
})()
: (() => {
const possibility = edge.possibility ?? 1;
this._checkPossibility(possibility, label);
if (edge.value !== undefined) {
if (!isValueFact) {
throw new Error(`DSLRuntime: ${label} returned a value for a non-value fact '${fact}'`);
}
this._checkScalarValue(secondParamType, edge.value, `${label}.value`);
} else if (isValueFact) {
throw new Error(`DSLRuntime: ${label} must supply a 'value' of type ${secondParamType}`);
}
return {
...(edge.relation ? { relation: edge.relation } : {}),
src: edge.src ?? user,
dst: edge.dst ?? defaultDst,
possibility,
...(edge.value !== undefined ? { value: edge.value } : {}),
...(edge.reliability !== undefined ? { reliability: edge.reliability } : {})
};
})();
out.push(normalized);
}
return out;
}
_checkPossibility(possibility, label) {
if (typeof possibility !== 'number' || !Number.isFinite(possibility) || possibility < 0 || possibility > 1) {
throw new Error(`DSLRuntime: ${label} returned invalid possibility ${possibility} (expected a number in [0, 1])`);
}
}
// ---------------------------------------------------------------------------
// Schema validation helpers
// ---------------------------------------------------------------------------
@@ -399,6 +435,11 @@ export class DSLRuntime {
if (this.types.has(typeName)) {
const { fields } = this.types.get(typeName);
for (const [name, field] of fields) {
// Required fields must be present on insert (`field: type` in the DSL;
// `field?: type` marks a field optional).
if (field.required && data[name] === undefined) {
throw new Error(`DSLRuntime: missing required field '${typeName}.${name}' on node insert`);
}
if (data[name] !== undefined) this._checkFieldValue(field, data[name], `${typeName}.${name}`);
}
} else if (this.strictTypes) {
@@ -559,7 +600,13 @@ export class DSLRuntime {
this._checkNodeType(user, meta.params[0].type, 'subject');
}
const required = this.requiredFacts(relation);
// Retrieval set: for an evidence, the injectable facts it depends on; for
// a direct FACT check, the fact itself is the retrieval target (its
// provider, if registered, supplies the edge — checking `owns` directly
// must consult the `owns` provider, not only evidence-mediated checks).
const required = new Set(this.requiredFacts(relation));
if (meta && meta.kind === 'fact') required.add(relation);
const requiredList = [...required];
const providers = { ...this.factProviders, ...(options.factProviders || {}) };
const maxRounds = options.maxProviderRounds ?? 3;
const partialRelations = [];
@@ -577,7 +624,7 @@ export class DSLRuntime {
// Fixed-point provider retrieval loop.
for (let round = 1; round <= maxRounds; round++) {
let newRelationsThisRound = 0;
for (const fact of required) {
for (const fact of requiredList) {
if (satisfied.has(fact)) continue;
const factMeta = this.relations.get(fact);
const provider = providers[fact];
@@ -587,8 +634,11 @@ export class DSLRuntime {
// provider overrides are one-off observations — they bypass the cache
// entirely (no read, no write) so a fresh override is never masked by
// a cached registered-provider result, nor does it pollute the cache.
// options.cacheProviderResults:false (or the policy default) disables
// the cache for this check.
const cachingEnabled = options.cacheProviderResults ?? this.cacheProviderResults;
const isPerCheckOverride = !!(options.factProviders && fact in options.factProviders);
const cacheHit = isPerCheckOverride ? null : this._providerCacheGet(fact, user, object);
const cacheHit = (cachingEnabled && !isPerCheckOverride) ? this._providerCacheGet(fact, user, object) : null;
let edges = null;
let fromCache = false;
if (cacheHit) {
@@ -619,8 +669,8 @@ export class DSLRuntime {
satisfied.add(fact);
continue;
}
edges = this._normalizeProviderEdges(result, factMeta, user, object);
if (!isPerCheckOverride) this._providerCacheSet(fact, user, object, edges);
edges = this._normalizeProviderEdges(result, factMeta, fact, user, object);
if (cachingEnabled && !isPerCheckOverride) this._providerCacheSet(fact, user, object, edges);
} else {
missingFacts.push({ relation: fact, reason: 'no_provider' });
satisfied.add(fact);
@@ -653,7 +703,7 @@ export class DSLRuntime {
return {
...result,
requiredFacts: required,
requiredFacts: requiredList,
providedFacts: injectedRelations.map(r => r.relation),
missingFacts
};
+8 -8
View File
@@ -20,9 +20,9 @@ import { Arbiter } from '@arbiter/core';
import { DSLRuntime } from '../src/runtime/DSLRuntime.js';
const BASE_DSL = `
definition Employee { id: string level: number active: boolean }
definition Group { id: string }
definition Doc { id: string }
definition Employee { id: string? level: number? active: boolean? }
definition Group { id: string? }
definition Doc { id: string? }
fact member_of(user: Employee, group: Group)
fact *owns(user: Employee, doc: Doc)
fact *user_score(user: Employee, value: number)
@@ -164,8 +164,8 @@ describe('DSLRuntime', () => {
it('derives transitive required facts through evidence composition', async () => {
const dsl = `
definition Employee { id: string }
definition Doc { id: string }
definition Employee { id: string? }
definition Doc { id: string? }
fact *owns(user: Employee, doc: Doc)
fact *banned(user: Employee)
evidence can_read(user: Employee, doc: Doc) { owns(user, doc) }
@@ -191,9 +191,9 @@ describe('DSLRuntime', () => {
it('derives transitive required facts through a condition-step chain', () => {
const dsl = `
definition Employee { id: string }
definition Group { id: string }
definition Doc { id: string }
definition Employee { id: string? }
definition Group { id: string? }
definition Doc { id: string? }
fact *member_of(user: Employee, group: Group)
fact *can_view(group: Group, doc: Doc)
fact *banned(group: Group)
+33 -6
View File
@@ -14,8 +14,8 @@ import { Arbiter } from '@arbiter/core';
import { DSLRuntime } from '../src/runtime/DSLRuntime.js';
const BASE_DSL = `
definition Employee { id: string }
definition Doc { id: string }
definition Employee { id: string? }
definition Doc { id: string? }
fact *owns(user: Employee, doc: Doc)
evidence can_read(user: Employee, doc: Doc) { owns(user, doc) }
`;
@@ -102,8 +102,8 @@ describe('DSLRuntime provider-result caching', () => {
it('invalidateProviderCache() clears all or per relation', async () => {
const dsl = `
definition Employee { id: string }
definition Doc { id: string }
definition Employee { id: string? }
definition Doc { id: string? }
fact *owns(user: Employee, doc: Doc)
fact *banned(user: Employee)
evidence can_read(user: Employee, doc: Doc) { owns(user, doc) }
@@ -151,8 +151,8 @@ describe('DSLRuntime provider-result caching', () => {
it('uses the DSL-declared fact TTL (BEHAVES { ttl X })', async () => {
const dsl = `
definition Employee { id: string }
definition Doc { id: string }
definition Employee { id: string? }
definition Doc { id: string? }
fact *balance(user: Employee, amount: number) BEHAVES { ttl 1h }
evidence can_spend(user: Employee, doc: Doc) { balance(user, 1) }
`;
@@ -173,4 +173,31 @@ describe('DSLRuntime provider-result caching', () => {
await rt.check('u:1', 'can_spend', 'doc:9');
assert.equal(calls, 2, 're-invoked past the DSL-declared 1h TTL');
});
it('cacheProviderResults:false bypasses the cache per check', async () => {
const rt = makeRuntime();
rt.addNode('u:1', 'Employee', {});
rt.addNode('doc:9', 'Doc', {});
let calls = 0;
rt.registerFact('owns', async () => { calls++; return 0.9; });
await rt.check('u:1', 'can_read', 'doc:9');
assert.equal(calls, 1);
// Bypass forces a fresh retrieval without clearing the cache.
await rt.check('u:1', 'can_read', 'doc:9', { cacheProviderResults: false });
assert.equal(calls, 2);
// Cache still intact for the next default check.
await rt.check('u:1', 'can_read', 'doc:9');
assert.equal(calls, 2);
});
it('policy.cacheProviderResults:false disables caching globally', async () => {
const rt = makeRuntime({ policy: { cacheProviderResults: false } });
rt.addNode('u:1', 'Employee', {});
rt.addNode('doc:9', 'Doc', {});
let calls = 0;
rt.registerFact('owns', async () => { calls++; return 0.9; });
await rt.check('u:1', 'can_read', 'doc:9');
await rt.check('u:1', 'can_read', 'doc:9');
assert.equal(calls, 2, 'no caching when disabled globally');
});
});
+25 -4
View File
@@ -14,8 +14,8 @@ import { Arbiter } from '@arbiter/core';
import { DSLRuntime } from '../src/runtime/DSLRuntime.js';
const BASE_DSL = `
definition Employee { id: string level: number active: boolean }
definition Doc { id: string created: timestamp }
definition Employee { id: string? level: number? active: boolean? }
definition Doc { id: string? created: timestamp? }
fact *owns(user: Employee, doc: Doc)
fact *banned(user: Employee)
evidence can_read(user: Employee, doc: Doc) { owns(user, doc) }
@@ -73,8 +73,8 @@ describe('DSLRuntime extended', () => {
// edge for a DIFFERENT injectable fact that can_open also requires via
// composition — here we add a transitive requirement to prove the loop.
const dsl = `
definition Employee { id: string }
definition Doc { id: string }
definition Employee { id: string? }
definition Doc { id: string? }
fact *owns(user: Employee, doc: Doc)
fact *granted(user: Employee, doc: Doc)
evidence base_read(user: Employee, doc: Doc) { owns(user, doc) }
@@ -144,4 +144,25 @@ describe('DSLRuntime extended', () => {
rt.updateNodeData('doc:9', { created: '2026-08-03T00:00:00Z' });
assert.throws(() => rt.addNode('doc:8', 'Doc', { created: {} }), /must be timestamp/);
});
it('direct FACT checks consult the registered provider', async () => {
const rt = makeRuntime();
rt.addNode('u:1', 'Employee', {});
rt.addNode('doc:9', 'Doc', {});
let calls = 0;
rt.registerFact('owns', async () => { calls++; return 0.9; });
// Checking the fact directly (not via an evidence) must retrieve it.
const res = await rt.check('u:1', 'owns', 'doc:9');
assert.equal(res.possibility, 0.9);
assert.equal(calls, 1);
assert.deepEqual(res.requiredFacts, ['owns']);
assert.deepEqual(res.providedFacts, ['owns']);
// Without a provider and without an edge, it reports the missing fact.
const rt2 = new DSLRuntime(new Arbiter()).compile(BASE_DSL, 'rt-fact-miss');
rt2.addNode('u:1', 'Employee', {});
rt2.addNode('doc:9', 'Doc', {});
const missed = await rt2.check('u:1', 'owns', 'doc:9');
assert.equal(missed.possibility, 0);
assert.deepEqual(missed.missingFacts, [{ relation: 'owns', reason: 'no_provider' }]);
});
});
+96
View File
@@ -0,0 +1,96 @@
/**
* tests/DSLRuntimeTyping.test.js duration seconds, required fields, and
* type validation of insertions / updates / provider retrievals.
*
* - Duration literals now accept s/m/h/d/w: `BEHAVES { ttl 30s }` is 30s.
* - Definition fields are REQUIRED by default (`field: type`); `field: type?`
* marks a field optional. addNode enforces presence on insert.
* - Provider-returned edges are validated against the fact's declared typing:
* a value-carrying fact must return { value, possibility } with a value of
* the declared type, and possibilities must lie in [0, 1].
*/
import { describe, it } from 'node:test';
import assert from 'node:assert/strict';
import { Arbiter } from '@arbiter/core';
import { DSLRuntime } from '../src/runtime/DSLRuntime.js';
describe('DSLRuntime typing', () => {
it('accepts seconds/minutes/hours/days/weeks in duration literals', async () => {
const dsl = `
definition Employee { id: string? }
definition Doc { id: string? }
fact *a(user: Employee, amount: number) BEHAVES { ttl 30s }
fact *b(user: Employee, amount: number) BEHAVES { ttl 2m }
fact *c(user: Employee, amount: number) BEHAVES { ttl 1h }
fact *d(user: Employee, amount: number) BEHAVES { ttl 3d }
fact *e(user: Employee, amount: number) BEHAVES { ttl 1w }
`;
const rt = new DSLRuntime(new Arbiter()).compile(dsl, 'rt-units');
assert.equal(rt.relations.get('a').ttlMs, 30_000);
assert.equal(rt.relations.get('b').ttlMs, 120_000);
assert.equal(rt.relations.get('c').ttlMs, 3_600_000);
assert.equal(rt.relations.get('d').ttlMs, 259_200_000);
assert.equal(rt.relations.get('e').ttlMs, 604_800_000);
});
it('enforces required definition fields on node insert', () => {
const rt = new DSLRuntime(new Arbiter()).compile(`
definition Employee { id: string level: number active: boolean? }
`, 'rt-req');
// id and level are required (no `?`); active is optional.
assert.throws(() => rt.addNode('u:1', 'Employee', { level: 3 }), /missing required field 'Employee.id'/);
assert.throws(() => rt.addNode('u:2', 'Employee', { id: 'u:2' }), /missing required field 'Employee.level'/);
rt.addNode('u:3', 'Employee', { id: 'u:3', level: 5 }); // both required, no active -> ok
rt.addNode('u:4', 'Employee', { id: 'u:4', level: 5, active: true });
});
it('exposes requiredness in the schema snapshot', () => {
const rt = new DSLRuntime(new Arbiter()).compile(`
definition Employee { id: string level: number? }
`, 'rt-schema-req');
const employee = rt.getSchema().types.find(t => t.name === 'Employee');
assert.equal(employee.fields.find(f => f.name === 'id').required, true);
assert.equal(employee.fields.find(f => f.name === 'level').required, false);
});
it('validates a provider-returned value against the declared value type', async () => {
const rt = new DSLRuntime(new Arbiter()).compile(`
definition Employee { id: string? }
definition Doc { id: string? }
fact *balance(user: Employee, amount: number)
evidence can_spend(user: Employee, doc: Doc) { balance(user, 1) }
`, 'rt-valuetype');
rt.addNode('u:1', 'Employee', {});
rt.addNode('doc:9', 'Doc', {});
rt.registerFact('balance', async () => ({ possibility: 1.0, value: 'high' }));
await assert.rejects(() => rt.check('u:1', 'can_spend', 'doc:9'), /must be number/);
});
it('requires a value for a value-carrying fact (no bare-number shorthand)', async () => {
const rt = new DSLRuntime(new Arbiter()).compile(`
definition Employee { id: string? }
definition Doc { id: string? }
fact *balance(user: Employee, amount: number)
evidence can_spend(user: Employee, doc: Doc) { balance(user, 1) }
`, 'rt-valshape');
rt.addNode('u:1', 'Employee', {});
rt.addNode('doc:9', 'Doc', {});
rt.registerFact('balance', async () => 0.9);
await assert.rejects(() => rt.check('u:1', 'can_spend', 'doc:9'), /value-carrying fact/);
rt.registerFact('balance', async () => ({ possibility: 1.0 })); // missing value
await assert.rejects(() => rt.check('u:1', 'can_spend', 'doc:9'), /must supply a 'value'/);
});
it('rejects a provider-returned possibility outside [0, 1]', async () => {
const rt = new DSLRuntime(new Arbiter()).compile(`
definition Employee { id: string? }
definition Doc { id: string? }
fact *owns(user: Employee, doc: Doc)
evidence can_read(user: Employee, doc: Doc) { owns(user, doc) }
`, 'rt-poss');
rt.addNode('u:1', 'Employee', {});
rt.addNode('doc:9', 'Doc', {});
rt.registerFact('owns', async () => ({ possibility: 2.0 }));
await assert.rejects(() => rt.check('u:1', 'can_read', 'doc:9'), /invalid possibility/);
});
});