Saved documentation for 0.1.0-alpha.1 (npm) / 0.1.0a0 (PyPI). Interactive tools use the current release. View latest documentation.

Quickstart

Install from the registries

Node 22+ and Python 3.11+ are supported. Install the published pre-alpha packages with npm install agindow@0.1.0-alpha.1 or pip install agindow==0.1.0a0. No hosted key is required. Installing the SDK alone does not detect drift. Configure a detector with baseline/live data windows. Monorepo contributors still build the shared WASM guest with the Rust target and wasm-bindgen CLI 0.2.129 when changing the engine. See Modes for the separate detector and mode setup requirements.

Detector setup and modes ↗

Detect a labelled simulated change

After npm install agindow@0.1.0-alpha.1, save the TypeScript sample below as detect.mts and run node --experimental-strip-types detect.mts. Prerequisites: Node.js 22+, a clean directory, and network access only to install the published package — no monorepo, Rust/WASM toolchain, hosted keys, vendor credentials, live vendor traffic or paid services. The sample selects an explicit statistical window, awaits readiness, and reports a real Unit finding for a labelled numeric magnitude shift (baseline value 1 → live value 100). An otherwise identical unchanged live window, a default engine with no selection, and insufficient windows report no detection. The printed JSON is the stable finding summary; latencyUs and host timing vary. This is observe-mode detection evidence, not an applied repair, not a bypass event, and not evidence of production accuracy.

pnpm install --frozen-lockfile
rustup target add wasm32-unknown-unknown
cargo install wasm-bindgen-cli --version 0.2.129 --locked
node cells/cell-relay/node/scripts/build.mjs
python3 cells/cell-relay/python/scripts/build.py --stage-only
uv sync --directory cells/cell-relay/python --frozen

Availability and identity fixtures

The separately labelled ts/py examples below run a synthetic local read and an explicitly unavailable or closed-engine fixture. They assert return identity and one bypass event. They are availability fixtures, not detection. Use the language tab that matches your install, then run the sample with node --experimental-strip-types example.ts or python example.py.

import { createAgindow } from 'agindow';
import type { Event, StatisticalSelection } from 'agindow';

/** Labelled simulated break: numeric magnitude shift (1 → 100). Not a vendor migration story. */
const documents = (value: number): string[] =>
  Array.from({ length: 128 }, () => JSON.stringify({ value }));

function selectionFor(live: number): StatisticalSelection {
  return {
    tenant: 'demo',
    connection: 'local',
    vendor: 'synthetic',
    operation: 'demo.detect',
    segment: 'default',
    fields: [{
      side: 'request',
      path: '/value',
      baseline: documents(1),
      live: documents(live),
      enumeration: true,
    }],
  };
}

async function observe(label: string, selection?: StatisticalSelection, bodyValue = 100): Promise<readonly Event[]> {
  const sdk = createAgindow(selection === undefined
    ? { mode: 'observe' }
    : { mode: 'observe', selection });
  await sdk.ready;
  const body = { value: bodyValue };
  const result = sdk.guard((input: { value: number }) => input, {
    tool: 'demo.detect',
    operation: 'read',
  })(body);
  if (result !== body) throw Error(`${label}: observe mutated the result (not an applied repair path)`);
  if (sdk.recent().some((event: Event) => event.type === 'repair')) {
    throw Error(`${label}: unexpected repair event`);
  }
  if (sdk.recent().some((event: Event) => event.type === 'bypass')) {
    throw Error(`${label}: unexpected bypass; this sample is detection, not an availability fixture`);
  }
  return sdk.recent();
}

const changed = await observe('changed', selectionFor(100), 100);
const drift = changed.find((event: Event) => event.type === 'drift');
if (!drift?.verdict
  || drift.verdict.bypassed
  || drift.verdict.halt
  || drift.verdict.repair
  || drift.verdict.findings !== 1
  || drift.verdict.detectors !== 5
  || drift.verdict.class !== 'semantic'
  || !drift.verdict.eligibleDetectors?.includes('Unit')) {
  throw Error('expected a real Unit finding for the labelled numeric magnitude shift');
}

