@skyhook-io/k8s-ui 1.18.0 → 1.18.2

package/src/utils/gitops-write-guard.test.ts

@@ -9,6 +9,7 @@ import {
   type GitOpsPathEvidence,
   type GitOpsWrite,
   type GitOpsWriteEvidence,
+  gitOpsWriteHeadline,
   type GitOpsWriteGuardInput,
   type GitOpsWritePolicyEvidence,
 } from './gitops-write-guard'
@@ -399,3 +400,334 @@ describe('copy', () => {
     }
   })
 })
+
+describe('manager answer composition', () => {
+  const a = { kind: 'Application', group: 'argoproj.io', namespace: 'argocd', name: 'a' }
+  const b = { ...a, name: 'b' }
+  const subject = { kind: 'Pod', namespace: 'db', name: 'pg-1' }
+  const parent = { kind: 'Deployment', group: 'apps', namespace: 'db', name: 'pg' }
+  const claim = { manager: a, source: 'argo-instance-label' as const, check: 'omitted' as const, weak: true }
+  const shared: import('../types/core').ManagerAnswer = { state: 'shared', lead: a, direct: { object: subject, recorders: [a, b] } }
+  const via: import('../types/core').ManagerAnswer = { state: 'listed', lead: b, direct: { object: subject }, via: { object: parent, recorders: [b] } }
+  const run = (manager: import('../types/core').ManagerAnswer, writes = [hibernate], extra: Partial<GitOpsWriteGuardInput> = {}) =>
+    guard({ manager, writes, evidence: evidence(selfHeal, [pathEvidence({ lastApplied: 'present', ignored: 'effective' })]), ...extra })
+
+  it('disagree field writes warn with both names despite a self-heal policy', () => {
+    const g = run({ state: 'disagree', direct: { object: subject, recorders: [b], claims: [claim] } })
+    expect(g.level).toBe('may-revert')
+    expect(g.summary).toContain('Application argocd/a and Application argocd/b')
+    expect(g.owner).toBeNull()
+  })
+
+  it('shared field writes cannot use one candidate’s ignore rule or policy exemption', () => {
+    const g = run(shared)
+    expect(g.level).toBe('may-revert')
+    expect(g.requiresAck).toBe(true)
+    expect(g.summary).toContain('argocd/a')
+    expect(g.summary).toContain('argocd/b')
+    expect(g.syncPolicy).toBeNull()
+  })
+
+  it('several claims without a lead warn in the plural', () => {
+    const g = run({ state: 'claimed', direct: { object: subject, claims: [claim, { ...claim, manager: b }] } })
+    expect(g.level).toBe('may-revert')
+    expect(g.summary).toContain('argocd/a and Application argocd/b')
+  })
+
+  it.each(['metadata', 'spec', 'delete'] as const)('via without an active direct claim makes %s informational without acknowledgment', scope => {
+    const g = run({ ...via, direct: { object: subject, claims: [{ ...claim, copied: true }] } }, [{ scope, paths: [HIBERNATE] }])
+    expect(g.level).toBe('info')
+    expect(g.requiresAck).toBe(false)
+    expect(g.summary).toContain('Deployment db/pg')
+    expect(g.summary).toContain('Application argocd/b')
+    if (scope === 'delete') expect(g.summary).toContain('controller recreates it from')
+  })
+
+  it('native Helm annotations do not compete with a GitOps ancestor', () => {
+    const helm = { kind: 'HelmRelease', group: '', namespace: 'db', name: 'chart' }
+    const g = run({ ...via, direct: { object: subject, claims: [{ manager: helm, source: 'helm-release', check: 'not-recording', weak: true }] } })
+    expect(g.level).toBe('info')
+    expect(g.requiresAck).toBe(false)
+    expect(g.summary).not.toContain('HelmRelease')
+  })
+
+  it.each(['disagree', 'shared', 'claimed'] as const)('%s deletes without a lead warn with every candidate', state => {
+    const direct = state === 'claimed' ? { object: subject, claims: [claim, { ...claim, manager: b }] } : { object: subject, recorders: state === 'shared' ? [a, b] : [b], claims: [claim] }
+    const g = run({ state, direct }, [{ scope: 'delete' }])
+    expect(g.level).toBe('may-revert')
+    expect(g.summary).toContain('Application argocd/a')
+    expect(g.summary).toContain('Application argocd/b')
+  })
+
+  it('via with a weak non-copied direct claim keeps the field warning', () => {
+    const g = run({ ...via, direct: { object: subject, claims: [claim] } })
+    expect(g.level).toBe('may-revert')
+    expect(g.requiresAck).toBe(true)
+    expect(g.summary).toContain('argocd/a')
+    expect(g.summary).toContain('Deployment db/pg')
+  })
+
+  it.each([shared, via])('status writes remain none', manager => {
+    expect(run(manager, [{ scope: 'status' }]).level).toBe('none')
+  })
+
+  it('shared create-child stays informational', () => {
+    expect(run(shared, [{ scope: 'create-child' }]).level).toBe('info')
+  })
+
+  it('operator-owned delete stays informational', () => {
+    expect(run(shared, [{ scope: 'delete' }], { operatorOwner: { kind: 'Cluster', name: 'pg' } }).level).toBe('info')
+  })
+
+  it.each([shared, via])('empty wildcard stays none', manager => {
+    expect(run(manager, [hibernate], { evidence: evidence(selfHeal, [pathEvidence({ empty: true })]) }).level).toBe('none')
+  })
+
+  it('a single agreeing candidate with declared field evidence can still prove will-revert', () => {
+    const manager = { state: 'agree' as const, lead: a, direct: { object: subject, recorders: [a], claims: [{ manager: a, source: 'argo-tracking-id' as const, check: 'recorded' as const }] } }
+    expect(run(manager, [hibernate], { evidence: evidence(selfHeal, [pathEvidence({ lastApplied: 'present' })]) }).level).toBe('will-revert')
+  })
+
+  // A list alone can name an object its manager never syncs: a copy carrying
+  // another object's tracking ID, a CRD a HelmRelease skips.
+  it.each([hibernate, { scope: 'delete' as const }])('a list without metadata naming its manager promises no revert (%o)', write => {
+    const manager = { state: 'listed' as const, lead: a, direct: { object: subject, recorders: [a], claims: [{ manager: b, source: 'argo-tracking-id' as const, check: 'missing' as const, copied: true }] } }
+    const g = run(manager, [write], { evidence: evidence(selfHeal, [pathEvidence({ lastApplied: 'present' })]) })
+    expect(g.level).toBe('may-revert')
+    expect(g.summary).toContain("Radar can't confirm Application argocd/a applies this object")
+    // The field evidence stays, behind the condition.
+    expect(g.summary).toMatch(/If it does: .+/)
+  })
+
+  it('a parent the managers disagree on says which names it and which lists it', () => {
+    const g = run({ state: 'disagree', direct: { object: subject }, via: { object: parent, recorders: [b], claims: [{ manager: a, source: 'argo-tracking-id', check: 'omitted' }] } })
+    expect(g.level).toBe('info')
+    expect(g.summary).toContain('whose metadata names Application argocd/a, while Application argocd/b lists it in its status')
+  })
+
+  // A CronJob's Job runs once: deleting it, even one created by hand, gets no
+  // replacement, whatever manages the CronJob.
+  it("a CronJob's Job is not said to be recreated", () => {
+    const cron = { kind: 'CronJob', group: 'batch', namespace: 'db', name: 'backup' }
+    const g = run({ state: 'agree', lead: a, direct: { object: subject }, via: { object: cron, recorders: [a], claims: [{ manager: a, source: 'argo-tracking-id', check: 'recorded' }] } }, [{ scope: 'delete' }], { operatorOwner: { kind: 'CronJob', name: 'backup' } })
+    expect(g.level).toBe('info')
+    expect(g.summary).toContain('nothing is expected to recreate it')
+    expect(g.summary).toContain('CronJob db/backup can still create new ones on its schedule')
+    expect(g.summary).not.toContain('recreates it')
+  })
+
+  // A newer Radar's state with no lead, or one candidate of a kind this UI
+  // can't open, still warns.
+  it.each([
+    ['an unfamiliar state without a lead', { state: 'future-state' as never, direct: { object: subject, recorders: [a] } }],
+    ['an unfamiliar manager kind', { state: 'claimed' as const, lead: { kind: 'Stack', group: 'example.io', namespace: 'x', name: 's' }, direct: { object: subject, claims: [{ manager: { kind: 'Stack', group: 'example.io', namespace: 'x', name: 's' }, source: 'argo-tracking-id' as never, check: 'omitted' as const }] } }],
+  ])('%s still warns on field writes and deletes', (_, manager) => {
+    for (const write of [hibernate, { scope: 'delete' as const }]) {
+      const g = run(manager, [write])
+      expect(g.level).toBe('may-revert')
+      expect(g.requiresAck).toBe(true)
+    }
+  })
+
+  it('a chain end this UI does not know keeps the conservative warning', () => {
+    const g = run({ state: 'unknown', direct: { object: subject }, chainEnd: 'future-stop' as never }, [hibernate])
+    expect(g.level).toBe('may-revert')
+    expect(g.requiresAck).toBe(true)
+  })
+
+  it('an agreeing answer whose manager kind this UI does not know still warns', () => {
+    const stack = { kind: 'Stack', group: 'example.io', namespace: 'x', name: 's' }
+    for (const write of [hibernate, { scope: 'delete' as const }]) {
+      const g = run({ state: 'agree', lead: stack, direct: { object: subject, recorders: [stack], claims: [{ manager: stack, source: 'argo-tracking-id', check: 'recorded' }] } }, [write])
+      expect(g.level).toBe('may-revert')
+    }
+  })
+
+  // A fallback via whose walk stopped at an unreadable owner may have missed
+  // a manager above it: a delete isn't just informational.
+  it('a delete through a fallback via with an unread chain keeps the warning', () => {
+    const g = run({ state: 'claimed', lead: a, direct: { object: subject }, via: { object: parent, claims: [{ manager: a, source: 'argo-instance-label', check: 'omitted', weak: true }] }, chainEnd: 'unfollowed', stop: { at: parent, state: 'unknown' } }, [{ scope: 'delete' }])
+    expect(g.level).toBe('may-revert')
+    expect(g.requiresAck).toBe(true)
+  })
+
+  it('a state this UI does not know is read as claimed', () => {
+    const g = run({ state: 'future-state' as never, lead: a, direct: { object: subject, recorders: [a] } }, [hibernate], { evidence: evidence(selfHeal, [pathEvidence({ lastApplied: 'present' })]) })
+    expect(g.level).toBe('may-revert')
+  })
+
+  // The schedule belongs to the Job's own CronJob, even when the answer came
+  // from an ancestor above it.
+  it("names the Job's own CronJob for future runs, not the answering ancestor", () => {
+    const op = { kind: 'Widget', group: 'example.io', namespace: 'db', name: 'pg' }
+    const g = run({ state: 'agree', lead: a, direct: { object: subject }, via: { object: op, recorders: [a], claims: [{ manager: a, source: 'argo-tracking-id', check: 'recorded' }] } }, [{ scope: 'delete' }], { operatorOwner: { kind: 'CronJob', name: 'backup' } })
+    expect(g.summary).toContain('but CronJob ')
+    expect(g.summary).toContain('backup can still create new ones on its schedule')
+    expect(g.summary).not.toContain('Widget db/pg can still')
+  })
+
+  it('an informational note on a list-only answer says listed, not managed', () => {
+    const g = run({ state: 'listed', lead: a, direct: { object: subject, recorders: [a] } }, [{ scope: 'create-child' }])
+    expect(g.level).toBe('info')
+    expect(gitOpsWriteHeadline(g)).toBe('Listed by Argo CD Application argocd/a.')
+  })
+
+  it('a parent the metadata alone names is not said to be managed', () => {
+    const g = run({ state: 'claimed', lead: a, direct: { object: subject }, via: { object: parent, claims: [{ manager: a, source: 'argo-tracking-id', check: 'missing' }] } })
+    expect(g.level).toBe('info')
+    expect(g.summary).toContain('whose metadata names Application argocd/a')
+    expect(g.summary).not.toContain('manages')
+  })
+
+  it('an adopted Helm release keeps its upgrade risk past an Argo CD ignore rule', () => {
+    const helm = { kind: 'HelmRelease', group: '', namespace: 'db', name: 'chart' }
+    const manager = { state: 'agree' as const, lead: a, direct: { object: subject, recorders: [a], claims: [
+      { manager: a, source: 'argo-tracking-id' as const, check: 'recorded' as const },
+      { manager: helm, source: 'helm-release' as const, check: 'not-recording' as const },
+    ] } }
+    const g = run(manager)
+    expect(g.level).toBe('may-revert')
+    expect(g.summary).toContain('Helm release db/chart')
+  })
+
+  const agree = { state: 'agree' as const, lead: a, direct: { object: subject, recorders: [a], claims: [{ manager: a, source: 'argo-tracking-id' as const, check: 'recorded' as const }] } }
+
+  it('a refused live answer drops the cached answer and the owner hint', () => {
+    const g = run(agree, [hibernate], { evidence: evidence(selfHeal, [pathEvidence({ lastApplied: 'present', ignored: 'effective' })], { managerUnavailable: 'objects_changed' }) })
+    expect(g.level).toBe('may-revert')
+    expect(g.owner).toBeNull()
+    expect(g.summary).toContain("Radar couldn't check what manages this resource right now (the read failed)")
+    expect(g.summary).not.toContain('objects_changed')
+  })
+
+  it.each([
+    ['kind_sync_pending', '(still loading)', true],
+    ['read_error', '(the read failed)', true],
+    ['user_forbidden', '(you may not list it)', false],
+    // Spellings an older Radar sends read as the code they became.
+    ['kind_sync_failed', '(loading is overdue)', true],
+    ['rbac_denied', '(you may not list it)', false],
+  ])('a refused live answer explains %s in words', (code, words, reopen) => {
+    const g = run(agree, [hibernate], { evidence: evidence(selfHeal, [], { managerUnavailable: code }) })
+    expect(g.summary).toContain(words)
+    expect(g.summary).not.toContain(code)
+    expect(g.summary.includes('Close and reopen this dialog to check again.')).toBe(reopen)
+  })
+
+  it("a failed request keeps the request's own message", () => {
+    const g = run(agree, [hibernate], { evidence: undefined, evidenceError: 'Request timed out' })
+    expect(g.summary).toContain('(Request timed out)')
+    expect(g.summary).not.toContain('reopen')
+  })
+
+  it("a failed live check doesn't keep a cached via answer's reassurance", () => {
+    const g = run(via, [hibernate], { evidence: undefined, evidenceError: 'forbidden' })
+    expect(g.level).toBe('may-revert')
+    expect(g.requiresAck).toBe(true)
+  })
+
+  it('a failed live check of a cached none stays quiet', () => {
+    const g = run({ state: 'none', direct: { object: subject } }, [hibernate], { evidence: undefined, evidenceError: 'timeout' })
+    expect(g.level).toBe('none')
+  })
+
+  it.each(['unknown', 'none'] as const)('server %s replaces client owner, Helm and manager inputs', state => {
+    const negative = { state, direct: { object: subject } }
+    const g = run(shared, [hibernate], { helmRelease: { namespace: 'db', name: 'old' }, evidence: evidence(selfHeal, [], { manager: negative }) })
+    expect(g.level).toBe('none')
+    expect(g.owner).toBeNull()
+    expect(g.helmRelease).toBeNull()
+  })
+
+  it('a stopped ancestor read retains conservative ownershipError behavior', () => {
+    const g = run({ state: 'unknown', direct: { object: subject }, stop: { at: subject, state: 'unknown', owner: parent } })
+    expect(g.level).toBe('may-revert')
+    expect(g.ownershipError).toContain("couldn't follow")
+  })
+
+  // A gone or replaced owner ends the chain with an answer: nothing above it
+  // was missed, so an object no manager names gets no warning.
+  it.each(['gone', 'replaced'] as const)('a walk ended by a %s owner is not an unread chain', state => {
+    const g = run({ state: 'none', direct: { object: subject }, chainEnd: 'unfollowed', stop: { at: subject, state, owner: parent } })
+    expect(g.level).toBe('none')
+    expect(g.ownershipError).toBeNull()
+  })
+
+  it('a stopped walk with a weak claim cannot use that candidate’s exemption', () => {
+    const g = run({ state: 'claimed', lead: a, direct: { object: subject, claims: [claim] }, stop: { at: subject, state: 'unknown', owner: parent } })
+    expect(g.level).toBe('may-revert')
+    expect(g.ownershipError).toContain("couldn't follow")
+  })
+
+  it('a failed target read retains conservative ownershipError behavior', () => {
+    const g = run({ state: 'unknown', direct: { object: subject } }, [hibernate], { ownershipError: 'Target read failed' })
+    expect(g.level).toBe('may-revert')
+    expect(g.ownershipError).toBe('Target read failed')
+  })
+
+  it('absent manager preserves legacy evidence verdicts', () => {
+    for (const policy of [selfHeal, manual, null]) {
+      const input = { writes: [hibernate], evidence: evidence(policy, [pathEvidence({ lastApplied: 'present' })]) }
+      expect(guard({ ...input, manager: undefined })).toEqual(guard(input))
+    }
+  })
+})
+
+
+// A ReplicaSet carries its Helm-installed Deployment's release annotations;
+// they are the Deployment's, so the ReplicaSet gets the generated-from note.
+it('a ReplicaSet of a plain Helm Deployment is generated from it, not claimed', () => {
+  const rs = { kind: 'ReplicaSet', group: 'apps', namespace: 'db', name: 'web-1' }
+  const release = { kind: 'HelmRelease', namespace: 'db', name: 'web' }
+  const g = guard({
+    target: rs,
+    manager: { state: 'claimed', lead: release,
+      direct: { object: rs, claims: [{ manager: release, source: 'helm-release', check: 'not-recording', weak: true }] },
+      via: { object: { kind: 'Deployment', group: 'apps', namespace: 'db', name: 'web' }, claims: [{ manager: release, source: 'helm-release', check: 'not-recording' }] } },
+    writes: [hibernate],
+  })
+  expect(g.level).toBe('info')
+  expect(g.requiresAck).toBe(false)
+})
+
+describe('unconfirmed manager boundaries', () => {
+  const app = { kind: 'Application', group: 'argoproj.io', namespace: 'argocd', name: 'candidate' }
+  const claimed: import('../types/core').ManagerAnswer = { state: 'claimed', lead: app, direct: { object: target, claims: [{ manager: app, source: 'argo-tracking-id', check: 'omitted' }] } }
+  it.each(['omitted', 'remote', 'unreadable', 'withheld', 'missing'] as const)('%s cannot prove a revert or waive acknowledgment', check => {
+    const manager = { ...claimed, direct: { object: target, claims: [{ ...claimed.direct.claims![0], check }] } }
+    for (const ignored of [undefined, 'effective'] as const) {
+      const g = guard({ manager, writes: [hibernate, { scope: 'delete' }], evidence: evidence(selfHeal, [pathEvidence({ lastApplied: 'present', ignored })]) })
+      expect(g.perWrite.map(w => w.level)).toEqual(['may-revert', 'may-revert'])
+      expect(g.requiresAck).toBe(true)
+      expect(g.syncPolicy).toBeNull()
+    }
+  })
+  // An opt-out on the target's own annotations holds whether or not the
+  // claimed manager's list names it.
+  it('an unconfirmed claim keeps an opt-out on the target itself', () => {
+    const g = guard({ manager: claimed, writes: [hibernate, { scope: 'delete' }], evidence: evidence({ ...selfHeal, objectReconcile: 'ignore' }, [pathEvidence({ lastApplied: 'present' })]) })
+    expect(g.perWrite.map(w => w.level)).toEqual(['info', 'info'])
+    expect(g.requiresAck).toBe(false)
+  })
+  // A tracking ID and an instance label on one Application are one manager.
+  it('a namespaced and an unqualified claim on one Application are one candidate', () => {
+    const manager = { ...claimed, direct: { object: target, claims: [
+      { manager: app, source: 'argo-tracking-id' as const, check: 'omitted' as const },
+      { manager: { ...app, namespace: '' }, source: 'argo-instance-label' as const, check: 'unresolved' as const },
+    ] } }
+    const g = guard({ manager, writes: [hibernate], evidence: evidence(selfHeal, [pathEvidence({ lastApplied: 'present' })]) })
+    expect(g.summary).not.toContain(' and ')
+    expect(g.summary).not.toContain("A single manager's ignore rules")
+  })
+  it.each(['cycle', 'truncated'] as const)('%s ancestry remains conservative without a stop object', chainEnd => {
+    const g = guard({ manager: { state: 'unknown', direct: { object: target }, chainEnd }, writes: [hibernate, { scope: 'delete' }] })
+    expect(g.perWrite.map(w => w.level)).toEqual(['may-revert', 'may-revert'])
+    expect(g.ownershipError).toContain("couldn't follow")
+  })
+  it('stopped claimed deletes retain the floor after the operator rule', () => {
+    const manager = { ...claimed, stop: { at: target, state: 'unknown' } }
+    const input = { manager, writes: [{ scope: 'delete' as const }], evidence: evidence(selfHeal) }
+    expect(guard(input).perWrite[0].reason).toContain("couldn't follow")
+    expect(guard({ ...input, operatorOwner: { kind: 'Cluster', name: 'pg' } }).level).toBe('info')
+  })
+})

