✨ feat(imports): enrich audit-only import reporting and fixtures

- add audit-only summary counters and suppression-reason aggregates for ingest and follow workflows

- cover richer operator output with checked-in ingest/follow sample fixtures and shared test helpers

- update README, operator guidance, and the development tracker for the new reporting shape

Author: cocosip

README.md

@@ -24,7 +24,7 @@ Use the docs by audience:
 - [Operator docs](docs/go/operator/README.md)
   Client registration, deployment/readiness, packaging, and troubleshooting.
 - [Import ingestion guide](docs/go/operator/import-ingestion.md)
-  JSONL batch and checkpointed follow-mode ingestion for watcher and relay artifacts.
+  JSONL batch and checkpointed follow-mode ingestion for watcher and relay artifacts, including checked-in `ingest-imports` and `follow-imports` sample outputs for richer audit-only reporting.
 - [Maintainer docs](docs/go/maintainer/README.md)
   Source-tree MCP integration, implementation planning, and development tracking.
 
@@ -76,10 +76,10 @@ They are not MCP tools and are not the normal end-user interaction path.
   Prints effective config plus runtime readiness, audit diagnostics, and the last-known `follow-imports` watch-health snapshot when one has been written, including stale-snapshot detection for continuous follow mode.
 - `codex-mem doctor --json`
   Prints the same diagnostics in machine-readable JSON for automation or CI checks.
-- `codex-mem ingest-imports --source watcher_import [--input events.jsonl] [--json] [--continue-on-error] [--failed-output failed.jsonl] [--failed-manifest failed.json]`
-  Imports newline-delimited watcher or relay note events into durable imported notes plus audit records, with optional partial-success handling plus retry-oriented failure exports.
-- `codex-mem follow-imports --source watcher_import --input events-a.jsonl [--input events-b.jsonl ...] [--state-file events-a.offset.json --state-file events-b.offset.json ...] [--watch-mode auto|notify|poll] [--poll-interval 5s] [--once] [--json]`
-  Follows one or more watcher or relay JSONL files incrementally, prefers filesystem notifications with polling fallback by default, keeps one checkpoint per input, automatically retries watcher recovery in `auto` mode, and reports command-level watch state plus poll-catchup/recovery events and warnings alongside per-input imported-note results.
+- `codex-mem ingest-imports --source watcher_import [--input events.jsonl] [--audit-only] [--json] [--continue-on-error] [--failed-output failed.jsonl] [--failed-manifest failed.json]`
+  Imports newline-delimited watcher or relay note events into durable imported notes plus audit records, or uses `--audit-only` to store only import-audit provenance while still applying the same privacy and explicit-memory precedence rules. Audit-only reports now distinguish new-note candidates from existing-note links and can aggregate suppression reasons.
+- `codex-mem follow-imports --source watcher_import --input events-a.jsonl [--input events-b.jsonl ...] [--state-file events-a.offset.json --state-file events-b.offset.json ...] [--watch-mode auto|notify|poll] [--poll-interval 5s] [--once] [--audit-only] [--json]`
+  Follows one or more watcher or relay JSONL files incrementally, prefers filesystem notifications with polling fallback by default, keeps one checkpoint per input, automatically retries watcher recovery in `auto` mode, and reports command-level watch state plus poll-catchup/recovery events and warnings alongside per-input imported-note results or audit-only import records, including nested audit-only summary counters and suppression-reason counts.
 - `codex-mem cleanup-follow-imports [--target-profile all|artifacts|state|retry|health] [...]`
   Removes selected follow-imports checkpoint, retry-artifact, and stale-health artifacts. `--target-profile` can enable common cleanup target sets before you add path, age, dry-run, or `--summary-only` report filters.
 - `codex-mem audit-follow-imports [--target-profile all|artifacts|state|retry|health] [...]`

docs/go/maintainer/development-tracker.md

@@ -25,6 +25,7 @@ Do not use this for:
 Use `ingest-imports` when you already have a bounded batch to replay.
 Use `follow-imports` when another process keeps appending to the same JSONL file and you want `codex-mem` to checkpoint progress between notification or polling passes.
 `follow-imports` can now fan in multiple files by repeating `--input`.
