feat: version the Estimation v2 performance contract

VERSION

@@ -1 +1 @@
-0.1.0
+0.2.0

models/process-resource-sample.v2.schema.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://semcod.dev/schemas/estimation/process-resource-sample.v2.json",
+  "title": "Process resource sample v2",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema", "sample_id", "process_uri", "process_key", "ticket_id",
+    "correlation_id", "started_at", "finished_at", "duration_seconds",
+    "cpu_user_seconds", "cpu_system_seconds", "effective_cpu_cores",
+    "peak_rss_bytes", "read_bytes", "write_bytes", "max_processes",
+    "sample_count", "exit_code", "outcome", "program", "argv_sha256",
+    "host_profile", "raw_output_included", "secret_material_included",
+    "energy", "kernel"
+  ],
+  "properties": {
+    "schema": {"const": "semcod.estimation.sample/v2"},
+    "sample_id": {"type": "string", "pattern": "^sample:[a-f0-9]{32}$"},
+    "process_uri": {"type": "string", "minLength": 3, "maxLength": 512},
+    "process_key": {"type": "string", "minLength": 3, "maxLength": 320},
+    "ticket_id": {"type": ["string", "null"], "maxLength": 128},
+    "correlation_id": {"type": "string", "minLength": 1, "maxLength": 128},
+    "started_at": {"type": "string", "format": "date-time"},
+    "finished_at": {"type": "string", "format": "date-time"},
+    "duration_seconds": {"type": "number", "minimum": 0},
+    "cpu_user_seconds": {"type": "number", "minimum": 0},
+    "cpu_system_seconds": {"type": "number", "minimum": 0},
+    "effective_cpu_cores": {"type": "number", "minimum": 0},
+    "peak_rss_bytes": {"type": "integer", "minimum": 0},
+    "read_bytes": {"type": "integer", "minimum": 0},
+    "write_bytes": {"type": "integer", "minimum": 0},
+    "max_processes": {"type": "integer", "minimum": 0},
+    "sample_count": {"type": "integer", "minimum": 1},
+    "exit_code": {"type": ["integer", "null"]},
+    "outcome": {"enum": ["succeeded", "failed", "interrupted", "observed"]},
+    "program": {"type": "string", "minLength": 1, "maxLength": 128},
+    "argv_sha256": {"type": "string", "pattern": "^[a-f0-9]{64}$"},
+    "host_profile": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["host_id", "system", "machine", "cpu_count", "memory_bytes"],
+      "properties": {
+        "host_id": {"type": "string", "pattern": "^host:[a-f0-9]{16}$"},
+        "system": {"type": "string", "maxLength": 32},
+        "machine": {"type": "string", "maxLength": 32},
+        "cpu_count": {"type": "integer", "minimum": 1},
+        "memory_bytes": {"type": "integer", "minimum": 1}
+      }
+    },
+    "raw_output_included": {"const": false},
+    "secret_material_included": {"const": false},
+    "energy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["joules", "method", "confidence", "domains"],
+      "properties": {
+        "joules": {"type": ["number", "null"], "minimum": 0},
+        "method": {"enum": ["unavailable", "rapl_cpu_share"]},
+        "confidence": {"enum": ["none", "low", "medium", "high"]},
+        "domains": {"type": "integer", "minimum": 0}
+      }
+    },
+    "kernel": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "cgroup_id", "attribution", "cpu_seconds", "memory_peak_bytes",
+        "read_bytes", "write_bytes", "pids_peak", "pressure"
+      ],
+      "properties": {
+        "cgroup_id": {"type": ["string", "null"], "pattern": "^cgroup:[a-f0-9]{16}$"},
+        "attribution": {"enum": ["unavailable", "shared", "dedicated"]},
+        "cpu_seconds": {"type": ["number", "null"], "minimum": 0},
+        "memory_peak_bytes": {"type": ["integer", "null"], "minimum": 0},
+        "read_bytes": {"type": ["integer", "number", "null"], "minimum": 0},
+        "write_bytes": {"type": ["integer", "number", "null"], "minimum": 0},
+        "pids_peak": {"type": ["integer", "null"], "minimum": 0},
+        "pressure": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["cpu_some_seconds", "io_some_seconds", "memory_some_seconds"],
+          "properties": {
+            "cpu_some_seconds": {"type": ["number", "null"], "minimum": 0},
+            "io_some_seconds": {"type": ["number", "null"], "minimum": 0},
+            "memory_some_seconds": {"type": ["number", "null"], "minimum": 0}
+          }
+        }
+      }
+    }
+  }
+}

