AbsoluteJS

Handoff

@absolutejs/handoffv0.1.0betaAI

Correlation, evidence, reconciliation, and visibility primitives for work handed to external systems.

#Installation

BASH
bun add @absolutejs/handoff

#Capabilities

Overview

Storage-neutral correlation and evidence for work that leaves your application.

A handoff starts in your code, continues in an external system, and may return through a callback, reconciliation, or a customer report. @absolutejs/handoff keeps those observations joined without pretending your application can inspect an external page directly.

Evidence and reconciliation

external_api, callback, and reconciliation evidence is authoritative. external_surface_report evidence records what a customer or operator saw without silently overriding external-system truth.

Recording

createHandoffRecorder() accepts optional storage and observer contracts. Recording returns per-sink delivery state instead of throwing when an observability sink fails, so visibility cannot break the business operation. The recorder also exposes low-cardinality counters by source and outcome.

Messages and references redact payment-number-shaped text and bearer credentials. Applications must still keep raw callbacks, credentials, payment details, and customer data in their own protected stores.

Package boundaries

@absolutejs/handoff owns the shared protocol. Domain packages keep their own meaning and adapters:

Commerce decides what paid, declined, and settled mean.

Dispatch decides what sent, bounced, and complained mean.

Show 3 more

CRM decides what synchronized or conflicted means.

Voice and Meeting decide what joined, recorded, and transcribed mean.

Those packages translate external-system evidence into this neutral vocabulary.

Outcomes

What you can build

Overview

Storage-neutral correlation and evidence for work that leaves your application.

Evidence and reconciliation

external_api, callback, and reconciliation evidence is authoritative. external_surface_report evidence records what a customer or operator saw without silently overriding external-system truth.

Recording

createHandoffRecorder() accepts optional storage and observer contracts. Recording returns per-sink delivery state instead of throwing when an observability sink fails, so visibility cannot break the business operation. The recorder also exposes low-cardinality counters by source and outcome.

Hardening checklist

Production guidance

Make every external boundary explicitPin the deployed @absolutejs/handoff version, replace example or memory-backed dependencies with durable implementations, bound external calls, protect credentials, and emit enough evidence to retry or recover safely.

Follow in order

Troubleshooting path

1
Trace from the first failed boundary
Reproduce the smallest canonical @absolutejs/handoff example, confirm the supported entry point and version in the API explorer, then inspect the first boundary that did not produce its documented result.

#Correlation

Partial snippet

Working example for Correlation.

TS
import {
  handoffCorrelationFrom,
  withHandoffCorrelation,
} from "@absolutejs/handoff";

const metadata = withHandoffCorrelation(
  { campaign: "summer" },
  crypto.randomUUID(),
);

// Services with fixed metadata slots can name the slot explicitly.
const gatewayFields = withHandoffCorrelation(
  { field_1: "campaign" },
  crypto.randomUUID(),
  "field_20",
);

const correlationId = handoffCorrelationFrom(gatewayFields, "field_20");

#Evidence and reconciliation

Partial snippet

Working example for Evidence and reconciliation.

TS
import { summarizeHandoff } from "@absolutejs/handoff";

const summary = summarizeHandoff([
  {
    at: Date.now(),
    correlationId: "invoice-123",
    operation: "invoice_payment",
    outcome: "succeeded",
    service: "gateway",
    source: "callback",
  },
  {
    at: Date.now() + 1,
    correlationId: "invoice-123",
    message: "The hosted page displayed an error",
    operation: "invoice_payment",
    outcome: "failed",
    service: "gateway",
    source: "external_surface_report",
  },
]);

// The callback remains authoritative while the customer-visible contradiction
// remains actionable.
console.log(summary.status); // "succeeded"
console.log(summary.contradiction); // true

#Public entry points

Supported entry points declared by this project’s package manifest. Internal dist paths are not part of the package contract.

Public package entry point declared in package.json.

@absolutejs/handoff@absolutejs/handoff/manifest@absolutejs/handoff/manifest.json

#Package commands

Scripts declared by this project’s package manifest.

bun run buildrm -rf dist && bun build src/index.ts src/manifest.ts --outdir dist --target=bun --external @absolutejs/manifest --external @sinclair/typebox && tsc -p tsconfig.build.json && absolute-manifest emit
bun run check:packagebun run format && bun run typecheck && bun run test && bun run verify-package && bun run build && bun run verify-package --artifacts
bun run formatprettier --write "./**/*.{ts,json,md}"
bun run testbun test
bun run typechecktsc --noEmit

#API reference

Search the declarations exported by the current package type files. Expand a symbol to inspect its source-backed signature.

17 symbols
HANDOFF_CORRELATION_KEYvaluePermalink

@absolutejs/handoff — privacy-safe visibility for work that leaves your app. A handoff starts in a host application, continues in an external system, and may return through callbacks, reconciliation, or a customer/operator report. This package preserves one correlation identity while keeping reported outcomes separate from authoritative external evidence.

TS
const HANDOFF_CORRELATION_KEY = "absolute_handoff_correlation";
Exported from @absolutejs/handoff