Receipts and reproduction

Replay a calc receipt

A successful calc-entry result carries the normalized request and its calculation conventions. JSON-clone the receipt request, then call the same function on the same engine version. Store the engine version and the complete receipt when retaining a result.

import { chart } from '@zodiacs/engine/calc';
const result = chart({
  time: '2000-01-01T12:00:00Z',
  place: { latitude: 51.4779, longitude: -0.0015 },
  houseSystem: 'whole',
});
if (result.status === 'ok') {
  const request = JSON.parse(JSON.stringify(result.receipt.request));
  const replayed = chart(request);
  console.log({ receipt: result.receipt, replayed });
} else {
  console.log({ reason: result.reason, detail: result.detail });
}

What a receipt establishes

A receipt records the request and method. It does not independently prove astronomical accuracy. Compare to independent references using the documented bounds and span.

Receipts can contain sensitive inputs. Redact personal context before publishing an issue or sharing a result. The receipt entry supplies natal-envelope parsing, serialization and redaction; its schema identifiers remain versioned separately from the package.

Install the release

npm install @zodiacs/engine@1.0.0

npm's 1.0.0 tarball is byte-identical to the archive the engine repository carries. To install those bytes from the carrier, with their digest checked before npm sees them, run this in the project's directory instead:

( set -eu
# POSIX shell — macOS, Linux or WSL. Not PowerShell. It runs in a subshell, so
# a failure stops the install without closing your terminal.
BASE=$(pwd)
FILE='zodiacs-engine-1.0.0.tgz'
# Run it in your project's directory. Without a package.json here, npm would
# install into the nearest parent directory that has one.
if test ! -f package.json; then
  echo "Stop: there is no package.json here. Run this in your project's directory, or create one first with: npm init -y" >&2
  exit 1
fi
if test -e "$FILE" || test -L "$FILE"; then
  echo "Stop: $FILE already exists here. Move or delete it, then run this again." >&2
  exit 1
fi
# A download that fails verification is removed, so the guard above does not
# then block the retry. Once npm takes over the archive stays: npm reports its
# own failures, and the file is what you would retry with.
trap 'status=$?; if test "$status" -ne 0; then rm -f "$BASE/$FILE"; fi; exit $status' EXIT

curl --disable --fail --silent --show-error --location --proto '=https' --max-time 120 \
  'https://raw.githubusercontent.com/zodiacs-org/engine/38d31854e5716454921b6ce8a211788a0984328e/artifacts/zodiacs-engine-1.0.0.tgz' -o "$FILE"

node --input-type=module <<'JS'
import { readFileSync } from 'node:fs';
import { createHash } from 'node:crypto';
const file = 'zodiacs-engine-1.0.0.tgz';
const expected = 'c4d3754de899fb98882331e6d7b9ce3ce77fb2072baeb002aa0ef8c77b0ab0f6';
const bytes = readFileSync(file);
const actual = createHash('sha256').update(bytes).digest('hex');
if (actual !== expected) {
  console.error(`Stop: this is not the published archive.\n  expected ${expected}\n  got      ${actual}`);
  console.error('Nothing was installed.');
  process.exit(1);
}
console.log(`Archive verified: ${actual}`);
JS

trap - EXIT
npm install --ignore-scripts "./$FILE"
echo "Installed @zodiacs/engine@1.0.0 from the verified archive."
)

References

• Engine source reference
• Engine source reference