@boxxy/dispatch 0.1.1 → 0.1.3

package/src/closeouts/build-settle-plans.ts

@@ -0,0 +1,173 @@
+import { dedupeOpenItems } from '@boxxy/closeout';
+import type { Effect, ItemId, ItemView, OpenItem, WorkFacts } from '@boxxy/model';
+import { match } from 'ts-pattern';
+import { effectHandlers } from './effect-handlers.ts';
+import type { EffectContext, EffectPlan } from './types.ts';
+
+type SettledFact = WorkFacts['boxxy.attempt.settled'];
+
+interface SettlePlansInput {
+  readonly effects: readonly Effect[];
+  readonly ctx: EffectContext;
+
+  // the open `core.issue` items of the item's repo, for the dedupe of filed items
+  readonly openIssues: readonly ItemView[];
+
+  // the rules map the outcome to a `{ hold: reason }` edge
+  readonly held: boolean;
+}
+
+export interface SettlePlans {
+  readonly plans: readonly EffectPlan[];
+  readonly criteria: SettledFact['criteria'];
+  readonly matched: readonly ItemId[];
+  readonly skippedEffects: SettledFact['skippedEffects'];
+}
+
+// The plan of each effect of a settle, and the `settled` fact's fields that the plans decide.
+// A hold withholds each effect that changes an existing item. Each plan sees what the plans
+// before it write, so a repeated effect skips instead of breaking a key of the store.
+export function buildSettlePlans(input: SettlePlansInput): SettlePlans {
+  const fileItems = input.effects.flatMap((effect) =>
+    effect.kind === 'file-item' ? [effect.item] : [],
+  );
+
+  const deduped = dedupeOpenItems(fileItems, input.openIssues);
+
+  const toFile = new Set(deduped.file);
+
+  // with no open issues to match, the dedupe keeps the first entry of each title
+  const firsts = new Set(dedupeOpenItems(fileItems, []).file);
+  const repeats = new Set(fileItems.filter((entry) => !firsts.has(entry)));
+
+  const effects = input.effects
+    .filter(
+      (effect) =>
+        effect.kind !== 'file-item' || toFile.has(effect.item) || repeats.has(effect.item),
+    )
+
+    // each item update expects the item open, so the close goes last
+    .toSorted(
+      (first, second) => Number(first.kind === 'close-item') - Number(second.kind === 'close-item'),
+    );
+
+  const plans = collectPlans(effects, input, repeats);
+
+  return {
+    plans,
+    criteria: collectCopiedEvidence(plans, input.ctx.item),
+    matched: deduped.matched,
+    skippedEffects: plans.flatMap((plan) =>
+      plan.kind === 'skip' ? [{ effect: plan.effect.kind, reason: plan.reason }] : [],
+    ),
+  };
+}
+
+function collectPlans(
+  effects: readonly Effect[],
+  input: SettlePlansInput,
+  repeats: ReadonlySet<OpenItem>,
+): EffectPlan[] {
+  const plans: EffectPlan[] = [];
+  let ctx = input.ctx;
+
+  for (const effect of effects) {
+    const reason = findSkipReason(effect, input.held, repeats);
+
+    const plan: EffectPlan =
+      reason === null ? planEffect(effect, ctx) : { kind: 'skip', effect, reason };
+
+    plans.push(plan);
+
+    ctx = buildPlannedContext(ctx, plan);
+  }
+
+  return plans;
+}
+
+function findSkipReason(
+  effect: Effect,
+  held: boolean,
+  repeats: ReadonlySet<OpenItem>,
+): string | null {
+  if (effect.kind === 'file-item' && repeats.has(effect.item)) {
+    return 'the close-out names this title already';
+  }
+
+  return held && isItemChange(effect) ? 'the item holds for the owner' : null;
+}
+
+const itemChanges: ReadonlySet<Effect['kind']> = new Set([
+  'close-item',
+  'add-relation',
+  'set-kind',
+  'set-field',
+  'set-acceptance',
+]);
+
+function isItemChange(effect: Effect): boolean {
+  return itemChanges.has(effect.kind);
+}
+
+// A handler that throws is a bug in the handler, not in the stored data, but the settle still
+// lands: the effect is skipped and listed.
+function planEffect(effect: Effect, ctx: EffectContext): EffectPlan {
+  try {
+    return pickHandler(effect)(ctx);
+  } catch (error) {
+    return { kind: 'skip', effect, reason: `the handler failed: ${String(error)}` };
+  }
+}
+
+function pickHandler(effect: Effect): (ctx: EffectContext) => EffectPlan {
+  return match(effect)
+    .returnType<(ctx: EffectContext) => EffectPlan>()
+    .with({ kind: 'file-item' }, (filed) => (ctx) => effectHandlers['file-item'](filed, ctx))
+    .with({ kind: 'close-item' }, (close) => (ctx) => effectHandlers['close-item'](close, ctx))
+    .with({ kind: 'add-relation' }, (add) => (ctx) => effectHandlers['add-relation'](add, ctx))
+    .with({ kind: 'set-kind' }, (set) => (ctx) => effectHandlers['set-kind'](set, ctx))
+    .with({ kind: 'set-field' }, (set) => (ctx) => effectHandlers['set-field'](set, ctx))
+    .with({ kind: 'set-acceptance' }, (set) => (ctx) => effectHandlers['set-acceptance'](set, ctx))
+    .with(
+      { kind: 'record-proposal' },
+      (record) => (ctx) => effectHandlers['record-proposal'](record, ctx),
+    )
+    .exhaustive();
+}
+
+// The context as the store will hold it after the plan's writes.
+function buildPlannedContext(ctx: EffectContext, plan: EffectPlan): EffectContext {
+  if (plan.kind === 'skip') {
+    return ctx;
+  }
+
+  const added = plan.writes.flatMap((write) =>
+    write.op === 'insert' && write.table === 'relations' ? [write.row] : [],
+  );
+
+  return {
+    ...ctx,
+    item: plan.effect.kind === 'close-item' ? { ...ctx.item, closedAt: ctx.now } : ctx.item,
+    relations: [...ctx.relations, ...added],
+  };
+}
+
+// The evidence ids that an applied `set-acceptance` added to each criterion.
+function collectCopiedEvidence(
+  plans: readonly EffectPlan[],
+  item: ItemView,
+): SettledFact['criteria'] {
+  return plans.flatMap((plan) => {
+    if (plan.kind !== 'apply' || plan.effect.kind !== 'set-acceptance') {
+      return [];
+    }
+
+    return plan.effect.criteria.flatMap((criterion) => {
+      const before = new Set(item.acceptance.find((old) => old.id === criterion.id)?.evidence);
+
+      const added = criterion.evidence.filter((evidence) => !before.has(evidence));
+
+      return added.length === 0 ? [] : [{ criterion: criterion.id, evidence: added }];
+    });
+  });
+}

