# Zengram embedding generation evidence

The article uses Ptah 0.11.4, PostgreSQL 16.15, and pgvector 0.8.7. All databases
used for these measurements were disposable. `verified.json` records the exact
release, source revision, image, and earlier fork CI result. The upstream PR was
open when the article was prepared; there is no claim of upstream adoption.

## Files and source identity

- `source.sql` and `upstream-spec.json` are unchanged copies of the proposal's
  source projection and example specification.
- `verify.js.txt`, `pgvector.js.txt`, and `reembed.js.txt` are unchanged source
  files from fork commit `93afcf8da691100f98c9d9a027e14362c0393df2`. The `.txt`
  suffix makes them downloadable through the blog's existing example routes.
- `ZENGRAM-LICENSE.txt` preserves the upstream MIT license.
- `candidate.json` is the actual specification written by the article test.
  `candidate` is a deterministic local fixture model, not a public model name.
  Its endpoint is local to the process running the test.
- `verify-article.js.txt` keeps the original integration assertions and adds
  evidence recording. It pins the fixture provider to port 8047 and supplies
  Ptah's common arguments through `PTAH_SPEC`, `PTAH_DB_URL`, and `PTAH_RUN_ID`,
  so the article's short CLI forms are exercised directly.
- `measured/commands.json` records argv, environment bindings, exit codes, and
  combined output for every invocation. The backfill outage and unapproved
  cutover are expected failures, not skipped tests.
- `measured/transcript.txt` is the complete test output. The shorter output files
  are exact excerpts used by the article. `file-hashes.json` hashes all evidence
  files other than itself.

## Repeat the original integration test

Install the released `ptah` binary on PATH. Clone the fork, check out the recorded
commit, and install API dependencies:

```sh
git clone https://github.com/denisvmedia/Zengram.git
cd Zengram
git checkout 93afcf8da691100f98c9d9a027e14362c0393df2
cd api
npm ci
```

Start an empty PostgreSQL 16 database using the pgvector image recorded in
`verified.json`. Set `POSTGRES_URL` to that disposable database, including the
intended SSL mode. Run from `Zengram/api`:

```sh
node scripts/ptah/verify.js
```

The test refuses a database that already contains `memories`. It starts its own
local provider and API storage processes. It leaves the test database populated
for inspection; drop that disposable database afterward. Do not run it against
application data.

## Repeat the article's command recording

Download `verify-article.js.txt` and save it as
`Zengram/api/scripts/ptah/verify-article.js`, retaining the other files from that
same source revision. Use another empty disposable database and an available
local port 8047. Set `POSTGRES_URL` as above, then from `Zengram/api`:

```sh
mkdir -p article-evidence
export PTAH_ARTICLE_OUTPUT="$PWD/article-evidence"
node scripts/ptah/verify-article.js > article-evidence/transcript.txt 2>&1
```

The driver writes `candidate.json`, raw `commands.jsonl`, and the redirected
transcript. The checked-in `measured/commands.json` is that JSONL converted into
an array without changing any record. Run IDs, transaction boundaries, and
approval digests vary across databases. An approval is read from that run's
refusal; a digest copied from the article is not reusable authorization.

The driver sets `PTAH_SPEC` to the generated specification's actual temporary
path, `PTAH_DB_URL` to `POSTGRES_URL`, and `PTAH_RUN_ID=zengram-proof` for every
CLI invocation. The command record uses the portable name `candidate.json` and
`$POSTGRES_URL` for those first two bindings. It does not serialize credentials
from a caller's environment. `commands/*.txt` contains the exact command forms
shown on the page; setup and API activity are provided by the driver.

## What passed

The old representation has 1,536 dimensions and the candidate has 384. The test
asserts that a provider outage and retry preserve the original vectors and
payloads. Old-model search runs while a candidate embedding request is pending.
After backfill, an edit, insert, and delete are captured and caught up; the test
compares the edited and inserted candidate vector components with their expected
values. It checks the original HNSW object's identity, explicit approval,
post-handover upserts and supersession, tenant/collection filtering, and catch-up
and verification after new-generation writes.

The provider encodes a few deterministic input distinctions. No learned model
quality, production corpus scale, deployment latency, or automatic rollback is
measured. Zengram's separate keyword/entity search code is unchanged. The
application still needs a coordinated encoder/column deployment and final writer
pause; the database pointer does not configure its API processes.