operations/index.json

@@ -1,6 +1,6 @@
 {
   "schema": "semcod.estimation.operations/v1",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "operations": [
     {
       "id": "measure",
@@ -29,6 +29,13 @@
       "kind": "query",
       "risk": "R0",
       "effect": "Predict a bounded resource envelope for a quantity and parallelism."
+    },
+    {
+      "id": "opportunities",
+      "processUri": "estimation://history/query/opportunities",
+      "kind": "query",
+      "risk": "R0",
+      "effect": "Rank recurring URI Processes by one explicit resource objective without applying changes."
     }
   ]
 }

project/ticket-010/README.md

@@ -0,0 +1,35 @@
+# Ticket 010: Measure energy and rank URI Process optimization opportunities
+
+- **ID**: ticket-010
+- **Owner**: unresolved:human
+- **Status**: IN_PROGRESS
+- **Workflow state**: VALIDATION
+- **Created**: 2026-08-30
+
+## Goal and scope
+
+Version the package contract for optional, bounded Linux energy, cgroup v2 and
+pressure evidence. Declare a read-only opportunity Process URI while keeping
+the runtime implementation in the dependent application workstream.
+
+## Acceptance criteria
+
+- [x] AC-01: Scope is approved by the user's request to monitor local cost,
+  energy and execution time and optimize the highest-cost URI Processes first.
+- [x] AC-02: The closed v2 schema defines optional energy/cgroup/PSI evidence
+  with explicit method, confidence and attribution.
+- [x] AC-03: The operation catalog declares the bounded, read-only opportunity
+  query with no authority to apply changes.
+- [x] AC-04: Package metadata is versioned to 0.2.0.
+- [x] AC-05: JSON validation and governance pass.
+
+## Closure evidence
+
+- Both JSON contracts parse successfully with Python's strict JSON parser.
+- Repository governance reports `GOV-PASS` with no errors or warnings.
+
+## Participants
+
+- Human participant: user:tom; authorization is recorded by the originating
+  request and no synthesized user file was created.
+- Agent participant: [ai-codex.md](ai-codex.md)

project/ticket-010/ai-codex.md

@@ -0,0 +1,41 @@
+---
+participant-id: agent:codex
+participant: codex
+role: agent
+ticket: ticket-010
+---
+# Participant: codex (AI agent)
+
+## Understanding
+
+Subactor needs an empirical optimization loop, not a second generic performance
+repository. `semcod/estimation` already owns URI Process resource evidence, so
+it should add honest energy and kernel-pressure observations plus objective-
+specific ranking. Runtime remains the execution owner and Wellmanifest remains
+the standard owner.
+
+## Execution plan
+
+1. Version the sample contract while retaining v1 reads.
+2. Observe optional RAPL, cgroup v2 and PSI counters without controlling work.
+3. Rank recurring Process URIs by an explicit savings objective and confidence.
+4. Add CLI/catalog exposure, tests and governance evidence.
+
+## Actual changes
+
+- Initialized the bounded ticket and recorded SESSION_EXECUTION_AUTHORIZATION
+  from the request to execute this work.
+- Added a closed v2 sample schema for optional energy and kernel observations.
+- Declared the read-only opportunity query and advanced package metadata to
+  version 0.2.0.
+- Split runtime implementation into dependent application ticket-011 after the
+  ownership gate correctly rejected mixed workstreams.
+- Passed JSON parsing and repository governance with no findings.
+
+## Blockers
+
+- None inside the recorded intent; proceed without a second confirmation.
+- New authority remains required for destructive action, secret access, new
+  external coordination or material objective expansion. Protected delivery
+  may be invoked without another prompt when publication is in scope; its
+  exact-head trusted approval remains independent evidence.

project/ticket-010/changelog.md

@@ -0,0 +1,6 @@
+# Ticket Changelog (ticket-010)
+
+## [0.1.0] - 2026-08-30
+
+- Initial governance scaffold created.
+- No human participant identity or content was generated.

project/ticket-010/intent.json