+Add `--audit-only` to either import command when you want import-audit provenance without creating or reusing durable imported notes.
 Use `audit-follow-imports` when you want a read-only hygiene report for pending checkpoint, retry-artifact, or stale-health cleanup work before deciding whether to run deletion.
 
 Minimal stdin example:
@@ -39,6 +40,12 @@ Read from a file and print JSON:
 codex-mem.exe ingest-imports --source relay_import --input .\relay-events.jsonl --json
 ```
 
+Store only import-audit records for the batch while preserving the same privacy and explicit-memory precedence checks:
+
+```powershell
+codex-mem.exe ingest-imports --source watcher_import --input .\events.jsonl --audit-only --json
+```
+
 Continue past bad lines and keep successful imports:
 
 ```powershell
@@ -63,6 +70,12 @@ Follow a growing JSONL file once and checkpoint the consumed offset:
 codex-mem.exe follow-imports --source watcher_import --input .\events.jsonl --once --json
 ```
 
+Follow the same stream in audit-only mode when another system should inspect imported provenance before materializing notes:
+
+```powershell
+codex-mem.exe follow-imports --source watcher_import --input .\events.jsonl --once --audit-only --json
+```
+
 Run as a long-lived poller with an explicit checkpoint file:
 
 ```powershell
@@ -159,6 +172,8 @@ Useful flags:
   Optional. Overrides the default ingestion session task summary.
 - `--json`
   Optional. Prints a structured report instead of line-oriented text output.
+- `--audit-only`
+  `ingest-imports` and `follow-imports` only. Optional. Evaluates each event against the same imported-note dedupe, privacy, and explicit-memory precedence rules, but writes only the import-audit record instead of materializing or reusing a durable note. The event schema stays the same so the audit-only path can answer whether the artifact would have been suppressed or linked to an existing note.
 - `--continue-on-error`
   `ingest-imports` only. Keeps scanning after per-line decode or import failures and returns a partial-success report when at least one event succeeds.
 - `--failed-output <path>`
@@ -259,6 +274,13 @@ Behavior to expect from this batch:
 - the first event creates an imported durable note plus an import audit record
 - the second event creates only a suppressed import audit record
 
+When `--audit-only` is set for `ingest-imports` or `follow-imports`:
+
+- the same event schema is still required because the command evaluates imported-note precedence rather than dropping to raw `memory_save_import`
+- new non-suppressed artifacts create only import-audit records and leave `materialized=0`
+- imported duplicates can still link the created audit record to an existing imported note
+- stronger explicit memory still suppresses the import audit with `suppression_reason=explicit_memory_exists`
+
 ## Output Semantics
 
 Text mode prints a compact summary such as:
@@ -282,6 +304,7 @@ warnings=1
 ```
 
 JSON mode returns the same summary plus per-line results, including the created or reused `note_id` and `import_id`.
+When `--audit-only` is active, the report also includes `audit_only=true`, `materialized` stays `0`, `would_materialize` counts unsuppressed artifacts that would have created a new imported note, and `linked_existing_note` counts unsuppressed artifacts that only linked an already-imported durable note. Whenever any suppression happens, the JSON report also includes a `suppression_reasons` object keyed by normalized reason (for example `privacy_intent`, `explicit_memory_exists`, or the fallback `import_policy` bucket), and text mode flattens those same counts as `suppression_reason_<reason>=<count>`. Each per-line result can still surface `suppression_reason`, and `note_id` stays omitted for newly audited artifacts that would have taken the new-note path.
 When a line fails in `--continue-on-error` mode, that result entry includes a structured `error` payload instead.
 If `--failed-output` is set, the report also includes the resolved output path and how many failed lines were written there.
 If `--failed-manifest` is set, the report also includes the manifest path and how many failures were captured there.
@@ -291,18 +314,34 @@ Multi-input `follow-imports` returns one aggregate report with command-level wat
 `audit-follow-imports` reports the same target-selection metadata and matched-versus-skipped counts as a read-only hygiene pass, plus whether `--summary-only` was active, whether the follow-health snapshot is present, when it was last updated, whether it is stale, and any warning summaries carried by that snapshot.
 When `--summary-only` is set, the aggregate counts stay the same but the detailed checkpoint and retry-artifact path lists are omitted from both text and JSON output.
 
-Checked-in sample outputs for common cleanup flows live under [../../../internal/app/testdata](../../../internal/app/testdata/):
+Checked-in sample outputs for import and follow workflows live under [../../../internal/app/testdata](../../../internal/app/testdata/):
 
+- [ingest-imports-audit-only-summary.txt](../../../internal/app/testdata/ingest-imports-audit-only-summary.txt)
+- [ingest-imports-audit-only-linked.json](../../../internal/app/testdata/ingest-imports-audit-only-linked.json)
+- [follow-imports-audit-only-single.txt](../../../internal/app/testdata/follow-imports-audit-only-single.txt)
+- [follow-imports-audit-only-multi.json](../../../internal/app/testdata/follow-imports-audit-only-multi.json)
 - [cleanup-follow-imports-daily-dry-run.txt](../../../internal/app/testdata/cleanup-follow-imports-daily-dry-run.txt)
 - [cleanup-follow-imports-filtered-cleanup.json](../../../internal/app/testdata/cleanup-follow-imports-filtered-cleanup.json)
 - [cleanup-follow-imports-target-profile-all.txt](../../../internal/app/testdata/cleanup-follow-imports-target-profile-all.txt)
 - [audit-follow-imports-daily-audit.txt](../../../internal/app/testdata/audit-follow-imports-daily-audit.txt)
 - [audit-follow-imports-filtered-audit.json](../../../internal/app/testdata/audit-follow-imports-filtered-audit.json)
 - [audit-follow-imports-target-profile-retry.json](../../../internal/app/testdata/audit-follow-imports-target-profile-retry.json)
 
-If a deliberate output change makes those fixtures drift, refresh the cleanup fixtures from the repository root through the test-only maintainer helper:
+If a deliberate output change makes those fixtures drift, refresh the ingest fixtures from the repository root through the test-only maintainer helper:
+
+```powershell
+$env:CODEX_MEM_REFRESH_INGEST_EXAMPLES = "all"
+go test ./internal/app -run TestRefreshIngestImportsExampleFixtures
+Remove-Item Env:CODEX_MEM_REFRESH_INGEST_EXAMPLES
+```
+
+Refresh the cleanup fixtures the same way:
 
 ```powershell
+$env:CODEX_MEM_REFRESH_FOLLOW_IMPORT_EXAMPLES = "all"
+go test ./internal/app -run TestRefreshFollowImportsExampleFixtures
+Remove-Item Env:CODEX_MEM_REFRESH_FOLLOW_IMPORT_EXAMPLES
+
 $env:CODEX_MEM_REFRESH_CLEANUP_EXAMPLES = "all"
 go test ./internal/app -run TestRefreshCleanupFollowImportsExampleFixtures
 Remove-Item Env:CODEX_MEM_REFRESH_CLEANUP_EXAMPLES
