# Runnable Blob attachment example

Read the [developer guide](https://teaql.io/docs/cookbook/blob-references/) first.
Download `AttachmentExample.java` and `run.sh` into one directory. The example
uses explicit runtime metadata and an application-owned `Asset` class; no
generated domain library is included or modified.

## Reproduce

Use Java 21 and Maven, with the source preview at Java commit
`af59bf4ee6f003f509ce8cc42a5d96bb5dcdb8c3`. From that source checkout, install the
example dependencies before invoking the standalone script:

```bash
mvn -pl examples/blob-view-preparation -am install -DskipTests
export TEAQL_JAVA_SOURCE="$PWD"
```

Provide a dedicated PostgreSQL test database and actual PDF and PNG files:

```bash
export TEAQL_BLOB_TEST_PG_URL='jdbc:postgresql://127.0.0.1:5432/attachment_demo'
export TEAQL_BLOB_TEST_PG_USER='attachment_demo'
read -r -s -p 'Test database password: ' TEAQL_BLOB_TEST_PG_PASSWORD
printf '\n'
export TEAQL_BLOB_TEST_PG_PASSWORD
export TEAQL_VIEW_PDF='/absolute/path/contract.pdf'
export TEAQL_VIEW_PNG='/absolute/path/cover.png'
bash /absolute/path/to/downloaded/run.sh
```

Run in Bash with Java 21 on PATH. The database user needs CREATE/DROP SCHEMA.
The database itself must already exist. The application creates and drops only
its unique schema. Temporary storage, parser files and compiled example classes
are removed on exit. The demo signing key is randomly generated per execution;
a deployed gateway needs persistent key configuration to retain URL validity
across restarts.

If your source build used a separate Maven cache, export `TEAQL_MAVEN_REPO` with
that same path. `MAVEN_BIN` can select the Maven executable. The script exports the
existing source example's runtime classpath; it does not install or select a
published Blob release. Required packages are `teaql-blob-reference`,
`teaql-blob-store-file`, `teaql-blob-content-tika`, `teaql-provider-jdbc` and the
PostgreSQL JDBC driver, with the runtime's own managed transitive dependencies.

## Verified execution, 2026-11-01

`verification.json` records the native command output, exact Java source revision,
input hashes, dependency JAR hashes and class-byte comparisons against that
checkout's source-built outputs. The source dependency installation command also passed; the final example run
consumed those freshly installed source-built dependencies. The native command was `bash run.sh` with Java 21.0.6,
Maven 3.9.16, PostgreSQL 14 and the conformance `sample.pdf`/`sample.png` inputs.
Its compile/run exit code was zero. All six application PASS receipts were
present. Both the application resources and the runner's private PostgreSQL
instance were stopped/removed.

The six assertions cover:

1. Actual PDF and PNG upload/verification for two fields.
2. Stable Keys in both SQL columns after graph save.
3. Complete HTTP URL downloads, exact content and MIME; entity Keys unchanged.
4. A new contract upload replacing only the contract field.
5. Clearing the nullable cover and preparing another readable contract view.
6. A failed presentation after commit preserving saved state and a committed
   error classification.

Ordinary logging-backend warnings and the isolated demo's mutation-policy notice
are retained in the native output. The one-actor demo policies grant access;
production authorization is not exercised here. This run also does not qualify
KSML evaluation/generation, an HTTP upload controller, S3, expiry/refresh, Range,
GC, crash recovery, multi-process reopening or cross-machine downloads.

Initial standalone-POM attempts failed dependency resolution; a later behavior
run passed but its provenance collector compared whole JAR bytes, including
packaging differences. The final successful run uses the original source
example's dependency graph and compares class bytes against the source build.
These earlier attempts are summarized in the receipt and are not counted as
passing setup paths. Use the retained `run.sh`, not those discarded POMs.