package/src/closeouts/close-out-attempt.ts

@@ -0,0 +1,156 @@
+import type { ContentHash } from '@boxxy/content-hash';
+import { contentHash } from '@boxxy/content-hash';
+import type {
+  AttemptRow,
+  CloseOutAnswer,
+  CloseOutContext,
+  FactId,
+  LoadedRules,
+  StoreChange,
+  StoreTx,
+} from '@boxxy/model';
+import { closeOutSchema, toJSONValue } from '@boxxy/model';
+import invariant from 'tiny-invariant';
+import { buildAttemptChange } from '../attempts/build-attempt-change.ts';
+import { pickCallAttempt } from '../attempts/pick-call-attempt.ts';
+import type { CloseOutInput } from './types.ts';
+
+// Records an attempt's close-out, in one store lock. The session check runs first, so the
+// answer to a call for an attempt that is not current does not depend on the body.
+export function closeOutAttempt(input: CloseOutInput): Promise<CloseOutAnswer> {
+  return input.store.exclusive(async (tx) => {
+    const latest = await tx.findAttemptBySession(input.call.session);
+
+    const found = pickCallAttempt(latest, input.call);
+
+    if (found.kind === 'refused') {
+      return found;
+    }
+
+    const attempt = found.attempt;
+
+    // the body only: the phase is the attempt's
+    const hash = buildBodyHash(input.body);
+
+    if (hash === null) {
+      return {
+        kind: 'rejected',
+        problems: [{ kind: 'schema', path: '', message: 'the close-out is not valid JSON text' }],
+      };
+    }
+
+    if (attempt.closeOutHash === hash && attempt.closeOutFact !== null) {
+      return { kind: 'recorded', attempt: attempt.id, factId: attempt.closeOutFact, repeat: true };
+    }
+
+    if (attempt.state === 'closing' && attempt.closing === 'closed-out') {
+      return { kind: 'refused', reason: 'already-closed-out' };
+    }
+
+    if (
+      attempt.state === 'closing' ||
+      attempt.state === 'succeeded' ||
+      attempt.state === 'failed'
+    ) {
+      return { kind: 'refused', reason: 'not-current' };
+    }
+
+    return writeCloseOut(tx, input, attempt, hash);
+  });
+}
+
+// null for a body that has no canonical JSON form, such as a string with a lone surrogate
+function buildBodyHash(body: unknown): ContentHash | null {
+  try {
+    return contentHash(toJSONValue(body));
+  } catch {
+    return null;
+  }
+}
+
+async function writeCloseOut(
+  tx: StoreTx,
+  input: CloseOutInput,
+  attempt: AttemptRow,
+  hash: ContentHash,
+): Promise<CloseOutAnswer> {
+  const phase = input.rules.phases.get(attempt.phase);
+
+  // the phase left the rules after the claim: the attempt can no longer close out
+  if (phase === undefined) {
+    return { kind: 'refused', reason: 'not-current' };
+  }
+
+  const ctx = await readCloseOutContext(tx, input, attempt);
+
+  const parsed = phase.closeOut.parse(input.body, ctx);
+
+  if (parsed.kind === 'invalid') {
+    return { kind: 'rejected', problems: parsed.problems };
+  }
+
+  const closeOut = closeOutSchema.safeParse(parsed.closeOut);
+
+  invariant(closeOut.success, `the phase kind ${attempt.phase} gives a close-out of a known shape`);
+
+  const built = buildAttemptChange({
+    attempt,
+    event: { kind: 'closed-out', closeOut: closeOut.data, hash },
+    actor: `boxxy:attempt:${attempt.id}`,
+    now: input.now,
+    newId: input.newId,
+  });
+
+  if (built.kind === 'not-allowed') {
+    return { kind: 'refused', reason: 'not-current' };
+  }
+
+  const result = await tx.applyChange(built.change);
+
+  return result.kind === 'applied'
+    ? {
+        kind: 'recorded',
+        attempt: attempt.id,
+        factId: getClosedOutFact(built.change),
+        repeat: false,
+      }
+    : { kind: 'refused', reason: 'not-current' };
+}
+
+async function readCloseOutContext(
+  tx: StoreTx,
+  input: CloseOutInput,
+  attempt: AttemptRow,
+): Promise<CloseOutContext> {
+  const item = await tx.readItem(attempt.item, input.now, input.rules);
+
+  invariant(item !== null, `an attempt's item is stored: ${attempt.item}`);
+
+  const items = await tx.listItems({}, input.now, input.rules);
+
+  return {
+    item,
+    attempt: attempt.id,
+    evidence: await tx.listEvidence(attempt.id),
+    world: buildWorld(
+      input.rules,
+      items.map((each) => each.id),
+    ),
+  };
+}
+
+function buildWorld(rules: LoadedRules, items: readonly CloseOutContext['item']['id'][]) {
+  return {
+    items: new Set(items),
+    kinds: new Set(rules.kinds.keys()),
+    relationTypes: new Set(rules.relationTypes.keys()),
+  };
+}
+
+function getClosedOutFact(change: StoreChange): FactId {
+  const fact = change.facts.find((candidate) => candidate.type === 'boxxy.attempt.closed_out');
+
+  invariant(fact !== undefined, 'the closed-out move records its fact');
+
+  return fact.id;
+}

