npm package: @cogcoin/vectors
Description: Self-contained Cogcoin indexer vectors, runner utilities, and published generation fixtures.
Latest version: 1.0.0

# `@cogcoin/vectors`

`@cogcoin/vectors@1.0.0` publishes self-contained Cogcoin indexer vectors together with the runner and schema used to replay them. Each vector bundles its own setup blocks, test blocks, expected state hash, transaction outcomes, and query assertions so it can be replayed directly against `@cogcoin/indexer`.

Use Node 18 or newer.

## Links

- Website: [cogcoin.org](https://cogcoin.org)
- Whitepaper: [cogcoin.org/whitepaper.md](https://cogcoin.org/whitepaper.md)
- Source: [github.com/cogcoin/vectors](https://github.com/cogcoin/vectors)
- Indexer package: [npmjs.com/package/@cogcoin/indexer](https://www.npmjs.com/package/@cogcoin/indexer)
- Scoring package: [npmjs.com/package/@cogcoin/scoring](https://www.npmjs.com/package/@cogcoin/scoring)

## Quick Start

Install the package:

```bash
npm install @cogcoin/vectors
```

The installed package includes the runner, published generated vectors, schema, and helper datasets needed by consumers.
The runtime API is published as compiled ESM with bundled type declarations.

## Dependency Surface

The published package depends on:

- `@cogcoin/indexer@1.0.0`
- `@cogcoin/scoring@1.0.0`

`@cogcoin/genesis` is pulled transitively through `@cogcoin/indexer`.

## API

Runtime utilities:

- `loadVector(path)`
- `runVector(vector, options?)`

Published JSON exports:

- `@cogcoin/vectors/history-queries.json`
- `@cogcoin/vectors/real-mining-pass.json`
- `@cogcoin/vectors/scoring-pass-fixtures.json`
- `@cogcoin/vectors/vector-schema.json`
- `@cogcoin/vectors/displayBlockHashes.json`
- `@cogcoin/vectors/recipientScriptPubKeys.json`

## Load a Vector from Disk

```ts
import { loadVector, runVector } from "@cogcoin/vectors";

const vector = await loadVector("/absolute/path/to/vector.json");
const result = await runVector(vector);
```

`runVector(...)` drives the full `prepare -> score -> finalize -> rewind` flow and checks query assertions against the resulting state.

## Import a Published Vector

```ts
import { createRequire } from "node:module";
import { runVector } from "@cogcoin/vectors";

const require = createRequire(import.meta.url);
const historyVector = require("@cogcoin/vectors/history-queries.json");

const result = await runVector(historyVector);
```

## Contents

Generated vectors:

- `history-queries.json`: anchoring, reviews, data history, resolved locks, and domain event log coverage
- `real-mining-pass.json`: published pass sentence replayed through the indexer with a compact synthetic setup
- `scoring-pass-fixtures.json`: extracted pass cases from the published scoring conformance vectors

Supporting data:

- `displayBlockHashes.json`: real display-order Bitcoin block hashes used by vector generation
- `recipientScriptPubKeys.json`: real recipient scriptPubKey samples used by fixtures and generators
- `schema/vector.schema.json`: JSON schema for vector files

The package intentionally ships finalized, self-contained vectors only.

## Practical Notes

- Vectors are designed for `@cogcoin/indexer`, not as standalone consensus logic.
- Query assertions cover both current-state selectors and the whitepaper's optional historical interfaces.
- Generated vector data is intentionally shipped as release artifacts; this package does not regenerate vectors during install or publish.