KLIS-1: Intent Manifest Specification

1. Purpose

The Intent Manifest Specification defines the standard format and semantics for agents to declare their potential effects on a shared environment before execution. By reifying intent into a symbolic data structure (the Klock Intent Manifest or NIM), systems can perform O(1) determinism checks, collision detection, and security policy enforcement without requiring semantic understanding of the agent's code or prompts.

This specification adheres to the "Ask Forgiveness, But Declare Permission" principle: agents may attempt any action, but they MUST hold a valid lease granted via a declared intent for that action to succeed.

2. Core Concepts

2.1. The SPO Triple

The atomic unit of intent is the SPO Triple (Subject-Predicate-Object), representing a single directed claim over a resource.

<Subject> <Predicate> <Object>

• Subject: The unique identifier of the agent instance (e.g., agent_123).
• Predicate: The specific nature of the intent (see Section 3).
• Object: The unique identifier of the target resource (see Section 4).

2.2. The Intent Manifest (Scope)

A collection of SPO Triples that represents the entirety of an agent's intended operations for a discrete unit of work (a "Turn" or "Session").

3. Intent Predicates

Agents MUST classify their operations into one of the following five predicates. These predicates are normative and exhaustive for the core specification.

| Predicate | Semantics | Example | | :--- | :--- | :--- | | PROVIDES | The agent intends to bring a new resource into existence. | Creating a new file, spawning a process. | | CONSUMES | The agent intends to read or inspect a resource without modifying it. | Reading a file, getting a URL, listing a directory. | | MUTATES | The agent intends to modify the state of an existing resource in place. | Appending to a log, editing code, updating a DB record. | | DELETES | The agent intends to remove a resource permanently or irrevocably. Requires an exclusive lock that blocks even CONSUMES (Readers). | rm file, DROP TABLE. | | DEPENDS_ON | The agent asserts that a resource must exist and remain invariant, but will not read its content directly. | Checking existence, asserting lock files. |

Normative Rules:

• A resource created via PROVIDES MAY be implicitly MUTATES-able by the same agent within the same scope.
• MUTATES implies CONSUMES (read-before-write is assumed).
• DELETES is terminal; no further predicates are valid on the resource in the same scope.

4. Resource Identity

Resources MUST be identified by a deterministic, uniform Resource Identifier (URI).

4.1. Standard Format

<Scheme>:<Authority>/<Path>

• Scheme: Case-insensitive resource type (e.g., FILE, URL, PROCESS, DB).
• Authority (Optional): The namespace or host (e.g., localhost, s3://bucket).
• Path: The canonicalized, absolute path to the resource.

4.2. Path Canonicalization

To ensure O(1) equality checks:

1. Normalization: Paths MUST be normalized (e.g., resolving .., removing redundant slashes).
2. Absolutism: Paths MUST be absolute. Relative paths are invalid in a manifest.
3. Case Sensitivity: Defined by the foundational OS or system. For cross-platform specs, assume Case-Sensitive (strict) or Canonicalize-to-Lower (loose). Recommendation: Strict.

Examples:

• FILE:/boot/config.txt
• URL:https://example.com/api/v1
• ENV:PRODUCTION/DB_PASSWORD

5. Scope Declaration Format

An Intent Manifest (NIM) MUST be a serializable structure (JSON/YAML) containing:

1. Session ID: Unique correlation ID for the workflow.
2. Agent ID: Identity of the requestor.
3. Intents: List of SPO Triples.

JSON Schema Excerpt:

{
  "ver": "1.0",
  "session_id": "uuid-v4",
  "agent_id": "agent-007",
  "priority_timestamp": 1735000000000,
  "scope": [
    {
        "predicate": "MUTATES",
        "resource": "FILE:/src/main.ts",
        "confidence": 1.0
    },
    {
        "predicate": "CONSUMES",
        "resource": "FILE:/src/utils.ts",
        "confidence": 1.0
    }
  ]
}

6. Validity & Rejection

A Control Plane MUST reject a manifest if:

1. Malformed Schema: Missing required fields.
2. Invalid Predicate: Use of non-standard predicate.
3. Ambiguous Resource: Relative or non-canonical path.
4. Internal Contradiction: The same manifest contains contradictory intents (e.g., PROVIDES and CONSUMES for the same resource is valid [read-after-write], but DELETES and MUTATES requires strict ordering or should be modeled as DELETES).
   • 6.4. Internal Contradiction Resolution: If a manifest contains CONSUMES and MUTATES for the same resource, the Kernel MUST escalate the requirement to the "Highest Severity" (MUTATES) for the duration of the lease.

7. Security Considerations

• Intent Spoofing: Manifests MUST be cryptographically signed or transmitted over authenticated channels (mTLS).
• Resource Exhaustion: Agents declaring global scope (e.g., MUTATES FILE:/) MUST be rejected by policy.
• Information Leakage: Resource paths in manifests might reveal sensitive file existence. Manifests should be treated as privileged metadata.

8. Non-Goals

• Semantic Validation: KLIS-1 does not check if the agent actually needs the file.
• Execution: KLIS-1 does not execute the intent.
• History: KLIS-1 does not track past intents, only the current proposed scope.