package/src/closeouts/effect-handlers.ts

@@ -0,0 +1,232 @@
+import type {
+  AnyNewFact,
+  ItemId,
+  ItemRow,
+  RelationRow,
+  RelationTypeName,
+  RowWrite,
+} from '@boxxy/model';
+import { brandSchemas } from '@boxxy/model';
+import type { EffectContext, EffectHandlers, EffectPlan } from './types.ts';
+
+// The plan of each kind of effect. Pure: each handler reads only its context, and refuses with
+// `skip` rather than throw, so a settle never fails on stored data.
+export const effectHandlers: EffectHandlers = {
+  'file-item': (effect, ctx) => {
+    const kind = brandSchemas.itemKindName.parse(effect.item.kind);
+
+    if (!ctx.rules.kinds.has(kind)) {
+      return { kind: 'skip', effect, reason: `the rules have no kind ${kind}` };
+    }
+
+    const row: ItemRow = {
+      id: brandSchemas.itemId.parse(ctx.newId()),
+      kind,
+      repo: ctx.item.repo,
+      title: effect.item.title,
+      outcome: effect.item.body,
+      acceptance: [],
+      fields: {},
+      labels: [],
+      foundInAttempt: ctx.attempt.id,
+      filedBy: ctx.actor,
+      filedAt: ctx.now,
+      closedAt: null,
+      closeReason: null,
+      keptSession: null,
+    };
+
+    const { keptSession: _keptSession, ...filed } = row;
+
+    return {
+      kind: 'apply',
+      effect,
+      writes: [{ op: 'insert', table: 'items', row }],
+      facts: [buildItemFact(ctx, row.id, { type: 'boxxy.item.filed', payload: filed })],
+    };
+  },
+  'close-item': (effect, ctx) => {
+    const closed = findClosedReason(ctx);
+
+    if (closed !== null) {
+      return { kind: 'skip', effect, reason: closed };
+    }
+
+    // a relation that is live already, such as one an earlier effect adds, is not added again
+    const relation = effect.of === null ? null : buildRelationPlan(ctx, 'duplicate-of', effect.of);
+    const duplicateOf = typeof relation === 'string' ? null : relation;
+
+    return {
+      kind: 'apply',
+      effect,
+      writes: [
+        ...(duplicateOf?.writes ?? []),
+        buildItemUpdate(ctx, { closedAt: ctx.now, closeReason: effect.reason }),
+      ],
+      facts: [
+        ...(duplicateOf?.facts ?? []),
+        buildItemFact(ctx, ctx.item.id, {
+          type: 'boxxy.item.closed',
+          payload: { reason: effect.reason, byAttempt: ctx.attempt.id, ended: [] },
+        }),
+      ],
+    };
+  },
+  'add-relation': (effect, ctx) => {
+    const closed = findClosedReason(ctx);
+
+    if (closed !== null) {
+      return { kind: 'skip', effect, reason: closed };
+    }
+
+    const plan = buildRelationPlan(ctx, effect.relation.type, effect.relation.target);
+
+    return typeof plan === 'string'
+      ? { kind: 'skip', effect, reason: plan }
+      : { kind: 'apply', effect, ...plan };
+  },
+  'set-kind': (effect, ctx) => {
+    const closed = findClosedReason(ctx);
+
+    if (closed !== null) {
+      return { kind: 'skip', effect, reason: closed };
+    }
+
+    if (!ctx.rules.kinds.has(effect.itemKind)) {
+      return { kind: 'skip', effect, reason: `the rules have no kind ${effect.itemKind}` };
+    }
+
+    return buildEditPlan(effect, ctx, { kind: effect.itemKind });
+  },
+  'set-field': (effect, ctx) => {
+    const closed = findClosedReason(ctx);
+
+    if (closed !== null) {
+      return { kind: 'skip', effect, reason: closed };
+    }
+
+    return buildEditPlan(effect, ctx, {
+      fields: { ...ctx.item.fields, [effect.field]: effect.value },
+    });
+  },
+  'set-acceptance': (effect, ctx) => {
+    const closed = findClosedReason(ctx);
+
+    if (closed !== null) {
+      return { kind: 'skip', effect, reason: closed };
+    }
+
+    return buildEditPlan(effect, ctx, { acceptance: effect.criteria });
+  },
+
+  // a fact about the attempt only, so it records on a closed item too
+  'record-proposal': (effect, ctx) => ({
+    kind: 'apply',
+    effect,
+    writes: [],
+    facts: [
+      buildItemFact(ctx, ctx.item.id, {
+        type: 'boxxy.proposal.recorded',
+        payload: { attempt: ctx.attempt.id, ...effect.friction },
+      }),
+    ],
+  }),
+};
+
+type FactBody = {
+  [T in AnyNewFact['type']]: Pick<Extract<AnyNewFact, { type: T }>, 'type' | 'payload'>;
+}[AnyNewFact['type']];
+
+function buildItemFact(ctx: EffectContext, item: ItemId, body: FactBody): AnyNewFact {
+  const fact: AnyNewFact = {
+    ...body,
+    id: brandSchemas.factId.parse(ctx.newId()),
+    entity: `boxxy:item:${item}`,
+    actor: ctx.actor,
+  };
+
+  return fact;
+}
+
+function findClosedReason(ctx: EffectContext): string | null {
+  return ctx.item.closedAt === null ? null : 'the item is closed';
+}
+
+function buildRelationPlan(
+  ctx: EffectContext,
+  typeName: string,
+  target: ItemId,
+): Pick<Extract<EffectPlan, { kind: 'apply' }>, 'writes' | 'facts'> | string {
+  const type = ctx.rules.relationTypes.get(brandSchemas.relationTypeName.parse(typeName))?.name;
+
+  if (type === undefined) {
+    return `the rules have no relation type ${typeName}`;
+  }
+
+  if (target === ctx.item.id) {
+    return 'an item has no relation to itself';
+  }
+
+  if (isLive(ctx.relations, target, type)) {
+    return 'the relation is live already';
+  }
+
+  const row: RelationRow = {
+    source: ctx.item.id,
+    target,
+    type,
+    addedBy: ctx.actor,
+    addedAt: ctx.now,
+    removedAt: null,
+  };
+
+  return {
+    writes: [{ op: 'insert', table: 'relations', row }],
+    facts: [
+      buildItemFact(ctx, ctx.item.id, {
+        type: 'boxxy.relation.added',
+        payload: { source: row.source, target, type },
+      }),
+    ],
+  };
+}
+
+function isLive(
+  relations: readonly RelationRow[],
+  target: ItemId,
+  type: RelationTypeName,
+): boolean {
+  return relations.some(
+    (relation) =>
+      relation.target === target && relation.type === type && relation.removedAt === null,
+  );
+}
+
+// Every update of the item expects it open, so a close of the same change goes last.
+function buildItemUpdate(ctx: EffectContext, set: Partial<ItemRow>): RowWrite {
+  return {
+    op: 'update',
+    table: 'items',
+    key: { id: ctx.item.id },
+    expect: { closedAt: null },
+    set,
+  };
+}
+
+function buildEditPlan(
+  effect: Extract<EffectPlan, { kind: 'apply' }>['effect'],
+  ctx: EffectContext,
+  set: Pick<Partial<ItemRow>, 'kind' | 'fields' | 'acceptance'>,
+): EffectPlan {
+  return {
+    kind: 'apply',
+    effect,
+    writes: [buildItemUpdate(ctx, set)],
+    facts: [
+      buildItemFact(ctx, ctx.item.id, {
+        type: 'boxxy.item.edited',
+        payload: { ...set, byAttempt: ctx.attempt.id },
+      }),
+    ],
+  };
+}