package/src/utils/gitops-write-guard.ts

@@ -9,7 +9,10 @@
 // field missing from both can still be in the source. So absence of evidence
 // is "unknown" (may be overwritten), never "safe".
 
-import type { GitOpsOwnerRef, GitOpsOwnerTool } from './gitops-owner'
+import { activeManagerClaims, gitOpsOwnerFromRef, managerCandidates, managerRefLabel, type GitOpsOwnerRef, type GitOpsOwnerTool } from './gitops-owner'
+import type { ManagerAnswer, ResourceRef } from '../types/core'
+import { dedupeResourceRefs } from './resource-refs'
+import { gapReasonText, readActionFor } from './read-actions'
 
 export type GitOpsWriteScope = 'status' | 'metadata' | 'spec' | 'create-child' | 'delete'
 
@@ -100,6 +103,9 @@ export interface GitOpsWritePolicyEvidence {
 }
 
 export interface GitOpsWriteEvidence {
+  manager?: ManagerAnswer
+  /** Why the server couldn't answer what manages the live object; the owner hint wasn't used either. */
+  managerUnavailable?: string
   uid: string
   resourceVersion: string
   owner: { kind: string; group?: string; namespace: string; name: string } | null
@@ -114,6 +120,7 @@ export interface GitOpsWriteEvidence {
 // ---------------------------------------------------------------------------
 
 export interface GitOpsWriteGuardInput {
+  manager?: ManagerAnswer
   target: GitOpsWriteTarget
   owner: GitOpsOwnerRef | null
   /** Native Helm release that manages the object when no GitOps tool does. */
@@ -141,6 +148,7 @@ export interface GitOpsWriteAssessment {
 }
 
 export interface GitOpsWriteGuard {
+  manager?: ManagerAnswer
   owner: GitOpsOwnerRef | null
   helmRelease: GitOpsWriteHelmRelease | null
   pending: boolean
@@ -413,10 +421,68 @@ function classifyWrite(input: GitOpsWriteGuardInput, owner: GitOpsOwnerRef | nul
   if (write.scope === 'status') {
     return { level: 'none', reason: 'This writes controller status; ordinary GitOps sync does not manage these fields.' }
   }
+  const manager = input.manager
+  if (manager) {
+    const candidates = managerCandidates(manager)
+    // A Helm release's annotations on an object answered through an ancestor
+    // are its Deployment's, copied onto it.
+    const directClaims = activeManagerClaims(manager.direct).filter(c => !manager.via || c.source !== 'helm-release')
+    const names = dedupeResourceRefs([...candidates, ...(manager.via ? directClaims.map(c => c.manager) : [])]).map(managerRefLabel).join(' and ')
+    if (write.scope === 'create-child' && candidates.length) {
+      return { level: 'info', reason: `A new object isn't in the GitOps source, so ${names} is not expected to revert it.` }
+    }
+    if (write.scope === 'metadata' || write.scope === 'spec') {
+      if (write.paths?.length && write.paths.every(path => input.evidence?.paths.find(p => p.path === path)?.empty)) {
+        return { level: 'none', reason: '' }
+      }
+      if (chainUnread(manager)) {
+        return { level: 'may-revert', reason: input.ownershipError! }
+      }
+    }
+    // A walk that couldn't read its chain may have missed a manager above;
+    // a controller that recreates the object makes that moot.
+    if (write.scope === 'delete' && chainUnread(manager) && !operatorOwnerOf(input)) {
+      return { level: 'may-revert', reason: input.ownershipError! }
+    }
+    if (manager.via && !directClaims.length) {
+      const source = managerRefLabel(manager.via.object)
+      const parent = `${source}, ${parentManagedBy(manager, names)}`
+      return {
+        level: 'info',
+        reason: write.scope === 'delete'
+          ? !NON_RECREATING_CONTROLLERS.includes(operatorOwnerOf(input)?.kind ?? '')
+            ? `Its controller recreates it from ${parent}.`
+            : `It was created from ${parent}; nothing is expected to recreate it, but ${operatorOwnerOf(input)!.kind} ${input.target.namespace ? `${input.target.namespace}/` : ''}${operatorOwnerOf(input)!.name} can still create new ones on its schedule.`
+          : `This resource is generated from ${parent}; changes to the parent may replace it.`,
+      }
+    }
+    if ((write.scope === 'metadata' || write.scope === 'spec') &&
+        (manager.state === 'disagree' || manager.state === 'shared' || candidates.length > 1 || manager.via && directClaims.length > 0)) {
+      return { level: 'may-revert', reason: `${names} may overwrite these fields. A single manager's ignore rules or sync policy cannot exempt this change.${manager.via ? ` The controller also generates it from ${managerRefLabel(manager.via.object)}.` : ''}` }
+    }
+    if (unconfirmed(manager, owner, input, candidates) && !targetOptedOut(input) && (write.scope === 'metadata' || write.scope === 'spec')) {
+      return { level: 'may-revert', reason: `This resource's metadata names ${names}, but its recorded membership isn't confirmed. A sync may overwrite this change.` }
+    }
+  }
   if (write.scope === 'delete') {
     const operator = operatorOwnerOf(input)
     if (operator) {
-      return { level: 'info', reason: `${operator.kind} ${operator.name} will recreate this ${input.target.kind}.` }
+      return {
+        level: 'info',
+        reason: !NON_RECREATING_CONTROLLERS.includes(operator.kind)
+          ? `${operator.kind} ${operator.name} will recreate this ${input.target.kind}.`
+          : `${operator.kind} ${operator.name} created this ${input.target.kind}; it is not expected to recreate it.`,
+      }
+    }
+  }
+  if (manager && write.scope === 'delete') {
+    const candidates = managerCandidates(manager)
+    if (chainUnread(manager)) return { level: 'may-revert', reason: input.ownershipError! }
+    if (unconfirmed(manager, owner, input, candidates) && !targetOptedOut(input)) {
+      return { level: 'may-revert', reason: `This resource's metadata names ${candidates.map(managerRefLabel).join(' and ')}, but its recorded membership isn't confirmed. A sync may recreate it.` }
+    }
+    if (manager.state === 'disagree' || manager.state === 'shared' || candidates.length > 1) {
+      return { level: 'may-revert', reason: `${candidates.map(managerRefLabel).join(' and ')} may recreate this resource on sync.` }
     }
   }
   if (owner) {
@@ -458,7 +524,8 @@ function classifyWrite(input: GitOpsWriteGuardInput, owner: GitOpsOwnerRef | nul
   return { level: 'none', reason: '' }
 }
 
-function headline(guard: Pick<GitOpsWriteGuard, 'owner' | 'helmRelease'>, level: GitOpsWriteLevel): string {
+function headline(guard: Pick<GitOpsWriteGuard, 'owner' | 'helmRelease' | 'manager'>, level: GitOpsWriteLevel): string {
+  if (guard.manager?.via && level === 'info') return `Generated from ${managerRefLabel(guard.manager.via.object)}.`
   const who = guard.owner
     ? describeGitOpsOwner(guard.owner)
     : guard.helmRelease
@@ -466,7 +533,8 @@ function headline(guard: Pick<GitOpsWriteGuard, 'owner' | 'helmRelease'>, level:
       : 'A GitOps tool'
   if (level === 'will-revert') return `${who} will revert this change.`
   if (level === 'may-revert') return `${who} may revert this change.`
-  if (level === 'info') return guard.owner || guard.helmRelease ? `Managed by ${who}.` : ''
+  // A list alone isn't management: say what the chip says.
+  if (level === 'info') return guard.owner || guard.helmRelease ? `${guard.manager?.state === 'listed' ? 'Listed by' : 'Managed by'} ${who}.` : ''
   return ''
 }
 
@@ -474,15 +542,110 @@ export function gitOpsWriteHeadline(guard: GitOpsWriteGuard): string {
   return headline(guard, guard.level)
 }
 
+// unconfirmed reports whether the answer names candidates without confirming
+// one Radar can act on: a claim, or a candidate this UI can't open (no lead,
+// or a manager kind it doesn't know). A native Helm lead has its own rules.
+function unconfirmed(manager: ManagerAnswer, owner: GitOpsOwnerRef | null, input: GitOpsWriteGuardInput, candidates: ResourceRef[]): boolean {
+  if (!candidates.length || !owner && input.helmRelease) return false
+  return manager.state === 'claimed' || !owner && manager.state !== 'none' && manager.state !== 'unknown'
+}
+
+// parentManagedBy says what the evidence says of a parent, in the words its
+// state allows: only a list and metadata agreeing say a manager manages it.
+function parentManagedBy(manager: ManagerAnswer, names: string): string {
+  const evidence = manager.via ?? manager.direct
+  const label = (refs: ResourceRef[]) => dedupeResourceRefs(refs).map(managerRefLabel).join(' and ')
+  const listing = (refs: ResourceRef[]) => `${label(refs)} ${refs.length > 1 ? 'list it in their statuses' : 'lists it in its status'}`
+  switch (manager.state) {
+    case 'disagree':
+      return `whose metadata names ${label(activeManagerClaims(evidence).map(c => c.manager))}, while ${listing(evidence.recorders ?? [])}`
+    case 'agree':
+      return `which ${names} manages`
+    case 'listed':
+    case 'shared':
+      return `which ${names} ${managerCandidates(manager).length > 1 ? 'list' : 'lists'} in ${managerCandidates(manager).length > 1 ? 'their statuses' : 'its status'}`
+    default:
+      return `whose metadata names ${names}`
+  }
+}
+
+// adoptedHelmRelease: a native Helm release's annotations on an object a GitOps
+// manager other than Flux's HelmRelease answers for. Argo CD renders charts
+// with helm template, and a Kustomization applies plain manifests, so the
+// annotations mean a Helm install was adopted: its release can still upgrade
+// or roll back the object, whatever the GitOps manager ignores.
+function adoptedHelmRelease(manager: ManagerAnswer | undefined): string | null {
+  if (!manager?.lead || manager.via) return null
+  if (manager.lead.kind === 'HelmRelease') return null
+  const claim = (manager.direct.claims ?? []).find(c => c.source === 'helm-release' && !c.copied && !c.weak)
+  return claim ? `${claim.manager.namespace ? `${claim.manager.namespace}/` : ''}${claim.manager.name}` : null
+}
+
+// targetOptedOut: the target's own annotations opt it out of its manager's
+// reconciliation, which holds whether or not that manager's list names it.
+function targetOptedOut(input: GitOpsWriteGuardInput): boolean {
+  return input.evidence?.policy?.objectReconcile === 'ignore'
+}
+
+// chainUnread: the walk up the controller chain stopped at an owner Radar
+// couldn't read or decide, so a manager above it may be missed. An owner that is
+// gone or was replaced ends the chain with an answer.
+function chainUnread(manager: ManagerAnswer): boolean {
+  // A chain end this UI doesn't know (from a newer Radar) stopped short too.
+  if (manager.chainEnd && manager.chainEnd !== 'unfollowed') return true
+  return Boolean(manager.stop && !['gone', 'replaced', 'excluded'].includes(manager.stop.state))
+}
+
+// The states this UI knows. A newer Radar may send another; it is read as
+// claimed, which never proves a revert or waives a warning.
+const MANAGER_STATES: Array<string> = ['shared', 'disagree', 'agree', 'listed', 'claimed', 'unknown', 'none']
+
+// Controllers that don't replace an object of theirs that is deleted: a
+// CronJob's Job (scheduled or created by hand) runs once.
+const NON_RECREATING_CONTROLLERS = ['CronJob']
+
 export function evaluateGitOpsWriteGuard(input: GitOpsWriteGuardInput): GitOpsWriteGuard {
-  const owner = input.owner ?? null
-  const helmRelease = owner ? null : (input.helmRelease ?? null)
-  const ownershipError = owner || helmRelease ? null : (input.ownershipError ?? null)
-  const normalized: GitOpsWriteGuardInput = { ...input, owner, helmRelease, ownershipError }
+  // A live check the server couldn't answer, or one that failed while the
+  // cached answer names a manager, leaves that answer unconfirmed: an exemption
+  // read from it could belong to the object as it was.
+  const cachedNamesManager = Boolean(input.manager && (input.manager.via || !['none', 'unknown'].includes(input.manager.state)))
+  const unavailable = input.evidence?.managerUnavailable
+  const failed = !input.evidence && input.evidenceError && cachedNamesManager ? input.evidenceError : null
+  const unconfirmed = unavailable || failed
+  const answered = unconfirmed ? undefined : input.evidence?.manager ?? input.manager
+  const manager = answered && !MANAGER_STATES.includes(answered.state) ? { ...answered, state: 'claimed' as const } : answered
+  const owner = unconfirmed ? null : manager ? manager.lead ? gitOpsOwnerFromRef(manager.lead) : null : input.owner ?? null
+  const helmRelease = unconfirmed ? null : manager
+    ? manager.lead?.kind === 'HelmRelease' && !manager.lead.group ? { namespace: manager.lead.namespace, name: manager.lead.name } : null
+    : owner ? null : (input.helmRelease ?? null)
+  const ownershipError = unconfirmed
+    ? `Radar couldn't check what manages this resource right now (${unavailable ? gapReasonText(unavailable) : failed}), so it can't tell whether a GitOps tool or Helm reverts this change.${unavailable && ['retry', 'wait'].includes(readActionFor(unavailable) ?? '') ? ' Close and reopen this dialog to check again.' : ''}`
+    : manager && chainUnread(manager)
+      ? "Radar couldn't follow this resource's controller chain, so it can't tell whether a GitOps tool or Helm manages it."
+      : owner || helmRelease ? null : (input.ownershipError ?? null)
+  const normalized: GitOpsWriteGuardInput = { ...input, manager, owner, helmRelease, ownershipError, ownerMatchedByName: manager ? false : input.ownerMatchedByName }
+  const adopted = adoptedHelmRelease(manager)
 
   const perWrite = input.writes.map((write) => {
     const verdict = classifyWrite(normalized, owner, write)
-    if (owner && input.ownerMatchedByName && verdict.level === 'info' && write.scope !== 'create-child') {
+    // A list alone doesn't show its manager syncs the object (a copy carrying
+    // another object's tracking ID, a CRD a HelmRelease skips): no promise,
+    // in the verdict or in its reason.
+    if (manager?.state === 'listed' && !manager.via && (verdict.level === 'will-revert' || verdict.level === 'may-revert')) {
+      return {
+        write,
+        level: 'may-revert' as const,
+        reason: `Radar can't confirm ${managerRefLabel(manager.lead!)} applies this object: its status lists it, but the object's metadata doesn't name it. If it does: ${verdict.reason}`,
+      }
+    }
+    if (adopted && verdict.level === 'info' && (write.scope === 'metadata' || write.scope === 'spec' || write.scope === 'delete')) {
+      return {
+        write,
+        level: 'may-revert' as const,
+        reason: `${verdict.reason} Its metadata also says Helm release ${adopted} installed it; the next helm upgrade or rollback of that release may ${write.scope === 'delete' ? 'recreate it' : 'overwrite this change'}.`,
+      }
+    }
+    if (owner && normalized.ownerMatchedByName && verdict.level === 'info' && write.scope !== 'create-child') {
       return {
         write,
         level: 'may-revert' as const,
@@ -493,16 +656,17 @@ export function evaluateGitOpsWriteGuard(input: GitOpsWriteGuardInput): GitOpsWr
   })
   const level = perWrite.reduce<GitOpsWriteLevel>((max, entry) => maxLevel(max, entry.level), 'none')
   const top = perWrite.find((entry) => entry.level === level)
-  const summary = level === 'none' ? '' : [headline({ owner, helmRelease }, level), top?.reason ?? ''].filter(Boolean).join(' ')
+  const summary = level === 'none' ? '' : [headline({ owner, helmRelease, manager }, level), top?.reason ?? ''].filter(Boolean).join(' ')
 
   return {
+    ...(manager ? { manager } : {}),
     owner,
     helmRelease,
     pending: Boolean(input.ownerPending),
     level,
     perWrite,
     summary,
-    syncPolicy: owner ? gitOpsSyncPolicy(input.evidence?.policy) : null,
+    syncPolicy: owner && (!manager || manager.state !== 'claimed' && managerCandidates(manager).length === 1) ? gitOpsSyncPolicy(input.evidence?.policy) : null,
     requiresAck: level === 'will-revert' || level === 'may-revert',
     ownershipError,
   }

package/src/utils/index.ts

@@ -11,6 +11,7 @@ export * from './log-export'
 export * from './log-format'
 export * from './download'
 export * from './clipboard'
+export * from './touch-intent'
 export * from './env-from'
 export * from './extended-resources'
 export * from './api-resources'
@@ -35,5 +36,7 @@ export * from './network-policy'
 export * from './cnpg-backup'
 export * from './url-path'
 export * from './resource-refs'
+export * from './resource-coverage'
+export * from './read-actions'
 
 export * from './grant'

package/src/utils/read-actions.test.ts

@@ -0,0 +1,22 @@
+import { readFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import { canonicalReadCode, READ_ACTIONS, readActionFor } from './read-actions'
+
+const FIXTURE = resolve(dirname(fileURLToPath(import.meta.url)), '../../../../pkg/readreason/testdata/actions.json')
+
+describe('read actions', () => {
+  it('mirror the server table exactly', () => {
+    expect(READ_ACTIONS).toEqual(JSON.parse(readFileSync(FIXTURE, 'utf8')))
+  })
+  it('maps an incomplete findings scan to changing the request', () => {
+    expect(READ_ACTIONS.findings_scan_incomplete).toBe('change_request')
+  })
+  it('read the spellings older Radars sent as the codes they became', () => {
+    expect(canonicalReadCode('kind_sync_failed')).toBe('kind_sync_timed_out')
+    expect(canonicalReadCode('rbac_denied')).toBe('user_forbidden')
+    expect(readActionFor('kind_sync_failed')).toBe('wait')
+    expect(readActionFor('rbac_denied')).toBe('user_access')
+  })
+})