@vaur94/agz-memory 0.4.1 → 0.5.1

package/docs/adr/hash-identity-v2.md

@@ -0,0 +1,57 @@
+# ADR: Version 2 Tuple Hash Identities
+
+Status: Accepted
+
+Date: 2026-09-02
+
+## Context
+
+Schema 10 hashes several user-controlled tuples by joining strings with NUL bytes. NUL is not rejected by every producer, so two different tuples can serialize to the same byte sequence. JavaScript string length also counts UTF-16 code units rather than UTF-8 bytes, which makes an implicit character-based framing contract unsuitable for persisted identities.
+
+The affected values include canonical note hashes, derived-document hashes, OpenCode capture identities, project binding keys, and capture payload hashes. These values survive process restarts and must be deterministic on every supported platform.
+
+## Decision
+
+Schema 11 uses one exported helper:
+
+```ts
+hashTuple(domain, version, fields)
+```
+
+The encoder writes the following byte sequence into SHA-256:
+
+1. A fixed `agz-memory/hash-tuple` format marker.
+2. A length-prefixed UTF-8 domain.
+3. An unsigned version integer.
+4. A field count.
+5. For every field, a one-byte type tag, an unsigned UTF-8/byte payload length, and the payload.
+
+`null`, strings, booleans, finite numbers, and byte arrays use distinct tags. Empty strings and `null` are therefore different. String lengths are measured after UTF-8 encoding, never with JavaScript `String.length`. Numbers use a canonical finite representation and unsafe integers are rejected.
+
+Each use has a separate domain. The initial version 2 domains are:
+
+- `canonical-note`
+- `derived-note`
+- `capture-identity`
+- `capture-payload`
+- `project-binding`
+- `checkpoint-identity`
+- `outbox-operation`
+
+Schema 11 recomputes canonical and revision hashes from persisted source fields. Derived hashes are recomputed from `deriveDocument()`. Capture keys are recomputed from strict source identities; a legacy row that cannot satisfy its event-kind identity contract stops migration with a safe row identifier and error code. Different legacy rows mapping to the same version 2 key stop migration; they are never merged or ignored.
+
+The capture writer emits `agz-memory.capture/2`. The migration reader accepts `/1` only while migrating persisted schema 10 rows. Runtime ingestion accepts `/2` and independently recomputes the idempotency key before insertion.
+
+## Consequences
+
+- NUL and Unicode tuple collision counterexamples no longer collide.
+- Hashes intentionally change during the schema 10 to 11 migration.
+- Version 2 databases cannot be safely written by version 0.4.1; the existing newer-schema guard must reject them before any DDL.
+- Hashes identify content or operation tuples; they are not secret storage and do not replace redaction.
+- Migration produces an aggregate mapping audit without recording note bodies, prompts, credentials, or other private payloads.
+
+## Rejected Alternatives
+
+- Delimiter escaping was rejected because every producer would need identical escaping and type/null handling.
+- `JSON.stringify` was rejected because object/key representation and numeric edge cases are not the persisted contract we need.
+- Reusing version 1 hashes was rejected because it preserves the collision class.

package/docs/adr/maintenance-lock.md

