Skip to content

getting-started.md

Latest commit

 

History

History
134 lines (100 loc) · 3.1 KB

getting-started.md

File metadata and controls

134 lines (100 loc) · 3.1 KB
Raw

Getting Started

git-warp v19 has one root runtime value:

Runtime

Applications write validated Intents to Lanes, run generated Observers, consume Readings, and retain Receipts.

Install

npm install @git-stunts/git-warp

Generate your domain SDK with Wesley and an application-owned renderer. The generated module supplies validated *.intents and *.observers; git-warp owns their execution. The v19 migration guide explains what Wesley owns, installs the pinned compiler, shows the exact two-stage generation scripts and expected files, and runs the small executable users reference.

Open a Runtime and Lane

import { Runtime } from '@git-stunts/git-warp';
import { users } from './users.generated.js';

const runtime = await Runtime.open({
  at: './application-repo',
  writer: 'local',
});

try {
  const lane = await runtime.lane('users');

  const writeReceipt = await lane.write(
    users.intents.registerUser({ subject: 'user:alice' }),
  );

  console.log(writeReceipt.outcome.kind);
} finally {
  await runtime.close();
}

Use a stable writer identity for each independent clone or process that writes to the same Lane.

Write Intents

Each lane.write(intent) admits one validated Intent and returns a WriteReceipt. The closed admission outcomes are:

  • derived
  • plural
  • conflict
  • obstruction

Operational outcomes and epistemic support are separate. Do not infer that an accepted write has settled a strand.

Observe bounded values

Prepare a missing local basis explicitly:

git warp repair \
  --repo ./application-repo \
  --lane users \
  --writer local \
  --action materialization

Then run a generated Observer:

const runtime = await Runtime.open({
  at: './application-repo',
  writer: 'local',
});

try {
  const lane = await runtime.lane('users');
  const observation = lane.observe(
    users.observers.roleOf({ subject: 'user:alice' }),
  );

  const reading = await observation.one();
  const receipt = await observation.receipt;

  console.log(reading.value);
  console.log(receipt.status);
} finally {
  await runtime.close();
}

lane.observe(observer) constructs one dormant Observation synchronously. Iterator demand, convenience methods such as one(), and awaiting receipt share exactly one execution.

For multi-value Observers, consume the Observation as an async iterable:

const observation = lane.observe(
  users.observers.rolesOf({
    subjects: ['user:alice', 'user:bob'],
  }),
);

for await (const reading of observation) {
  console.log(reading.value);
}

console.log((await observation.receipt).status);

Keep Receipts

Receipts are the stable operational record of writes, observations, and settlements. Application code should retain them when it needs auditability, support evidence, or a later diagnostic handoff.

Next steps