From ab700b54cf1ecc41a9ff2a29ab567049e56e1c20 Mon Sep 17 00:00:00 2001 From: Tom Softreck Date: Sun, 30 Aug 2026 13:43:35 +0200 Subject: [PATCH 1/2] plan: define Estimation v2 performance contract [ticket-010] --- project/ticket-010/README.md | 35 ++++++++++++++ project/ticket-010/ai-codex-logs.txt | 0 project/ticket-010/ai-codex.md | 41 +++++++++++++++++ project/ticket-010/changelog.md | 6 +++ project/ticket-010/intent.json | 69 ++++++++++++++++++++++++++++ project/ticket-010/preprompt.md | 15 ++++++ 6 files changed, 166 insertions(+) create mode 100644 project/ticket-010/README.md create mode 100644 project/ticket-010/ai-codex-logs.txt create mode 100644 project/ticket-010/ai-codex.md create mode 100644 project/ticket-010/changelog.md create mode 100644 project/ticket-010/intent.json create mode 100644 project/ticket-010/preprompt.md diff --git a/project/ticket-010/README.md b/project/ticket-010/README.md new file mode 100644 index 0000000..577d82d --- /dev/null +++ b/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) diff --git a/project/ticket-010/ai-codex-logs.txt b/project/ticket-010/ai-codex-logs.txt new file mode 100644 index 0000000..e69de29 diff --git a/project/ticket-010/ai-codex.md b/project/ticket-010/ai-codex.md new file mode 100644 index 0000000..c491931 --- /dev/null +++ b/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. diff --git a/project/ticket-010/changelog.md b/project/ticket-010/changelog.md new file mode 100644 index 0000000..f61ef02 --- /dev/null +++ b/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. diff --git a/project/ticket-010/intent.json b/project/ticket-010/intent.json new file mode 100644 index 0000000..0a9a2ee --- /dev/null +++ b/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"} + ] + } +} diff --git a/project/ticket-010/preprompt.md b/project/ticket-010/preprompt.md new file mode 100644 index 0000000..720b070 --- /dev/null +++ b/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. From a059d7a9e00498db7f60d449b213ab4a7ec4cbd0 Mon Sep 17 00:00:00 2001 From: Tom Softreck Date: Sun, 30 Aug 2026 13:43:36 +0200 Subject: [PATCH 2/2] feat: version Estimation v2 performance contract [ticket-010] --- VERSION | 2 +- models/process-resource-sample.v2.schema.json | 91 +++++++++++++++++++ operations/index.json | 9 +- pyproject.toml | 4 +- 4 files changed, 102 insertions(+), 4 deletions(-) create mode 100644 models/process-resource-sample.v2.schema.json diff --git a/VERSION b/VERSION index 6e8bf73..0ea3a94 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -0.1.0 +0.2.0 diff --git a/models/process-resource-sample.v2.schema.json b/models/process-resource-sample.v2.schema.json new file mode 100644 index 0000000..b6dc5a7 --- /dev/null +++ b/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} + } + } + } + } + } +} diff --git a/operations/index.json b/operations/index.json index a1d2dc1..64ec87d 100644 --- a/operations/index.json +++ b/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." } ] } diff --git a/pyproject.toml b/pyproject.toml index 664377a..72c7f59 100644 --- a/pyproject.toml +++ b/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"