package/src/closeouts/pick-settlement.ts

@@ -0,0 +1,80 @@
+import type {
+  AttemptRow,
+  EngineOutcome,
+  ForcedFailure,
+  Instant,
+  ItemView,
+  LoadedRules,
+  OutcomeName,
+  Settlement,
+} from '@boxxy/model';
+import { brandSchemas } from '@boxxy/model';
+
+interface SettlementInput {
+  readonly attempt: AttemptRow;
+  readonly item: ItemView;
+  readonly rules: LoadedRules;
+  readonly forced: ForcedFailure | null;
+  readonly now: Instant;
+}
+
+export interface PickedSettlement extends Omit<Settlement, 'outcome'> {
+  readonly outcome: OutcomeName | EngineOutcome;
+
+  // the name the phase code returned that its kind does not list; else null
+  readonly returnedOutcome: string | null;
+}
+
+// How the attempt ends. Never throws: phase code that throws, or answers an outcome its kind
+// does not list, gives `unsettleable`. The returned name is never stored as the outcome, so a
+// rollback to rules that map it cannot move the item on with no effect applied.
+export function pickSettlement(input: SettlementInput): PickedSettlement {
+  const closeOut = input.attempt.closeOut;
+
+  if (closeOut === null || input.forced !== null) {
+    return {
+      state: 'failed',
+      failure: input.forced ?? 'closeout-missing',
+      outcome: 'lost',
+      returnedOutcome: null,
+      effects: [],
+      frictionDropped: 0,
+    };
+  }
+
+  const phase = input.rules.phases.get(input.attempt.phase);
+
+  if (phase === undefined) {
+    return buildUnsettleable(null);
+  }
+
+  try {
+    const settlement = phase.settle({
+      attempt: input.attempt,
+      item: input.item,
+      closeOut,
+      now: input.now,
+    });
+
+    return phase.outcomes.includes(settlement.outcome)
+      ? {
+          ...settlement,
+          outcome: brandSchemas.outcomeName.parse(settlement.outcome),
+          returnedOutcome: null,
+        }
+      : buildUnsettleable(settlement.outcome);
+  } catch {
+    return buildUnsettleable(null);
+  }
+}
+
+function buildUnsettleable(returnedOutcome: string | null): PickedSettlement {
+  return {
+    state: 'failed',
+    failure: 'closeout-unsettleable',
+    outcome: 'unsettleable',
+    returnedOutcome,
+    effects: [],
+    frictionDropped: 0,
+  };
+}