@@ -0,0 +1,93 @@
+# ADR: Cross-Process Database Maintenance Gate
+
+Status: Accepted
+
+Date: 2026-09-02
+
+## Context
+
+SQLite WAL coordinates transactions but does not make replacing the database pathname safe while another process holds an open connection. An old connection can continue to use the replaced inode and its WAL after restore. Before schema 11, the migration lock serialized migration owners only; normal MCP and plugin handles did not participate.
+
+AGZ Memory must run on Linux, macOS, and Windows under Bun. Bun does not currently expose one portable shared/exclusive advisory-file-lock API for this package, so schema 11 uses a conservative filesystem protocol and fails closed whenever ownership cannot be established.
+
+## Decision
+
+Every normal database handle owns a lease for its complete lifetime. Migration, restore, backup publication, and prune use one exclusive maintenance gate associated with the canonical database path.
+
+### Normal Open
+
+1. Resolve and validate the canonical path and parent policy.
+2. Reject an existing maintenance gate.
+3. Publish a private lease file by exclusive staging and atomic rename. Its record contains an opaque owner ID, PID, process-start marker, hostname, and creation time. It contains no database content or configured private path.
+4. Check the maintenance gate again. If it appeared, remove only the caller's verified lease and retry or fail.
+5. Open and validate SQLite.
+6. Keep the lease until statements and the SQLite handle are closed.
+
+The second gate check closes the race where maintenance creates the gate between the first check and lease publication. Maintenance either observes the published lease, or the opener observes the gate and withdraws.
+
+### Maintenance
+
+1. Atomically create the gate. Only one owner can succeed.
+2. Validate the gate owner record after publication.
+3. Enumerate leases. A local lease is stale only when PID liveness and process-start identity prove that its owner is gone or the PID was reused. A remote-host or unverifiable lease remains active and blocks maintenance.
+4. If any active lease exists, remove only the caller's gate and return `active_database_handles`.
+5. Perform the operation without exposing a normal handle.
+6. Verify the installed canonical database before removing the gate.
+
+There is no `--force` bypass for active or unverifiable leases. Stale cleanup requires current owner identity checks. Gate and lease deletion never recursively removes an unverified replacement pathname.
+
+Migration waiters recheck the canonical schema under a normal lease while they
+still own the migration lock. A waiter that finds the target schema returns that
+handle without creating another maintenance gate. After a successful migration,
+the owner releases the maintenance gate and publishes its normal lease before
+releasing the migration lock. This handoff prevents queued stale observations
+from creating a new gate between migration completion and reopen.
+
+An active gate left by a crashed local process is reclaimed in place: an
+exclusive takeover record serializes contenders and atomically replaces the
+stale owner while the gate directory remains continuously present. A reused PID
+is stale only when both process-start markers exist and differ. Remote owners,
+live owners, unavailable markers, malformed records, and missing records remain
+fail-closed.
+
+`retain()` atomically persists `state: recovery-required` before returning. Such
+a gate is never reclaimed automatically. A verified restore may take it over
+only with the exact recorded owner ID and
+`RECOVER_RETAINED_MAINTENANCE_GATE`; the restore keeps the gate continuously
+held and validates the installed database before release.
+
+### Restore
+
+While the maintenance gate is held and no leases exist:
+
+1. Open the backup and manifest through the validated no-symlink policy.
+2. Copy the source into a private same-parent staging file while streaming SHA-256 and byte count.
+3. Validate manifest hash/size, application ID, database UUID/product, schema version/fingerprint, row counts, `integrity_check`, and `foreign_key_check` on the staging inode.
+4. Checkpoint and preserve the current canonical database.
+5. Fsync staging and its parent, atomically replace the canonical pathname, and quarantine stale WAL/SHM files.
+6. Reopen the installed target and repeat identity, fingerprint, count, and health validation.
+7. On failure, restore the preserved source while still holding the gate. If rollback cannot be verified, retain the gate as a recovery-required marker and fail closed.
+
+Backup hashing is streaming. Restore never copies a pathname that was validated and then reopened as the source of truth.
+
+## Platform Policy
+
+- The database, backup root, manifest, maintenance gate, lease registry, lock records, and their existing parents must not be symbolic links.
+- Existing components must have the expected file type and private ownership/permissions when the platform exposes those attributes.
+- New files use exclusive creation and private modes.
+- An unsupported no-follow or identity check causes the sensitive operation to fail closed rather than silently weaken the policy.
+- Process-start markers use the strongest local facility available. An unavailable marker never justifies breaking a live lease.
+
+## Consequences
+
+- Restore is offline-safe, not an online hot swap.
+- Long-lived MCP/plugin handles explicitly block maintenance until clean shutdown.
+- A crashed owner can be reclaimed only with verifiable stale-owner evidence.
+- The protocol is cooperative against same-user processes; it does not protect a database directory writable by an untrusted account. Unsafe ownership or permissions are rejected.
+
+## Rejected Alternatives
+
+- WAL checkpoint alone was rejected because it does not invalidate old file descriptors.
+- PID-only lock files were rejected because PIDs are reused.
+- Unconditional stale timeout and `--force` were rejected because a paused live writer could lose acknowledged writes.
+- Path-only verify-then-copy was rejected because it leaves a TOCTOU window.

package/docs/backup-restore-runbook.md

@@ -2,7 +2,7 @@
 
 English | [Türkçe](backup-restore-runbook.tr.md)
 
-This runbook applies to `@vaur94/agz-memory@0.4.1` and SQLite schema v10.
+This runbook applies to `@vaur94/agz-memory@0.5.1` and SQLite schema v11.
 
 ## Preconditions
 
@@ -25,20 +25,20 @@ Do not proceed with a guessed or empty path.
 Run a read-only health report first:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin doctor
+bunx --package @vaur94/agz-memory@0.5.1 agz-memory-admin doctor
 ```
 
 `ok` must be `true`. Record `schemaVersion`, row counts, and invariant counts.
 Then create a standalone verified backup and upgrade:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin backup
-bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin upgrade --to 10
-bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin doctor
+bunx --package @vaur94/agz-memory@0.5.1 agz-memory-admin backup
+bunx --package @vaur94/agz-memory@0.5.1 agz-memory-admin upgrade --to 11
+bunx --package @vaur94/agz-memory@0.5.1 agz-memory-admin doctor
 ```
 
 The upgrade itself creates another verified pre-migration backup when the
-database schema is older than v10. Preserve each printed manifest path and
+database schema is older than v11. Preserve each printed manifest path and
 SHA-256. Do not start a writer if the final report has `ok: false`.
 
 ## Verify A Backup
@@ -54,16 +54,16 @@ The manifest format is `agz-memory-backup/1`. `agz-memory-admin restore` verifie
 that the manifest and database are regular files in the same backup directory,
 then checks size, SHA-256, SQLite integrity, foreign keys, and row counts.
 