const unchanged = await observe('unchanged', selectionFor(1), 1);
if (unchanged.some((event: Event) => event.type === 'drift')) {
  throw Error('unchanged live window reported drift');
}

const withoutDetector = await observe('default');
if (withoutDetector.some((event: Event) => event.type === 'drift')) {
  throw Error('default engine reported detection without an explicit selection');
}

const insufficient: StatisticalSelection = {
  tenant: 'demo',
  connection: 'local',
  vendor: 'synthetic',
  operation: 'demo.detect',
  segment: 'default',
  fields: [{
    side: 'request',
    path: '/value',
    baseline: Array.from({ length: 4 }, () => '{"value":1}'),
    live: Array.from({ length: 4 }, () => '{"value":100}'),
    enumeration: true,
  }],
};
const thin = await observe('insufficient', insufficient, 100);
if (thin.some((event: Event) => event.type === 'drift')) {
  throw Error('insufficient windows reported a successful detection');
}

const observed = {
  labelledChange: 'numeric magnitude shift',
  detector: drift.verdict.eligibleDetectors.find(name => name === 'Unit'),
  event: drift.type,
  findings: drift.verdict.findings,
  detectors: drift.verdict.detectors,
  eligibleDetectors: drift.verdict.eligibleDetectors,
  class: drift.verdict.class,
  bypassed: Boolean(drift.verdict.bypassed),
  halt: Boolean(drift.verdict.halt),
  repairApplied: Boolean(drift.verdict.repair),
  resultUnchanged: true, // observe() checked reference identity above.
};
console.log(JSON.stringify(observed, null, 2));
console.log('Variable per run (not part of the stable finding above): latencyUs and host timing.');

Read the first outcome

Inspect sdk.recent() or subscribe with sdk.on. A drift event with findings is detection evidence; bypass is an availability event and leaves the result body unchanged. A healthy default engine can return no findings without proving drift safety. Audit artifact production requires explicit audit options and a host drain; missing artifact IDs must stay unavailable.

Specification

Read the published modes guide and the guard loop.

import { createAgindow } from 'agindow';
const sdk = createAgindow({ mode: 'observe' });
await sdk.ready;
const payload = { id: 'synthetic-customer' };
let calls = 0;
const read = sdk.guard(() => { calls++; return payload; }, { tool: 'vendor.read', operation: 'read' });
const result = read();
if (result !== payload || calls !== 1) throw Error('Fixture identity changed');
// A labelled unavailable-engine fixture produces one bypass without a hosted key.
const unavailable = createAgindow({ mode: 'observe' }, async () => { throw Error('Synthetic loading fault'); });
await unavailable.ready;
const fallback = unavailable.wrap(() => payload);
if (fallback() !== payload || unavailable.recent().filter(e => e.type === 'bypass').length !== 1) throw Error('Missing bypass');
sdk.configure({ mode: 'observe' });
console.log('Synthetic fixture: original result retained; unavailable engine bypassed once.');

import asyncio
from agindow import Agindow
sdk = Agindow(mode="observe")
payload = {"id": "synthetic-customer"}
@sdk.guard(tool="vendor.read", operation="read")
def read() -> dict[str, str]:
    return payload
@sdk.guard(tool="vendor.read", operation="read")
async def read_async() -> dict[str, str]:
    return payload
with sdk.context(mode="observe"):
    assert read() is payload
async def main() -> None:
    async with sdk.context(mode="observe"):
        assert await read_async() is payload
asyncio.run(main())
# A closed engine is a labelled availability fixture, not vendor drift.
sdk.close()
assert read() is payload
assert len([event for event in sdk.recent() if event.type == "bypass"]) == 1
print("Synthetic fixture: sync/async identity retained; closed engine bypassed once.")