feat(capability-policy): per-capability default-policy source (§7)

[zetyquickly]

Part of #5261 (epic) · continues #4628 · stacked on #5262 (base is
feat/capability-policy).

Second independent slice — still depends only on ironclaw_host_api, no
dependency on #4544.

What this adds

The per-capability default-policy source (architecture doc §7), in the
ironclaw_capability_policy crate:

• CapabilityDefaultPolicySource trait — default_for(capability) -> CapabilityDefaultPolicy.
• StaticCapabilityDefaultPolicySource — in-memory entries over a global
  fallback, seeded from manifest declarations at composition time.
• CapabilityDefaultPolicy::conservative_fallback() — fail-closed default for
  unlisted capabilities (hidden · no credential · ask).

Why a source instead of a descriptor field

CapabilityDescriptor has 49 construction sites, so adding a default_policy
field would be a wide sweep. Sourcing the default by CapabilityId keeps this
slice decoupled and #4544-independent; the manifest remains the source of truth.

Tests

cargo clippy -p ironclaw_capability_policy --all-features --tests -- -D warnings
clean; 11 unit tests pass (3 new: entry-then-fallback lookup, the
conservative fallback shape, and the source default feeding the precedence fold).

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

🗂️ Base branches to auto review (2)

• staging
• reborn-integration

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 3b8a4ea5-d44f-488a-bcc3-ae7c0464bb76

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

_{Comment @coderabbitai help to get the list of available commands.}

[gemini-code-assist]

Code Review

This pull request introduces the CapabilityDefaultPolicySource trait and its in-memory implementation StaticCapabilityDefaultPolicySource to decouple default policy lookups from capability registration, alongside a conservative global fallback policy and unit tests. The reviewer suggests optimizing the default_for method to return a reference (&CapabilityDefaultPolicy) instead of an owned value to avoid unnecessary cloning of heap-allocated fields. This optimization requires corresponding updates to the trait implementation and unit tests.

Important

The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.

[gemini-code-assist]

To avoid unnecessary cloning of CapabilityDefaultPolicy (which contains a heap-allocated serde_json::Value in its config field), consider defining default_for to return a reference &CapabilityDefaultPolicy instead of an owned value. Since the lookup is performed against a read-only source, returning a reference avoids overhead on what may be a frequent capability dispatch path.

Suggested change

	pub trait CapabilityDefaultPolicySource: Send + Sync {
	/// The default policy for `capability`, or the global fallback when the
	/// capability declares none.
	fn default_for(&self, capability: &CapabilityId) -> CapabilityDefaultPolicy;
	}
	pub trait CapabilityDefaultPolicySource: Send + Sync {
	/// The default policy for `capability`, or the global fallback when the
	/// capability declares none.
	fn default_for(&self, capability: &CapabilityId) -> &CapabilityDefaultPolicy;
	}

References

1. Prefer routing through centralized helper functions to maintain drift-resistance and avoid duplicating domain knowledge locally, even if it introduces minor performance overhead (like cloning) on non-hot paths. However, on hot paths (like frequent capability dispatch), avoiding cloning by returning references is preferred.

[gemini-code-assist]

Update the implementation of CapabilityDefaultPolicySource to return a reference, matching the trait signature change and avoiding cloning the policy.

impl CapabilityDefaultPolicySource for StaticCapabilityDefaultPolicySource {
    fn default_for(&self, capability: &CapabilityId) -> &CapabilityDefaultPolicy {
        self.entries
            .get(capability)
            .unwrap_or(&self.fallback)
    }
}

[gemini-code-assist]

Update the test to compare references instead of owned values, matching the updated default_for signature.

Suggested change

	#[test]
	fn default_source_returns_entry_then_fallback() {
	let entry = CapabilityDefaultPolicy {
	availability: Availability::Available,
	identity: IdentityMode::None,
	approval: PermissionMode::Allow,
	config: json!({}),
	};
	let source = StaticCapabilityDefaultPolicySource::new(
	CapabilityDefaultPolicy::conservative_fallback(),
	)
	.with_entry(cap(), entry.clone());
	assert_eq!(source.default_for(&cap()), entry);
	let unknown = CapabilityId::new("shell.exec").expect("valid capability id");
	assert_eq!(
	source.default_for(&unknown),
	CapabilityDefaultPolicy::conservative_fallback()
	);
	}
	#[test]
	fn default_source_returns_entry_then_fallback() {
	let entry = CapabilityDefaultPolicy {
	availability: Availability::Available,
	identity: IdentityMode::None,
	approval: PermissionMode::Allow,
	config: json!({}),
	};
	let source = StaticCapabilityDefaultPolicySource::new(
	CapabilityDefaultPolicy::conservative_fallback(),
	)
	.with_entry(cap(), entry.clone());
	assert_eq!(source.default_for(&cap()), &entry);
	let unknown = CapabilityId::new("shell.exec").expect("valid capability id");
	assert_eq!(
	source.default_for(&unknown),
	&CapabilityDefaultPolicy::conservative_fallback()
	);
	}

References

1. In tests, when setting up a state that depends on environmental factors, prefer expect() to explicitly fail the test with a clear message if the setup is not possible. Avoid fallbacks like unwrap_or() that could cause the test to silently check the wrong logic.

[gemini-code-assist]

Update the test to pass the reference returned by default_for directly to resolve_effective_policy without borrowing it again.

Suggested change

	#[test]
	fn source_default_feeds_the_fold() {
	// An admin per-user grant flips the conservative hidden default to
	// available for one user.
	let source = StaticCapabilityDefaultPolicySource::new(
	CapabilityDefaultPolicy::conservative_fallback(),
	);
	let mut user = delta(PolicyScope::User {
	user_id: uid("bob"),
	});
	user.availability = Some(Availability::Available);
	let eff = resolve_effective_policy(&source.default_for(&cap()), &[user]);
	assert!(eff.available);
	}
	#[test]
	fn source_default_feeds_the_fold() {
	// An admin per-user grant flips the conservative hidden default to
	// available for one user.
	let source = StaticCapabilityDefaultPolicySource::new(
	CapabilityDefaultPolicy::conservative_fallback(),
	);
	let mut user = delta(PolicyScope::User {
	user_id: uid("bob"),
	});
	user.availability = Some(Availability::Available);
	let eff = resolve_effective_policy(source.default_for(&cap()), &[user]);
	assert!(eff.available);
	}

[railway-app]

🚅 Deployed to the ironclaw-pr-5263 environment in ironclaw-ci-preview

Service	Status	Web	Updated (UTC)
ironclaw	✅ Success (View Logs)	Web	Jun 26, 2026 at 5:52 am