-Final `0.4.1` does not accept prerelease manifest formats. Use the originating
+Final `0.5.1` does not accept prerelease manifest formats. Use the originating
 prerelease to restore such a backup, run its doctor check, and only then upgrade
-that restored database with `0.4.1`.
+that restored database with `0.5.1`.
 
 ## Restore Rehearsal
 
 Keep all writers stopped. First request a dry run by omitting confirmation:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin restore \
+bunx --package @vaur94/agz-memory@0.5.1 agz-memory-admin restore \
   "$OPENCODE_MEMORY_DATABASE_PATH.backup/<backup>.manifest.json"
 ```
 
@@ -71,7 +71,7 @@ Compare `targetPath`, `sourceSchema`, `targetSchema`, row counts, size, and
 SHA-256 with the recorded backup. Then use the exact manifest hash:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin restore \
+bunx --package @vaur94/agz-memory@0.5.1 agz-memory-admin restore \
   "$OPENCODE_MEMORY_DATABASE_PATH.backup/<backup>.manifest.json" \
   --sha256 <manifest-database-sha256> \
   --confirm RESTORE_DATABASE_FROM_VERIFIED_BACKUP
@@ -84,9 +84,9 @@ database passes all checks.
 ## Post-Restore Validation
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin doctor
-bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin capture status
-bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin outbox status
+bunx --package @vaur94/agz-memory@0.5.1 agz-memory-admin doctor
+bunx --package @vaur94/agz-memory@0.5.1 agz-memory-admin capture status
+bunx --package @vaur94/agz-memory@0.5.1 agz-memory-admin outbox status
 ```
 
 Start only the MCP server and perform read-only `project_list`, `memory_recall`,
@@ -94,6 +94,26 @@ and `memory_read` smoke calls. Compare project/note counts with the manifest.
 Only after those checks pass should OpenCode be restarted. Keep the plugin in
 `off` until a separate rollout decision is made.
 
+## Retained Maintenance Gate
+
+`<database>.maintenance/owner.json` with `state: recovery-required` means a
+previous restore could not verify its rollback. It is never removed
+automatically. Stop every MCP/plugin process, preserve the database, sidecars,
+gate, and restore artifacts, then select a verified backup. Supply the exact
+recorded owner ID only on the restoring command:
+
+```sh
+bunx --package @vaur94/agz-memory@0.5.1 agz-memory-admin restore <manifest> \
+  --sha256 <manifest-sha256> \
+  --confirm RESTORE_DATABASE_FROM_VERIFIED_BACKUP \
+  --maintenance-owner <owner-id> \
+  --maintenance-confirm RECOVER_RETAINED_MAINTENANCE_GATE
+```
+
+Remote, live, malformed, or otherwise unverifiable owners remain blocked. Never
+delete the gate manually; the recovery restore atomically takes ownership while
+the gate directory remains present.
+
 ## Stale Migration Lock
 
 The lock is `<database>.migration.lock/owner.json`. Never remove it while the
@@ -104,7 +124,7 @@ style error first if uncertain. Break only a proven stale lock with the exact
 owner ID and confirmation:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin unlock \
+bunx --package @vaur94/agz-memory@0.5.1 agz-memory-admin unlock \
   --owner <owner-id> \
   --confirm BREAK_STALE_MIGRATION_LOCK
 ```
@@ -118,13 +138,13 @@ The first command is non-destructive and returns a digest over the exact backup
 set:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin backup prune
+bunx --package @vaur94/agz-memory@0.5.1 agz-memory-admin backup prune
 ```
 
 Review every listed manifest/database pair. Delete only that unchanged set:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin backup prune \
+bunx --package @vaur94/agz-memory@0.5.1 agz-memory-admin backup prune \
   --digest <dry-run-digest> \
   --confirm DELETE_VERIFIED_BACKUPS
 ```

package/docs/backup-restore-runbook.tr.md

@@ -2,7 +2,7 @@
 
 [English](backup-restore-runbook.md) | Türkçe
 
-Bu runbook `@vaur94/agz-memory@0.4.1` ve SQLite schema v10 için geçerlidir.
+Bu runbook `@vaur94/agz-memory@0.5.1` ve SQLite schema v11 için geçerlidir.
 
 ## Ön Koşullar
 
@@ -25,19 +25,19 @@ Tahmin edilmiş veya boş bir yolla devam etmeyin.
 Önce salt-okunur sağlık raporu alın:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin doctor
+bunx --package @vaur94/agz-memory@0.5.1 agz-memory-admin doctor
 ```
 
 `ok` değeri `true` olmalıdır. `schemaVersion`, satır sayıları ve değişmez kural
 sayılarını kaydedin. Sonra bağımsız doğrulanmış yedek oluşturup yükseltin:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin backup
-bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin upgrade --to 10
-bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin doctor
+bunx --package @vaur94/agz-memory@0.5.1 agz-memory-admin backup
+bunx --package @vaur94/agz-memory@0.5.1 agz-memory-admin upgrade --to 11
+bunx --package @vaur94/agz-memory@0.5.1 agz-memory-admin doctor
 ```
 
-Veritabanı v10'dan eskiyse yükseltme ayrıca değişiklikten önce doğrulanmış yedek
+Veritabanı v11'den eskiyse yükseltme ayrıca değişiklikten önce doğrulanmış yedek
 oluşturur. Yazdırılan her manifest yolunu ve SHA-256 değerini saklayın. Son rapor
 `ok: false` ise yazıcı başlatmayın.
 
@@ -54,16 +54,16 @@ Manifest formatı `agz-memory-backup/1` olur. `agz-memory-admin restore`, manife
 ile veritabanının aynı yedek dizinindeki normal dosyalar olduğunu doğrular;
 ardından boyut, SHA-256, SQLite bütünlüğü, foreign key ve satır sayılarını denetler.
 
-Final `0.4.1` ön sürüm manifest formatlarını kabul etmez. Böyle bir yedeği onu
+Final `0.5.1` ön sürüm manifest formatlarını kabul etmez. Böyle bir yedeği onu
 oluşturan ön sürümle geri yükleyin, o sürümün doctor kontrolünü çalıştırın ve
-yalnız bundan sonra geri yüklenen veritabanını `0.4.1` ile yükseltin.
+yalnız bundan sonra geri yüklenen veritabanını `0.5.1` ile yükseltin.
 
 ## Geri Yükleme Provası
 
 Tüm yazıcıları kapalı tutun. Önce onay vermeden deneme yapın:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin restore \
+bunx --package @vaur94/agz-memory@0.5.1 agz-memory-admin restore \
   "$OPENCODE_MEMORY_DATABASE_PATH.backup/<backup>.manifest.json"
 ```
 
@@ -71,7 +71,7 @@ bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin restore \
 değerlerini kaydedilen yedekle karşılaştırın. Sonra tam manifest özetini kullanın:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin restore \
+bunx --package @vaur94/agz-memory@0.5.1 agz-memory-admin restore \
   "$OPENCODE_MEMORY_DATABASE_PATH.backup/<backup>.manifest.json" \
   --sha256 <manifest-database-sha256> \
   --confirm RESTORE_DATABASE_FROM_VERIFIED_BACKUP
@@ -84,9 +84,9 @@ veritabanı tüm kontrollerden geçmeden bunu silmeyin.
 ## Geri Yükleme Sonrası Doğrulama
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin doctor
-bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin capture status
-bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin outbox status
+bunx --package @vaur94/agz-memory@0.5.1 agz-memory-admin doctor
+bunx --package @vaur94/agz-memory@0.5.1 agz-memory-admin capture status
+bunx --package @vaur94/agz-memory@0.5.1 agz-memory-admin outbox status
 ```
 
 Yalnız MCP sunucusunu başlatın ve salt-okunur `project_list`, `memory_recall` ve
@@ -94,6 +94,26 @@ Yalnız MCP sunucusunu başlatın ve salt-okunur `project_list`, `memory_recall`
 OpenCode'u ancak bu kontroller geçince yeniden başlatın. Ayrı devreye alma kararı
 verilene kadar eklentiyi `off` tutun.
 
+## Korunan Bakım Kapısı
+
+`<database>.maintenance/owner.json` içindeki `state: recovery-required`, önceki
+bir geri yüklemenin geri alma sonucunu doğrulayamadığını gösterir. Bu kapı
+otomatik kaldırılmaz. Tüm MCP/eklenti süreçlerini durdurun; veritabanını, yan
+dosyaları, kapıyı ve geri yükleme kalıntılarını koruyun; ardından doğrulanmış bir
+yedek seçin. Kayıtlı tam sahip kimliğini yalnız geri yükleme komutunda verin:
+
+```sh
+bunx --package @vaur94/agz-memory@0.5.1 agz-memory-admin restore <manifest> \
+  --sha256 <manifest-sha256> \
+  --confirm RESTORE_DATABASE_FROM_VERIFIED_BACKUP \
+  --maintenance-owner <owner-id> \
+  --maintenance-confirm RECOVER_RETAINED_MAINTENANCE_GATE
+```
+
+Uzak, canlı, bozuk veya başka biçimde doğrulanamayan sahipler engelli kalır.
+Kapıyı elle silmeyin; kurtarma geri yüklemesi kapı dizini kesintisiz yerindeyken
+sahipliği atomik olarak devralır.
+
 ## Eski Geçiş Kilidi
 
 Kilit `<database>.migration.lock/owner.json` konumundadır. Kayıtlı süreç yaşıyor
@@ -103,7 +123,7 @@ Sahip dosyasındaki PID, makine ve başlangıç zamanını doğrulayın. Yalnız
 kanıtlanan kilidi tam sahip ID'si ve onayla kırın:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin unlock \
+bunx --package @vaur94/agz-memory@0.5.1 agz-memory-admin unlock \
   --owner <owner-id> \
   --confirm BREAK_STALE_MIGRATION_LOCK
 ```
