hypignore usage policy: .hypignore capture-seam drop (LLP 0049/0052/0053)

README.md

@@ -219,6 +219,7 @@ hyp smoke walkthrough_picker_to_first_query
 hyp smoke client_attach_idempotent
 hyp smoke gateway_claude_capture
 hyp smoke gateway_codex_capture
+hyp smoke hypignore_capture_drop
 hyp smoke otel_loopback_capture
 hyp smoke local_parquet_export
 hyp smoke status_diagnostics

collectivus-plugin-kernel-types.d.ts

@@ -17,6 +17,7 @@
 
 import type { AsyncDataSource, ScanOptions, ScanResults } from 'squirreling'
 import type { CachePartitioningDeclaration } from './src/core/iceberg/types.d.ts'
+import type { UsagePolicyDrop } from './src/core/usage-policy/types.d.ts'
 
 export type { AsyncDataSource, ScanOptions, ScanResults }
 
@@ -1463,6 +1464,12 @@ export interface AiGatewayClientStatusContext {
  * no projector succeeds the gateway still emits pass-through
  * telemetry (the `aigw.exchange` log and `aigw.exchange_bytes` meter)
  * but writes zero rows into `ai_gateway_messages`.
+ *
+ * Returning the `USAGE_POLICY_DROP` sentinel is distinct from declining
+ * with `undefined`: it is a TERMINAL `.hypignore` usage-policy drop
+ * (LLP 0050). The dispatcher stops the projector walk on it (no later
+ * projector is consulted) and logs it as an intentional drop, never as
+ * a `no_projector_match` miss, while still writing zero rows.
  */
 export interface AiGatewayExchangeProjector {
   name: string
@@ -1471,7 +1478,11 @@ export interface AiGatewayExchangeProjector {
   project(
     input: AiGatewayExchangeInput,
     ctx: AiGatewayExchangeProjectorContext
-  ): AiGatewayProjectedExchange | Promise<AiGatewayProjectedExchange | undefined> | undefined
+  ):
+    | AiGatewayProjectedExchange
+    | UsagePolicyDrop
+    | Promise<AiGatewayProjectedExchange | UsagePolicyDrop | undefined>
+    | undefined
 }
 
 export interface AiGatewayExchangeProjectorContext {

hypaware-core/plugins-workspace/ai-gateway/src/message_projector.js

@@ -2,11 +2,14 @@
 
 import { createHash } from 'node:crypto'
 
+import { isUsagePolicyDrop } from '../../../../src/core/usage-policy/index.js'
+
 export const SCHEMA_VERSION = 7
 
 /**
  * @import { AiGatewayExchangeInput, AiGatewayProjectedExchange, AiGatewayProjectedMessage, CachePartitionMeta, ColumnSpec, PluginLogger, QueryStorageService } from '../../../../collectivus-plugin-kernel-types.js'
  * @import { ExtendedQueryStorageService } from '../../../../src/core/cache/types.js'
+ * @import { UsagePolicyDrop } from '../../../../src/core/usage-policy/types.js'
  * @import { RegisteredProjector } from './types.js'
  */
 
@@ -165,6 +168,20 @@ export function createAiGatewayMessageProjector(opts) {
     async projectExchange(exchange) {
       const input = /** @type {AiGatewayExchangeInput} */ (exchange)
       const projection = await dispatchProjector(projectors, input, log)
+      // An intentional `.hypignore` usage-policy drop is a TERMINAL success, not
+      // a projection miss: the adapter already logged the rich
+      // `plugin.<adapter>.usage_policy_drop` event at the seam, so the gateway
+      // records the drop at info level (NOT the `no_projector_match` warn below,
+      // which would mislabel a privacy drop as a failure) and writes no rows.
+      // @ref LLP 0050 [implements]
+      if (isUsagePolicyDrop(projection)) {
+        log?.info?.('aigw.usage_policy_drop', {
+          exchange_id: stringValue(input.exchange_id) ?? '',
+          upstream: stringValue(input.upstream) ?? '',
+          reason: 'usage_policy_drop',
+        })
+        return []
+      }
       if (!projection) {
         log?.warn?.('aigw.message_projection_skipped', {
           exchange_id: stringValue(input.exchange_id) ?? '',
@@ -490,7 +507,7 @@ export function aiGatewayRowsFromProjectedExchange(projection, opts = {}) {
  * @param {RegisteredProjector[]} projectors
  * @param {AiGatewayExchangeInput} input
  * @param {{ warn?: (m: string, f?: Record<string, unknown>) => void } | undefined} log
- * @returns {Promise<AiGatewayProjectedExchange | undefined>}
+ * @returns {Promise<AiGatewayProjectedExchange | UsagePolicyDrop | undefined>}
  */
 async function dispatchProjector(projectors, input, log) {
   if (projectors.length === 0) return undefined
@@ -509,6 +526,12 @@ async function dispatchProjector(projectors, input, log) {
       })
       continue
     }
+    // A usage-policy drop is TERMINAL: stop the walk and propagate the sentinel
+    // so the drop wins outright. Crucially we do NOT `continue` here (which is
+    // what a bare `undefined` decline does below) so a later overlapping
+    // projector can never record an exchange the user asked to suppress.
+    // @ref LLP 0050 [implements]
+    if (isUsagePolicyDrop(result)) return result
     if (!isValidProjection(result)) {
       if (result !== undefined) {
         log?.warn?.('aigw.projector_invalid_output', {

hypaware-core/plugins-workspace/claude/src/backfill.js

@@ -9,10 +9,12 @@ import {
 import { pickLatestMatching, readSessionContext } from './session_context.js'
 import { deriveRepoFromCwd } from './git_repo.js'
 import { anthropicMessageAttributes } from './anthropic.js'
+import { createUsagePolicyResolver } from '../../../../src/core/usage-policy/index.js'
 
 /**
  * @import { AiGatewayProjectedExchange, AiGatewayProjectedMessage, BackfillContribution, BackfillItem, BackfillProvenance, BackfillRunContext, JsonObject, PluginLogger } from '../../../../collectivus-plugin-kernel-types.js'
  * @import { SessionContextRecord, TranscriptEntry } from './types.js'
+ * @import { UsagePolicyResolver } from '../../../../src/core/usage-policy/types.js'
  */
 
 /**
@@ -66,6 +68,7 @@ const DAY_MS = 24 * 60 * 60 * 1000
  *   clientName?: string,
  *   pluginName?: string,
  *   deriveRepo?: (cwd: string | undefined) => Promise<{ git_remote?: string, repo_root?: string }>,
+ *   resolver?: UsagePolicyResolver,
  * }} opts
  * @returns {BackfillContribution}
  */
@@ -78,14 +81,18 @@ export function createClaudeBackfillProvider(opts) {
   // recover it by running git in the session's cwd at backfill time. Injectable
   // so tests stub the git lookup and stay hermetic.
   const deriveRepo = opts.deriveRepo ?? deriveRepoFromCwd
+  // One resolver per backfill run (LLP 0050): the per-cwd cache reflects disk at
+  // run time and is shared across the whole scan. Injectable for hermetic tests.
+  // @ref LLP 0050 [implements]: skip ignored sessions at the capture seam.
+  const resolver = opts.resolver ?? createUsagePolicyResolver()
 
   return {
     name: clientName,
     plugin: pluginName,
     datasets: [AI_GATEWAY_MESSAGES_DATASET],
     summary: 'Import local Claude Code transcripts into ai_gateway_messages',
     async *run(ctx) {
-      yield* runClaudeBackfill({ ctx, projectsDir, stateFile, clientName, deriveRepo })
+      yield* runClaudeBackfill({ ctx, projectsDir, stateFile, clientName, deriveRepo, resolver })
     },
   }
 }
@@ -103,11 +110,12 @@ export function createClaudeBackfillProvider(opts) {
  *   stateFile: string,
  *   clientName: string,
  *   deriveRepo: (cwd: string | undefined) => Promise<{ git_remote?: string, repo_root?: string }>,
+ *   resolver: UsagePolicyResolver,
  * }} args
  * @returns {AsyncGenerator<BackfillItem>}
  */
 async function* runClaudeBackfill(args) {
-  const { ctx, projectsDir, stateFile, clientName, deriveRepo } = args
+  const { ctx, projectsDir, stateFile, clientName, deriveRepo, resolver } = args
   const log = ctx.log
   const window = resolveWindow(ctx)
   // Many sessions share a cwd (the same repo, often the same checkout), and
@@ -166,11 +174,36 @@ async function* runClaudeBackfill(args) {
 
     for (const [sessionId, sessionEntries] of groupBySession(entries)) {
       const windowed = filterByWindow(sessionEntries, window)
+      const record = pickLatestMatching(sessionRecords, { sessionId, transcriptPath: filePath })
+
+      // @ref LLP 0050 [implements]: capture-seam drop for backfill. Skip an
+      // ignored session BEFORE projecting/writing it, else `hyp backfill` would
+      // silently re-import the exact sessions ignored live (LLP 0049#requirements
+      // R1). The cwd precedence mirrors projectedExchangeFromEntries (the
+      // hook-written record wins, else the first transcript line's cwd), so the
+      // session is tested on the same cwd the row would have carried.
+      const sessionCwd = record?.cwd ?? windowed.find((entry) => entry.cwd)?.cwd
+      const sessionPolicy = sessionCwd ? resolver.resolve(sessionCwd) : null
+      if (sessionPolicy?.class === 'ignore') {
+        // A fail-safe clamp (declared token unimplemented) escalates to warn
+        // so an operator can tell it from an intended ignore (R3 SHOULD).
+        log[sessionPolicy.warn ? 'warn' : 'info']('claude.backfill.usage_policy_drop', {
+          component: 'plugin.claude.backfill',
+          operation: 'usage_policy_drop',
+          session_id: sessionId,
+          declared: sessionPolicy.declared,
+          governed_by: sessionPolicy.governedBy,
+          status: 'ok',
+          ...(sessionPolicy.warn ? { warn: sessionPolicy.warn } : {}),
+        })
+        continue
+      }
+
       const exchange = await projectedExchangeFromEntries({
         sessionId,
         entries: windowed,
         clientName,
-        record: pickLatestMatching(sessionRecords, { sessionId, transcriptPath: filePath }),
+        record,
         agentMeta,
         deriveRepo: deriveRepoCached,
       })

hypaware-core/plugins-workspace/claude/src/projector.js

@@ -33,10 +33,12 @@ import {
   pickLatestMatching,
   readSessionContext,
 } from './session_context.js'
+import { createUsagePolicyResolver, USAGE_POLICY_DROP } from '../../../../src/core/usage-policy/index.js'
 
 /**
  * @import { AiGatewayExchangeInput, AiGatewayExchangeProjector, AiGatewayProjectedExchange, AiGatewayProjectedMessage, AiGatewayUpstreamPreset, JsonObject } from '../../../../collectivus-plugin-kernel-types.js'
  * @import { TranscriptEntry } from './types.js'
+ * @import { UsagePolicyResolver } from '../../../../src/core/usage-policy/types.js'
  */
 
 /**
@@ -80,6 +82,7 @@ import {
  *   projectsDir?: string,
  *   clientName?: string,
  *   logger?: { warn(message: string, fields?: Record<string, unknown>): void, debug?: (m: string, f?: Record<string, unknown>) => void },
+ *   resolver?: UsagePolicyResolver,
  * }} opts
  * @returns {AiGatewayExchangeProjector}
  */
@@ -89,6 +92,11 @@ export function createClaudeExchangeProjector(opts) {
   const clientName = opts.clientName ?? 'claude'
   const logger = opts.logger
   const sessionContextCache = createSessionContextCache()
+  // One resolver per projector (per daemon run): the per-cwd cache rides the
+  // projector's lifetime so the capture hot path adds no unbounded fs work.
+  // @ref LLP 0050 [implements]: the .hypignore capture-seam drop lives in the
+  // client adapter, the only place that resolves a cwd; injectable for tests.
+  const resolver = opts.resolver ?? createUsagePolicyResolver()
 
   return {
     name: 'claude-anthropic-messages',
@@ -152,6 +160,33 @@ export function createClaudeExchangeProjector(opts) {
           sessionId,
         })
         : undefined
+
+      // @ref LLP 0050 [implements]: capture-seam drop. Once the exchange's cwd
+      // is resolved, an ancestor `.hypignore` that resolves to `ignore` means
+      // this exchange is never recorded: return BEFORE building any rows, so the
+      // gateway source's write guard (`if (messageRows.length > 0)`) persists
+      // nothing. The response has already streamed to the client, so the live
+      // LLM call is untouched (LLP 0049#requirements R2). The drop returns the
+      // terminal `USAGE_POLICY_DROP` sentinel (NOT a bare `undefined`): the
+      // dispatcher stops the projector walk on it so no later projector can
+      // record the suppressed exchange, and logs it as a drop rather than a
+      // `no_projector_match` miss.
+      const cwd = sessionContextRecord?.cwd
+      const policy = cwd ? resolver.resolve(cwd) : null
+      if (policy?.class === 'ignore') {
+        // A fail-safe clamp (declared token unimplemented) escalates to warn
+        // so an operator can tell it from an intended ignore (R3 SHOULD).
+        ctx.log[policy.warn ? 'warn' : 'info']('plugin.claude.usage_policy_drop', {
+          component: 'claude',
+          operation: 'usage_policy_drop',
+          exchange_id: input.exchange_id,
+          declared: policy.declared,
+          governed_by: policy.governedBy,
+          ...(policy.warn ? { warn: policy.warn } : {}),
+        })
+        return USAGE_POLICY_DROP
+      }
+
       const transcriptEntries = sessionId
         ? await loadTranscriptSafe({
           projectsDir,

hypaware-core/plugins-workspace/codex/src/backfill.js

@@ -3,11 +3,13 @@
 import fs from 'node:fs/promises'
 import path from 'node:path'
 
+import { createUsagePolicyResolver } from '../../../../src/core/usage-policy/index.js'
 import { redactRemoteUserinfo } from './git-remote.js'
 
 /**
  * @import { AiGatewayProjectedExchange, AiGatewayProjectedMessage, BackfillContribution, BackfillEvent, BackfillItem, BackfillProvenance, BackfillRunContext, JsonObject, JsonValue, PluginLogger } from '../../../../collectivus-plugin-kernel-types.js'
  * @import { CodexRolloutItem, CodexRolloutSession } from './types.js'
+ * @import { UsagePolicyResolver } from '../../../../src/core/usage-policy/types.js'
  */
 
 /**
@@ -74,6 +76,7 @@ const DAY_MS = 24 * 60 * 60 * 1000
  *   unsupportedLocations?: Array<{ kind: string, path: string }>,
  *   clientName?: string,
  *   pluginName?: string,
+ *   resolver?: UsagePolicyResolver,
  * }} opts
  * @returns {BackfillContribution}
  */
@@ -83,14 +86,17 @@ export function createCodexBackfillProvider(opts) {
   const codexHome = opts.codexHome ?? defaultCodexHome(opts.homeDir)
   const sessionsDir = opts.sessionsDir ?? path.join(codexHome, 'sessions')
   const unsupportedLocations = opts.unsupportedLocations ?? defaultUnsupportedLocations(opts.homeDir)
+  // One `.hypignore` resolver per backfill run, holding its per-cwd cache for
+  // the whole scan (LLP 0049 R6).
+  const resolver = opts.resolver ?? createUsagePolicyResolver()
 
   return {
     name: clientName,
     plugin: pluginName,
     datasets: [AI_GATEWAY_MESSAGES_DATASET],
     summary: 'Import local Codex session rollouts into ai_gateway_messages',
     async *run(ctx) {
-      yield* runCodexBackfill({ ctx, codexHome, sessionsDir, unsupportedLocations, clientName })
+      yield* runCodexBackfill({ ctx, codexHome, sessionsDir, unsupportedLocations, clientName, resolver })
     },
   }
 }
@@ -131,11 +137,12 @@ function defaultUnsupportedLocations(homeDir) {
  *   sessionsDir: string,
  *   unsupportedLocations: Array<{ kind: string, path: string }>,
  *   clientName: string,
+ *   resolver: UsagePolicyResolver,
  * }} args
  * @returns {AsyncGenerator<BackfillItem | BackfillEvent>}
  */
 async function* runCodexBackfill(args) {
-  const { ctx, codexHome, sessionsDir, unsupportedLocations, clientName } = args
+  const { ctx, codexHome, sessionsDir, unsupportedLocations, clientName, resolver } = args
   const log = ctx.log
   const window = resolveWindow(ctx)
 
@@ -158,6 +165,7 @@ async function* runCodexBackfill(args) {
 
   let filesSeen = 0
   let sessionsProjected = 0
+  let sessionsIgnored = 0
   let messagesProjected = 0
 
   for (const filePath of await listRolloutFiles(sessionsDir)) {
@@ -180,6 +188,29 @@ async function* runCodexBackfill(args) {
     }
 
     for (const session of sessions) {
+      // @ref LLP 0050 [implements]: capture-seam drop for backfill, symmetric
+      // to the @hypaware/claude backfill skip. A session whose recorded cwd has
+      // an ancestor `.hypignore` of class `ignore` is skipped before projecting
+      // or yielding any row, so `hyp backfill` never re-imports the exact
+      // sessions ignored live (LLP 0049 R1).
+      const sessionPolicy = session.cwd ? resolver.resolve(session.cwd) : null
+      if (sessionPolicy?.class === 'ignore') {
+        sessionsIgnored += 1
+        // A fail-safe clamp (declared token unimplemented) escalates to warn
+        // so an operator can tell it from an intended ignore (R3 SHOULD).
+        log[sessionPolicy.warn ? 'warn' : 'info']('codex.backfill.usage_policy_drop', {
+          component: COMPONENT,
+          operation: 'usage_policy_drop',
+          conversation_id: session.sessionId,
+          class: 'ignore',
+          declared: sessionPolicy.declared,
+          governed_by: sessionPolicy.governedBy,
+          status: 'skipped',
+          ...(sessionPolicy.warn ? { warn: sessionPolicy.warn } : {}),
+        })
+        continue
+      }
+
       const exchange = projectedExchangeFromSession({
         session,
         items: filterByWindow(session.items, window),
@@ -211,6 +242,7 @@ async function* runCodexBackfill(args) {
     operation: 'backfill.scan',
     files_seen: filesSeen,
     sessions_projected: sessionsProjected,
+    sessions_ignored: sessionsIgnored,
     messages_projected: messagesProjected,
     status: 'ok',
   })