@@ -0,0 +1,69 @@
+{
+  "schema": "new-project.intent/v3",
+  "ticket": "ticket-010",
+  "summary": "Measure energy and rank URI Process optimization opportunities",
+  "workstream": "integration",
+  "classification": {
+    "kind": "FEATURE",
+    "priority": "P1",
+    "origin": "requested"
+  },
+  "placement": {
+    "home": "semcod",
+    "runtimeOwner": "semcod",
+    "shape": "runtime_service",
+    "adopt": ["wellmanifest/new-project", "wellmanifest/logs", "wellmanifest/performance"]
+  },
+  "allowedPaths": [
+    "project/ticket-010/**",
+    "TODO.md",
+    "project/TICKETS.md",
+    "VERSION",
+    "pyproject.toml",
+    "models/**",
+    "operations/**"
+  ],
+  "forbiddenPaths": ["project/ticket-*/user-*.md"],
+  "stacks": [],
+  "dependsOn": [],
+  "conflictsWith": [],
+  "integrationTicket": null,
+  "delivery": {
+    "acceptedBaseSha": "b70aa563d0c58e5a264938b001db83605f1f58d0",
+    "targetBranch": "main",
+    "outcome": "Versioned URI Process samples include bounded Linux energy and pressure observations, and a read-only query ranks recurring optimization opportunities by an explicit resource objective.",
+    "nonGoals": [
+      "Create or mutate cgroups, scheduling policy or process authorization.",
+      "Claim process-exclusive energy attribution from shared package counters.",
+      "Capture command arguments, output, environment values, cgroup paths or secrets.",
+      "Automatically apply an optimization from a single sample."
+    ],
+    "complexity": "L",
+    "estimatedMinutes": 30,
+    "budgets": {
+      "maxImplementationFiles": 15,
+      "maxAffectedComponents": 4,
+      "maxPublicInterfaceChanges": 3,
+      "maxRuntimeDependencies": 0
+    },
+    "architecture": {
+      "status": "accepted",
+      "decision": "Keep measurement append-only and advisory: observe existing Linux counters without privilege, retain v1 reads, label attribution confidence, and rank savings independently for CPU, wall time, energy or I/O.",
+      "components": [
+        {"name": "package-metadata", "paths": ["VERSION", "pyproject.toml"]},
+        {"name": "sample-contract", "paths": ["models/**"]},
+        {"name": "operation-catalog", "paths": ["operations/**"]}
+      ],
+      "responsibilityChanges": false,
+      "interfaceChanges": ["Add the v2 sample schema.", "Declare the opportunities Process URI."],
+      "dataChanges": ["Append v2 sample records; existing v1 JSONL remains readable."],
+      "ui": {"impact": "none", "states": [], "evidence": []},
+      "rollback": "Stop emitting v2 samples and remove the opportunities query; append-only v1 and v2 records remain auditable."
+    },
+    "runtimeDependencies": [],
+    "validation": [
+      {"criterion": "AC-04", "commands": ["python -m json.tool models/process-resource-sample.v2.schema.json", "python -m json.tool operations/index.json"], "evidence": "versioned closed schema and operation catalog"},
+      {"criterion": "AC-05", "commands": ["PYTHONPATH=src ./project/governance-check.sh"], "evidence": "repository governance passes"}
+    ]
+  }
+}

project/ticket-010/preprompt.md

@@ -0,0 +1,15 @@
+# Ticket preprompt
+
+- **Task ID**: ticket-010
+- **Task title**: Measure energy and rank URI Process optimization opportunities
+- **Created**: 2026-08-30T10:34:06Z
+
+Keep executable implementation outside this governance/evidence directory.
+Read a human-owned user-*.md file only when one exists.
+The request to execute this work creates SESSION_EXECUTION_AUTHORIZATION;
+proceed within the recorded intent without a redundant confirmation prompt.
+Require new authority for destructive action, secrets, external coordination,
+or material objective expansion. When publication is in scope, session
+authorization permits the declared protected delivery process and its merge
+after exact-head trusted approval without another prompt. Session prose is
+never approval evidence and the agent must not merge directly.

pyproject.toml

@@ -4,8 +4,8 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "estimation"
-version = "0.1.0"
-description = "Historical CPU, memory, I/O and duration estimates for ticket-bound URI processes"
+version = "0.2.0"
+description = "Historical CPU, memory, I/O, energy and duration estimates for ticket-bound URI processes"
 readme = "README.md"
 license = "Apache-2.0"
 requires-python = ">=3.10"