@@ -116,14 +136,14 @@ kanıtıdır; veritabanı doğrulamasını atlama izni değildir.
 İlk komut silme yapmaz ve tam yedek kümesinin özetini döndürür:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin backup prune
+bunx --package @vaur94/agz-memory@0.5.1 agz-memory-admin backup prune
 ```
 
 Listelenen her manifest/veritabanı çiftini inceleyin. Yalnız değişmemiş kümeyi
 silin:
 
 ```sh
-bunx --package @vaur94/agz-memory@0.4.1 agz-memory-admin backup prune \
+bunx --package @vaur94/agz-memory@0.5.1 agz-memory-admin backup prune \
   --digest <dry-run-digest> \
   --confirm DELETE_VERIFIED_BACKUPS
 ```

package/docs/repository-hardening.md

@@ -0,0 +1,125 @@
+# Repository Hardening Checklist
+
+Repository: `ugur-murat-alt/agz-memory`
+
+Verified on: 2026-09-02
+
+The checks below are GitHub repository controls and cannot be enforced by the package source alone. The verification performed for 0.5.0 found that `main` had no classic branch protection, no repository ruleset, no deployment environment, and Actions allowed all actions without repository-level SHA-pinning enforcement. Workflow actions in this repository are nevertheless pinned by commit SHA.
+
+## Required `main` Ruleset
+
+GitHub screen: **Settings > Rules > Rulesets > New branch ruleset**
+
+Target: default branch, `main`
+
+Enable:
+
+- Restrict deletions.
+- Block force pushes.
+- Require a pull request before merging.
+- Require at least one approval.
+- Dismiss stale approvals when new commits are pushed.
+- Require review from Code Owners when a `CODEOWNERS` file is introduced.
+- Require conversation resolution.
+- Require status checks to pass.
+- Require branches to be up to date before merging.
+- Require signed commits.
+- Require linear history.
+
+Required status checks should include every 0.5.0 CI gate rather than only the aggregate job name:
+
+- Linux minimum Bun type/test/build/package gate.
+- Linux current Bun type/test/build/package gate.
+- macOS current Bun gate.
+- Windows current Bun gate.
+- Property/security tests.
+- Multiprocess stress tests.
+- Restore fault tests.
+- Benchmark gate.
+- Packed install and audit.
+- CodeQL.
+- Dependency review for pull requests.
+
+Do not grant bypass permission to ordinary contributors. Keep the repository administrator bypass limited to documented emergency recovery.
+
+## Signed Commits and Tags
+
+GitHub screen: **Settings > Rules > Rulesets > Require signed commits**
+
+Local verification:
+
+```sh
+git log --show-signature -1
+git tag -v v0.5.0
+```
+
+Create the release tag from the reviewed merge commit. Do not move an existing release tag.
+
+## Release Environment
+
+GitHub screen: **Settings > Environments > New environment**
+
+Name: `npm-release`
+
+Configure:
+
+- Required reviewer.
+- Deployment branch restricted to protected `main` and version tags.
+- No long-lived npm token when trusted publishing is available.
+
+The publish workflow should use npm trusted publishing with OpenID Connect and provenance:
+
+```yaml
+permissions:
+  contents: read
+  id-token: write
+```
+
+```sh
+npm publish --provenance --access public
+```
+
+Verify the published package exposes provenance and that npm `gitHead`, Git tag SHA, GitHub Release SHA, and reviewed merge commit all match.
+
+## Actions Policy
+
+GitHub screen: **Settings > Actions > General > Actions permissions**
+
+Prefer **Allow enterprise actions and select non-enterprise actions** if the account plan supports it. Require full-length commit SHA pinning for third-party actions. Keep workflow token permissions read-only by default and grant narrower write permissions per job.
+
+Repository verification commands:
+
+```sh
+gh api repos/ugur-murat-alt/agz-memory/branches/main/protection
+gh api repos/ugur-murat-alt/agz-memory/rulesets
+gh api repos/ugur-murat-alt/agz-memory/actions/permissions
+gh api repos/ugur-murat-alt/agz-memory/environments
+```
+
+Expected release condition:
+
+- The protection endpoint or active ruleset reports required pull requests, reviews, signed commits, required status checks, no force push, and no deletion.
+- At least one protected `npm-release` environment exists.
+- Actions policy and workflow files both enforce immutable action versions.
+
+## npm Package Policy
+
+- Enable npm two-factor authentication for authorization and writes.
+- Enable trusted publishing for both `@vaur94/agz-memory` and `@vaur94/agz-memory-plugin`.
+- Require provenance on both packages.
+- Deprecate, do not overwrite, a compromised version.
+- Test the packed artifacts together in a clean directory before publish.
+- Verify registry integrity, package contents, imports, exact nine-tool MCP catalog, and inert plugin defaults after publish.
+
+## Release Evidence
+
+Attach or link:
+
+- Ruleset export or settings screenshots.
+- Required-check list and successful run URLs.
+- Signed merge commit and tag verification.
+- Release environment protection.
+- npm provenance statement for both packages.
+- Pack SHA-256 values and clean-install smoke output.
+
+Repository setting changes remain a release blocker until independently verified. Source documentation does not itself close AGZ-064.

package/docs/review-resolution.md

@@ -0,0 +1,78 @@
+# AGZ 0.5.0 Review Resolution
+
+This record maps every AGZ-001 through AGZ-068 review finding to its 0.5.0
+resolution and durable source or regression evidence. `Fixed` means the source
+change and cited local test or release gate exist in this branch. Repository
+settings are external state; AGZ-064 remains explicitly deferred and blocks a
+release-ready claim until the controls in `repository-hardening.md` are verified.
+
+| Finding | Priority | Resolution | Evidence |
+|---|---|---|---|
+| AGZ-001 | P1 | Fixed | Note update and pin compare-and-swap under multiprocess contention: `src/store.ts`, `test/concurrency/note-update-multiprocess.test.ts`. |
+| AGZ-002 | P1 | Fixed | Project deletion binds the immutable ID and confirmed current name in one transaction: `src/store.ts`, `test/concurrency/project-delete-rename.test.ts`. |
+| AGZ-003 | P1 | Fixed | Revision snapshots and provenance use the row returned by the successful mutation: `src/store.ts`, `test/store/lifecycle.test.ts`. |
+| AGZ-004 | P1 | Fixed | Required outbox insertion shares the canonical transaction and cannot be ignored: `src/store.ts`, `test/store/lifecycle.test.ts`. |
+| AGZ-005 | P1 | Fixed | Concurrent project and binding creation distinguishes duplicates from conflicts: `src/store.ts`, `src/store/capture.ts`, `test/concurrency/binding-race.test.ts`. |
+| AGZ-006 | P1 | Fixed | Domain-separated, length-prefixed UTF-8 tuple hashing removes delimiter and Unicode collisions: `src/hash.ts`, `test/capture/capture-contract-v2.test.ts`. |
+| AGZ-007 | P1 | Fixed | Reused capture identities with different source or payload fail as `idempotency_conflict`: `src/store/capture.ts`, `test/capture/capture-contract-v2.test.ts`. |
+| AGZ-008 | P1 | Fixed | Shared MCP/core identities retain the exact nine-tool and fail-closed contract: `src/tools.ts`, `test/contract/mcp-surface.test.ts`. |
+| AGZ-009 | P1 | Fixed | Normal handles publish lifetime database leases before opening SQLite: `src/db/maintenance.ts`, `test/db/maintenance.test.ts`. |
+| AGZ-010 | P1 | Fixed | Maintenance uses one exclusive gate and rejects active or unverifiable handles: `src/db/maintenance.ts`, `test/db/maintenance.test.ts`. |
+| AGZ-011 | P1 | Fixed | Restore refuses to replace a database held by a live writer: `src/db/backup.ts`, `test/db/restore-live-writer.test.ts`. |
+| AGZ-012 | P1 | Fixed | Restore copies and hashes one opened source inode instead of reopening a verified path: `src/db/backup.ts`, `test/db/restore-toctou.test.ts`. |
+| AGZ-013 | P1 | Fixed | Database, backup, sidecar, gate, lease, and manifest paths reject symbolic links: `src/db/maintenance.ts`, `src/db/backup.ts`, `test/db/path-symlink-matrix.test.ts`. |
+| AGZ-014 | P1 | Fixed | `application_id` and `agz_meta` bind product, database UUID, schema, and hash policy: `src/db/schema.ts`, `docs/schema-v11.md`. |
+| AGZ-015 | P1 | Fixed | Exact application-object fingerprint detects same-version schema drift: `src/db/schema.ts`, `test/db/schema-drift-failclosed.test.ts`. |
+| AGZ-016 | P1 | Fixed | Nonempty unsigned databases fail closed while a zero-object database may initialize: `src/db.ts`, `test/db/unrecognized-database.test.ts`. |
+| AGZ-017 | P1 | Fixed | Projection reports truncation into the redaction boundary instead of hiding removed suffixes: `src/capture/projection.ts`, `test/security/redaction-property.test.ts`. |
+| AGZ-018 | P1 | Fixed | Credential/private-key/high-entropy redaction fails closed across boundaries and punctuation: `src/capture/redact.ts`, `test/security/redaction-corpus.test.ts`. |
+| AGZ-019 | P1 | Fixed | Capture event kinds enforce required and forbidden native source identity fields: `src/capture/contract.ts`, `test/capture/capture-contract-v2.test.ts`. |
+| AGZ-020 | P1 | Fixed | Composite foreign keys reject cross-project binding, capture, checkpoint, note, and outbox references: `src/db/schema.ts`, `test/capture/capture-contract-v2.test.ts`. |
+| AGZ-021 | P1 | Fixed | Quarantined events retain no payload and cannot materialize notes: `src/store/capture.ts`, `test/capture/capture.test.ts`. |
+| AGZ-022 | P1 | Fixed | Extraction admits terminal text/status only and excludes tool payloads and reasoning: `packages/opencode-plugin/src/extract.ts`, `test/capture/capture.test.ts`. |
+| AGZ-023 | P1 | Fixed | Checkpoints use `(binding_key, session_id)` so native session IDs can repeat safely: `src/db/schema.ts`, `test/capture/capture-contract-v2.test.ts`. |
+| AGZ-024 | P1 | Fixed | Startup/hourly retention drains bounded terminal, quarantined, and checkpoint backlogs: `src/store/capture.ts`, `test/capture/capture.test.ts`. |
+| AGZ-025 | P2 | Fixed | Reconciliation resumes only after the persisted binding/session checkpoint: `packages/opencode-plugin/src/runtime.ts`, `test/plugin/reconcile-incremental.test.ts`. |
+| AGZ-026 | P2 | Fixed | Reconciliation has bounded global concurrency and coalesces same-session reruns: `packages/opencode-plugin/src/runtime.ts`, `test/plugin/reconcile-backpressure.test.ts`. |
+| AGZ-027 | P1 | Fixed | Shutdown aborts without awaiting hung event, session, or context calls: `packages/opencode-plugin/src/runtime.ts`, `test/plugin/hung-context-stop.test.ts`. |
+| AGZ-028 | P1 | Fixed | Turn opt-out remains effective across every supported hook order: `packages/opencode-plugin/src/runtime.ts`, `test/plugin/optout-hook-permutations.test.ts`. |
+| AGZ-029 | P2 | Fixed | Concurrent opt-out history probes share one bounded request: `packages/opencode-plugin/src/runtime.ts`, `test/plugin/optout-hook-permutations.test.ts`. |
+| AGZ-030 | P2 | Fixed | Reconciliation, terminal-event, and opt-out preflight calls have bounded abortable timeouts: `packages/opencode-plugin/src/runtime.ts`, `packages/opencode-plugin/test/plugin.test.ts`. |
+| AGZ-031 | P2 | Fixed | Runtime errors are reduced to safe codes and do not log payload text: `packages/opencode-plugin/src/runtime.ts`, `packages/opencode-plugin/test/plugin.test.ts`. |
+| AGZ-032 | P1 | Fixed | Location and binding checks fail closed on missing, mismatched, or conflicting identity: `packages/opencode-plugin/src/binding.ts`, `packages/opencode-plugin/test/plugin.test.ts`. |
+| AGZ-033 | P2 | Fixed | First run creates the private default database hierarchy below `HOME`: `src/config.ts`, `test/plugin/first-run-home.test.ts`. |
+| AGZ-034 | P1 | Fixed | Injection remains bounded, escaped, and explicitly marked untrusted: `src/retrieval/formatter.ts`, `test/retrieval/retrieval.test.ts`. |
+| AGZ-035 | P1 | Fixed | Plugin defaults remain off/empty and exact OpenCode version mismatch disables startup: `packages/opencode-plugin/src/config.ts`, `packages/opencode-plugin/test/plugin.test.ts`. |
+| AGZ-036 | P1 | Fixed | Backend hits use the redacted derived-document hash, not canonical note hash: `src/retrieval/derived.ts`, `test/retrieval/hardening.test.ts`. |
+| AGZ-037 | P1 | Fixed | Backend responses have strict keys/types/count bounds and malformed data falls back lexically: `src/retrieval/contract.ts`, `test/retrieval/hardening.test.ts`. |
+| AGZ-038 | P2 | Fixed | One deadline covers backend, canonical validation, graph expansion, and formatting: `src/store/retrieval.ts`, `test/retrieval/hardening.test.ts`. |
+| AGZ-039 | P2 | Fixed | Backend hit validation uses bounded batch SQL rather than per-hit queries: `src/store/retrieval.ts`, `test/retrieval/hardening.test.ts`. |
+| AGZ-040 | P2 | Fixed | Reciprocal-rank fusion is deterministic under channel permutation: `src/retrieval/fusion.ts`, `test/retrieval/hardening.test.ts`. |
+| AGZ-041 | P1 | Fixed | Directed graph retrieval preserves source and target endpoints: `src/store/retrieval.ts`, `test/retrieval/hardening.test.ts`. |
+| AGZ-042 | P2 | Fixed | Context truncation never splits a Unicode code point: `src/retrieval/formatter.ts`, `test/retrieval/hardening.test.ts`. |
+| AGZ-043 | P1 | Fixed | Stale and cross-project backend hits are rejected against canonical rows: `src/store/retrieval.ts`, `test/retrieval/retrieval.test.ts`. |
+| AGZ-044 | P1 | Fixed | Outbox backend calls hard-time out even when `AbortSignal` is ignored: `src/store/outbox.ts`, `test/retrieval/hardening.test.ts`. |
+| AGZ-045 | P1 | Fixed | Heartbeat, lease generation, and fence condition every final outbox transition: `src/store/outbox.ts`, `test/retrieval/hardening.test.ts`. |
+| AGZ-046 | P1 | Fixed | Operation-specific checks and tuple-hashed operation keys reject malformed queue rows: `src/db/schema.ts`, `src/store/outbox.ts`, `test/store/outbox.test.ts`. |
+| AGZ-047 | P1 | Fixed | Each reindex generation queues purge plus a transactional active-note snapshot: `src/admin/index.ts`, `test/retrieval/hardening.test.ts`. |
+| AGZ-048 | P2 | Fixed | Dead work retries explicitly and bounded exponential backoff preserves FIFO: `src/admin/index.ts`, `src/store/outbox.ts`, `test/store/outbox.test.ts`. |
+| AGZ-049 | P1 | Fixed | Project deletion and rebuild enqueue purge so derived stores cannot retain omitted content: `src/store.ts`, `src/admin/index.ts`, `test/store/outbox.test.ts`. |
+| AGZ-050 | P1 | Fixed | Backup publication and migration occur only under the maintenance gate with verified rollback: `src/db.ts`, `src/db/backup.ts`, `test/db/maintenance.test.ts`, `test/db/backup-restore.test.ts`. |
+| AGZ-051 | P2 | Fixed | Batch mutations remain ordered, independently committed, and return every result: `src/tools.ts`, `test/contract/mcp-surface.test.ts`. |
+| AGZ-052 | P1 | Fixed | Schema-10 migration preserves valid legacy bindings, events, tombstones, and orphaned outbox history: `src/db/migrations/v011.ts`, `test/db/migration-v11.test.ts`. |
+| AGZ-053 | P1 | Fixed | Migration verifies counts, revisions, hashes, FTS, foreign keys, identity, and fingerprint before publish: `src/db/migrations/v011.ts`, `src/admin/doctor.ts`, `test/db/migration-v11.test.ts`. |
+| AGZ-054 | P2 | Fixed | Public query and batch inputs retain explicit hard cardinality bounds: `src/tools.ts`, `test/contract/mcp-surface.test.ts`. |
+| AGZ-055 | P1 | Fixed | Semantic query bytes and retrieval card requests clamp to hard limits: `src/store/retrieval.ts`, `test/retrieval/hardening.test.ts`. |
+| AGZ-056 | P2 | Fixed | Store conflicts and lease loss return stable typed error codes rather than raw SQLite errors: `src/store.ts`, `src/store/outbox.ts`, concurrency regressions. |
+| AGZ-057 | P1 | Fixed | Doctor checks database identity, exact fingerprint, tenant references, hashes, revisions, FTS, and operation keys: `src/admin/doctor.ts`, `test/db/migration-v11.test.ts`. |
+| AGZ-058 | P2 | Fixed | Admin reindex/status/retry responses are bounded and payload-free: `src/admin/index.ts`, `test/retrieval/hardening.test.ts`. |
+| AGZ-059 | P2 | Fixed | Retrieval metrics deduplicate rankings and clamp recall, MRR, and NDCG to the unit interval: `benchmark/evaluate.ts`, `test/retrieval/hardening.test.ts`. |
+| AGZ-060 | P2 | Fixed | `benchmark:gate` enforces the documented p99 latency ceiling: `benchmark/run.ts`, `package.json`. |
+| AGZ-061 | P3 | Fixed | Baseline manifest, timings, logs, platform, commit, and benchmark artifacts are committed in `artifacts/baseline/manifest.json` and its listed files. |
+| AGZ-062 | P2 | Fixed | CI covers minimum/current Bun on Linux plus current Bun on macOS and Windows: `.github/workflows/ci.yml`. |
+| AGZ-063 | P2 | Fixed | CI has separate property, stress, restore, benchmark, CodeQL, and dependency-review gates with immutable action pins: `.github/workflows/ci.yml`. |
+| AGZ-064 | P2 | Deferred | `main` protection/ruleset and `npm-release` environment are absent external repository settings; required controls and verification are in `docs/repository-hardening.md`. |
+| AGZ-065 | P2 | Fixed | Package smoke derives both tarball names from the manifest version instead of a stale literal: `.github/workflows/ci.yml`. |
+| AGZ-066 | P3 | Fixed | Runtime ranges, exact plugin compatibility, frozen lock installs, audits, and Dependabot policy are explicit: `package.json`, `packages/opencode-plugin/package.json`, `.github/dependabot.yml`. |
+| AGZ-067 | P3 | Fixed | English/Turkish README and recovery sections are release-verified as mapped contracts: `scripts/verify-release.ts`, `test/release/release-surface.test.ts`. |
+| AGZ-068 | P2 | Fixed | Release verification requires exactly this ordered 68-row record and forbids deferred P0/P1 findings: `scripts/verify-release.ts`, `test/release/release-surface.test.ts`. |