@@ -319,6 +358,14 @@ Remove-Item Env:CODEX_MEM_REFRESH_AUDIT_EXAMPLES
 If you only need one fixture while iterating on a specific report shape, pass a comma-separated fixture-name subset instead of `all`:
 
 ```powershell
+$env:CODEX_MEM_REFRESH_INGEST_EXAMPLES = "audit-only-linked-json"
+go test ./internal/app -run TestRefreshIngestImportsExampleFixtures
+Remove-Item Env:CODEX_MEM_REFRESH_INGEST_EXAMPLES
+
+$env:CODEX_MEM_REFRESH_FOLLOW_IMPORT_EXAMPLES = "audit-only-single-text"
+go test ./internal/app -run TestRefreshFollowImportsExampleFixtures
+Remove-Item Env:CODEX_MEM_REFRESH_FOLLOW_IMPORT_EXAMPLES
+
 $env:CODEX_MEM_REFRESH_CLEANUP_EXAMPLES = "filtered-cleanup-json"
 go test ./internal/app -run TestRefreshCleanupFollowImportsExampleFixtures
 Remove-Item Env:CODEX_MEM_REFRESH_CLEANUP_EXAMPLES
@@ -338,6 +385,7 @@ go test ./internal/app -run "Test(Audit|Cleanup)FollowImportsExampleOutputsStayI
 
 - `ingest-imports` starts one fresh session for the whole batch after resolving scope.
 - `follow-imports` starts one fresh session per consumed polling batch, not one session for the lifetime of the process.
+- `--audit-only` keeps the same session, checkpoint, retry-export, and follow-health behavior as the materializing path so operators can switch between audit-only and imported-note materialization without learning a second ingestion flow.
 - When `follow-imports` fans in multiple files, each input keeps its own checkpoint sidecar and each consumed input still starts its own ingestion session for that batch.
 - In `auto` mode, `follow-imports` prefers filesystem notifications for lower latency and keeps the poll timer as a safety net in case a platform drops an event.
 - In `auto` mode, if watcher setup fails or a running watcher later closes/errors, `follow-imports` falls back to polling and keeps retrying watcher setup on later poll intervals. When watcher setup succeeds again, the process switches back to notify mode instead of staying degraded forever.
@@ -365,6 +413,7 @@ go test ./internal/app -run "Test(Audit|Cleanup)FollowImportsExampleOutputsStayI
 - When multi-input follow mode shares failed-output or failed-manifest bases, pass the same `--input` set to `cleanup-follow-imports` so it derives the same per-input filenames before scanning for range-suffixed artifacts.
 - When multi-input follow mode shares `--failed-output` or `--failed-manifest` base paths, `codex-mem` derives per-input file names before adding the byte-range suffix so retry artifacts from different inputs do not overwrite each other.
 - Each event uses the same imported-note workflow as `memory_save_imported_note`.
+- `--audit-only` intentionally still uses that imported-note workflow instead of the lower-level `memory_save_import` contract, because operators usually want privacy suppression, explicit-memory precedence, and imported-note dedupe to stay aligned between audit-only and materializing runs.
 - Existing explicit memory wins over weaker imported duplicates in the same project.
 - The default implementation is fail-fast: the first invalid line stops the batch and returns an error.
 - `--continue-on-error` preserves successful lines, reports per-line failures, and still exits with an error if nothing in the batch imports successfully.

docs/go/operator/import-ingestion.md

@@ -13,17 +13,17 @@ import (
 	"codex-mem/internal/domain/common"
 )
 
-const cleanupFollowImportsExampleDirName = "testdata"
+const commandExampleDirName = "testdata"
 
-type followImportsExampleFixture[T any] struct {
+type commandExampleFixture[T any] struct {
 	Name         string
 	RelativePath string
 	JSON         bool
 	Report       T
 }
 
-type cleanupFollowImportsExampleFixture = followImportsExampleFixture[cleanupFollowImportsReport]
-type auditFollowImportsExampleFixture = followImportsExampleFixture[auditFollowImportsReport]
+type cleanupFollowImportsExampleFixture = commandExampleFixture[cleanupFollowImportsReport]
+type auditFollowImportsExampleFixture = commandExampleFixture[auditFollowImportsReport]
 
 func normalizeFollowImportsExampleName(value string) string {
 	return strings.ToLower(strings.TrimSpace(value))
@@ -49,17 +49,17 @@ func parseFollowImportsExampleNames(raw string) ([]string, error) {
 	return names, nil
 }
 
-func selectFollowImportsExampleFixtures[T any](fixtures []followImportsExampleFixture[T], names []string, command string) ([]followImportsExampleFixture[T], error) {
+func selectCommandExampleFixtures[T any](fixtures []commandExampleFixture[T], names []string, command string) ([]commandExampleFixture[T], error) {
 	if len(names) == 0 {
 		return fixtures, nil
 	}
 
-	byName := make(map[string]followImportsExampleFixture[T], len(fixtures))
+	byName := make(map[string]commandExampleFixture[T], len(fixtures))
 	for _, fixture := range fixtures {
 		byName[normalizeFollowImportsExampleName(fixture.Name)] = fixture
 	}
 
-	selected := make([]followImportsExampleFixture[T], 0, len(names))
+	selected := make([]commandExampleFixture[T], 0, len(names))
 	seen := make(map[string]struct{}, len(names))
 	for _, name := range names {
 		normalized := normalizeFollowImportsExampleName(name)
@@ -79,8 +79,8 @@ func selectFollowImportsExampleFixtures[T any](fixtures []followImportsExampleFi
 	return selected, nil
 }
 
-func writeFollowImportsExampleFixtures[T any](baseDir string, names []string, command string, fixtures []followImportsExampleFixture[T], render func(T, bool) ([]byte, error)) ([]string, error) {
-	selected, err := selectFollowImportsExampleFixtures(fixtures, names, command)
+func writeCommandExampleFixtures[T any](baseDir string, names []string, command string, fixtures []commandExampleFixture[T], render func(T, bool) ([]byte, error)) ([]string, error) {
+	selected, err := selectCommandExampleFixtures(fixtures, names, command)
 	if err != nil {
 		return nil, err
 	}
@@ -102,13 +102,13 @@ func writeFollowImportsExampleFixtures[T any](baseDir string, names []string, co
 	return writtenPaths, nil
 }
 
-func listFollowImportsExamples[T any](fixtures []followImportsExampleFixture[T], w io.Writer) error {
+func listCommandExamples[T any](fixtures []commandExampleFixture[T], w io.Writer) error {
 	for _, fixture := range fixtures {
 		format := "text"
 		if fixture.JSON {
 			format = "json"
 		}
-		if _, err := fmt.Fprintf(w, "example=%s path=%s format=%s\n", fixture.Name, filepath.Join(cleanupFollowImportsExampleDirName, fixture.RelativePath), format); err != nil {
+		if _, err := fmt.Fprintf(w, "example=%s path=%s format=%s\n", fixture.Name, filepath.Join(commandExampleDirName, fixture.RelativePath), format); err != nil {
 			return err
 		}
 	}
@@ -429,11 +429,11 @@ func auditFollowImportsExampleFixtures() []auditFollowImportsExampleFixture {
 }
 
 func selectCleanupFollowImportsExampleFixtures(names []string) ([]cleanupFollowImportsExampleFixture, error) {
-	return selectFollowImportsExampleFixtures(cleanupFollowImportsExampleFixtures(), names, "cleanup-follow-imports")
+	return selectCommandExampleFixtures(cleanupFollowImportsExampleFixtures(), names, "cleanup-follow-imports")
 }
 
 func selectAuditFollowImportsExampleFixtures(names []string) ([]auditFollowImportsExampleFixture, error) {
-	return selectFollowImportsExampleFixtures(auditFollowImportsExampleFixtures(), names, "audit-follow-imports")
+	return selectCommandExampleFixtures(auditFollowImportsExampleFixtures(), names, "audit-follow-imports")
 }
 
 func renderCleanupFollowImportsExample(report cleanupFollowImportsReport, jsonOutput bool) ([]byte, error) {
@@ -459,17 +459,17 @@ func renderAuditFollowImportsExample(report auditFollowImportsReport, jsonOutput
 }
 
 func writeCleanupFollowImportsExampleFixtures(baseDir string, names []string) ([]string, error) {
-	return writeFollowImportsExampleFixtures(baseDir, names, "cleanup-follow-imports", cleanupFollowImportsExampleFixtures(), renderCleanupFollowImportsExample)
+	return writeCommandExampleFixtures(baseDir, names, "cleanup-follow-imports", cleanupFollowImportsExampleFixtures(), renderCleanupFollowImportsExample)
 }
 
 func writeAuditFollowImportsExampleFixtures(baseDir string, names []string) ([]string, error) {
-	return writeFollowImportsExampleFixtures(baseDir, names, "audit-follow-imports", auditFollowImportsExampleFixtures(), renderAuditFollowImportsExample)
+	return writeCommandExampleFixtures(baseDir, names, "audit-follow-imports", auditFollowImportsExampleFixtures(), renderAuditFollowImportsExample)
 }
 
 func listCleanupFollowImportsExamples(w io.Writer) error {
-	return listFollowImportsExamples(cleanupFollowImportsExampleFixtures(), w)
+	return listCommandExamples(cleanupFollowImportsExampleFixtures(), w)
 }
 
 func listAuditFollowImportsExamples(w io.Writer) error {
-	return listFollowImportsExamples(auditFollowImportsExampleFixtures(), w)
+	return listCommandExamples(auditFollowImportsExampleFixtures(), w)
 }