Define the LibreSign AI capability and policy contract #9054

Goal

Document and decide the LibreSign AI capability and policy contract that future implementation must follow.

This is an architecture and planning task. It does not implement Task Processing integration, Policy Workbench changes, AI UI, providers, or runtime behavior.

The purpose is to turn the current roadmap into an explicit maintainer-approved contract so later implementation issues can be executed without inventing architecture inside pull requests.

Inputs

Before resolving this issue, review:

• the current Policy Workbench architecture and delegation model;
• the current signer/public-signer authorization model;
• the public Nextcloud Task Processing API available in the supported Nextcloud versions;
• the deterministic testing requirements defined by the foundation epic;
• the relevant documentation/research produced by focused child issues.

Use existing code, tests and public Nextcloud contracts as evidence.

Do not infer behavior from roadmap text when the current implementation or public API can answer the question.

Version compatibility rule

Verify every selected Nextcloud OCP API against the full set of Nextcloud versions supported by the target LibreSign release.

Record @since information for APIs that materially affect the contract. Do not silently make a newer Nextcloud API a universal requirement if LibreSign still supports older versions.

For example, current Nextcloud sources expose IManager::getAvailableTaskTypeIds() with @since 32.0.0, while other Task Processing capabilities such as intermediate output and newer Context Chat extensions arrive in later releases.

Questions this contract must answer

Capability

Document:

• which public Nextcloud Task Processing APIs LibreSign will rely on;
• how raw Nextcloud task types map to semantic LibreSign capabilities;
• how capabilities are resolved for the current actor/context;
• how unavailable, disabled or failing capabilities are represented;
• which task-lifecycle states LibreSign must understand;
• which provider details are intentionally hidden from LibreSign.

Policy

Document:

• which AI capabilities require separate LibreSign policy decisions;
• how system, group and user scopes apply through the existing Policy Workbench model;
• which values can be delegated/customized at lower scopes;
• how the backend resolves and enforces the effective policy;
• how public/external signer contexts are represented;
• what happens when technical capability exists but policy denies use.

Do not create a second AI-specific permission system.

Security boundary

The contract must state explicitly that:

• Task Processing capability does not grant LibreSign authorization;
• frontend visibility is not authorization;
• prompts do not enforce business rules;
• document input and AI output are untrusted;
• model output never expands the actor's effective permissions;
• AI-suggested state changes must pass normal LibreSign services and validation;
• provider credentials and model configuration remain owned by Nextcloud.

Provider metadata

Record only provider/trust/privacy metadata actually exposed through supported public Nextcloud APIs.

Do not invent:

• Ethical AI ratings;
• local/remote heuristics based on provider names;
• trust tables maintained by LibreSign;
• privacy claims that Nextcloud does not expose authoritatively.

Anything unavailable remains explicitly deferred.

Required architecture artifact

The final issue outcome must leave an explicit, reviewable contract covering:

1. semantic LibreSign AI capability identifiers;
2. mapping to supported Nextcloud task types;
3. backend service boundaries;
4. Policy Workbench policy keys/relationships;
5. actor/context rules;
6. task ownership and lifecycle;
7. unavailable/error semantics;
8. data-minimization expectations;
9. testing seams for deterministic providers;
10. deferred metadata/questions.

The artifact may live in maintained developer documentation or another repository-owned architecture document, but it must be durable and reviewable. Do not leave the contract only in PR discussion.

Documentation requirements

Write the architecture as current/future product contract, not as a diary of how the decision was reached.

Use:

• declarative language;
• diagrams/tables where they reduce ambiguity;
• cross-references to existing Policy Workbench and signer-authorization documentation;
• exact Nextcloud public API names only after they are verified.

Do not document planned behavior as already implemented.

Inputs from newcomer-friendly documentation tasks

Focused documentation issues may document the current LibreSign architecture that this synthesis depends on.

Those tasks must not decide the future AI contract.

In particular, LibreSign/documentation#112 documents the current Policy Workbench architecture and is factual input to this issue. That documentation task must not decide the future AI contract.

Out of scope

Do not:

• add production code;
• add Task Processing providers;
• create AI policies in code;
• create frontend controls;
• create test doubles;
• change signer authorization behavior;
• implement downstream AI features.

If resolving this issue exposes a required product decision that cannot be supported by current evidence, document it as an open maintainer decision instead of guessing.

Done when

• The capability-to-feature mapping is explicit and provider-neutral.
• The Policy Workbench contract for AI is explicit.
• Actor/context behavior, including public/external signing, is explicit.
• Security ownership between Nextcloud, LibreSign backend and frontend is explicit.
• Unknown provider metadata remains explicitly deferred rather than inferred.
• The contract is stored in a durable project-owned form.
• Later implementation issues can follow the contract without making new architecture decisions.